# Email

URL: https://heaven.dev/docs/email
Updated: 2026-11-21

Every Computer can receive and send email. An agent can receive a verification code when it signs up for a service, reply to a thread, or send a build notification from the Computer where it runs.

## Receiving email

A Computer named `my-site` receives mail at addresses such as `signups@my-site.heaven.dev`. Ordinary addresses ending in `@my-site.heaven.dev` all deliver to the same mailbox. External services can send to those addresses without a Heaven account or an invitation. Incoming mail is on by default for new Computers, so you can give a service the address as soon as the Computer is running. A copy starts with its source's receiving setting and reply policy.

Read incoming messages in the image login user's `~/Maildir/new` inside the Computer. Each message is a file. Heaven's [browser terminal and SSH connections](https://heaven.dev/docs/connecting) open a shell as that user.

Check receiving and reply settings from your local terminal.

```sh
heaven mail view my-site
```

Run `heaven mail my-site off` to stop receiving or `heaven mail my-site on` to resume it. Turning receiving off clears reply threads and subscriptions. If there are any to clear, Heaven previews the change and asks you to repeat the command with `--yes`.

## Reply policy

The reply policy controls who the Computer can send to. Heaven checks recipients so a Computer can reply to people who wrote to it while limiting unsolicited mail.

| Policy | Allowed recipients |
| --- | --- |
| `all` (default) | Everyone allowed by `known`, plus verified subscribers and senders in eligible threads while receiving is on. |
| `known` | The Computer's owner, active organization members and people with a direct share on the Computer, using their verified email addresses. |
| `owner` | The Computer's owner at their verified email address. |
| `none` | Sending is off. |

To subscribe, a sender emails the Computer with the subject `subscribe`. Heaven verifies the request using the sender's DKIM signature. A sender can opt out by emailing `unsubscribe@my-site.heaven.dev` with the subject `unsubscribe`. Opt-outs override the reply policy.

To reply to a thread, send to the incoming message's `From` address and pass its `Message-ID` as `in_reply_to`. Under `all`, Heaven allows replies for 30 days after receiving an eligible message. To qualify, the message needs an aligned DKIM signature covering `From`, `Subject`, `Message-ID` and the `To` or `Cc` that names the Computer.

Change the policy with [`heaven mail`](https://heaven.dev/docs/reference/computers/mail) from your local terminal.

```sh
heaven mail my-site --reply-policy known
```

## Sending email

Send a plain-text message to one allowed recipient through Heaven's mail service from inside the Computer. The service recognizes the Computer making the request, so your app can send mail using the Computer's identity. This example assumes `alex@example.com` is the Computer owner's address.

```sh
curl http://169.254.169.254/gateway/email/send \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: build-123' \
  -d '{"to":"alex@example.com","subject":"Build complete","body":"All tests passed."}'
```

Mail goes out from `computers@heaven.dev` with the Computer's hostname as the display name. By default, replies go to `yes-reply@my-site.heaven.dev` for `my-site`.

Heaven blocks direct outbound SMTP on TCP port 25 because spam from one Computer can get a shared IP address blocklisted for other customers.

## Delivery status

Save the `id` returned by the send request. Read its status from inside the same Computer.

```sh
curl http://169.254.169.254/gateway/email/status/MESSAGE_ID
```

The Computer's owner or someone with root access can also run [`heaven mail status my-site MESSAGE_ID`](https://heaven.dev/docs/reference/computers/mail-status) from their local terminal.

A `queued` or `submitting` message is still being processed. `provider_accepted` means the sending provider accepted the message. `delivered` means the recipient's mail server accepted it. `bounced` means the sending provider reported a delivery failure. If the send returns `unknown` or the connection drops, check status when you have an ID. To retry an uncertain send within 24 hours, reuse the same request body and idempotency key so Heaven can return the existing result.
