Send email
Send emails from your VM
Your VM can send plain-text emails.
## Request
```bash
curl -X POST http://169.254.169.254/gateway/email/send \
-H "Content-Type: application/json" \
-d '{
"to": "odysseus@example.com",
"subject": "Build Complete",
"body": "Your build finished successfully!"
}'
```
Required fields: `to`, `subject`, `body`
Optional fields: `reply_to`, `in_reply_to`, `references`, `attachments`
Sending is rate-limited.
## Attachments
Pass an `attachments` array. Each entry needs a `filename` and
base64-encoded `content`; `content_type` is optional.
```bash
curl -X POST http://169.254.169.254/gateway/email/send \
-H "Content-Type: application/json" \
-d '{
"to": "odysseus@example.com",
"subject": "Report",
"body": "Latest numbers attached.",
"attachments": [
{
"filename": "report.csv",
"content": "'"$(base64 -w0 report.csv)"'"
}
]
}'
```
Attachment count and size are limited.
## Allowed recipients
To prevent spam, `to` must be one of:
- you
- a member of your exe.dev team
- someone that has logged into your private-but-shared VM using exe.dev auth
- someone who has emailed your VM (see below)
## Replying to people who email your VM
If your VM [receives email](/docs/receive-email), it may reply to people who
email it. By default the permission is scoped to the thread: set `in_reply_to`
(or `references`) to the `Message-ID` of a message the sender sent your VM
within the last 30 days. Replies sent this way carry a short footer telling
the recipient how to widen or revoke the permission (every message your VM
sends a correspondent carries at least the unsubscribe instruction):
- they can email your VM with subject `subscribe`, after which your VM may
email them directly (no `in_reply_to` needed)
- they can email your VM with subject `unsubscribe`, after which your VM cannot
email them at all — this outranks every other permission, including your own
and your team's, and only another `subscribe` from that same address lifts it
The subject must be exactly the command word; `Re: subscribe` does not count,
so that hitting Reply can never subscribe someone by accident.
To prevent spoofed or replayed mail from opening this door, the inbound email
must carry a valid DKIM signature that is aligned with its From domain and
covers a To/Cc header naming your VM (nearly all real mail providers do
this). The subject and `Message-ID` must be signed too, or they are ignored.
Mail that can't be verified is still delivered to your VM, but does not make
its sender replyable; the send endpoint's error message says why a given
address isn't sendable.
Reply permissions are cleared when you run `share receive-email <vm> off`,
when the VM is deleted, and when it changes owner. An `unsubscribe` outlives
the off/on cycle and a change of owner: neither lets your VM mail someone who
asked it to stop. Whether your VM may email someone is that person's call, so
they are also the only one who can reverse it.
While inbound email is off, your VM cannot email correspondents at all —
their `unsubscribe` reply would have nowhere to land.
You can also restrict who your VM may email at all:
```
ssh exe.dev share receive-email <vm> --reply-policy=<policy>
```
where `<policy>` is `all` (default: owner, team, share recipients, and
correspondents), `known` (no correspondents), `owner`, or `none`.
## Response
```json
{"success": true}
```
or
```json
{"error": "error message"}
```