Skip to content

Email

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 open a shell as that user.

Check receiving and reply settings from your local terminal.

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.

PolicyAllowed recipients
all (default)Everyone allowed by known, plus verified subscribers and senders in eligible threads while receiving is on.
knownThe Computer's owner, active organization members and people with a direct share on the Computer, using their verified email addresses.
ownerThe Computer's owner at their verified email address.
noneSending 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 from your local terminal.

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.

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.

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 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.