mailer.Send sends a message from the app's one address to the domains its permission list
allows, and mailer.List and mailer.Get read the app's mailbox. The runner checks every message
against the mail rules, and every message carries an idempotency key, so a retried request does not
mail again while the runner remembers the key: on the platform, the app's last 10 000 keys within
24 hours.
Declaring mail
email:
from: people@acme.example # the one address the app sends from
to_domains: [acme.example] # the only domains it may send to
Without an email section, every mail call fails with E-MAN-012.
Sending
_, err := mailer.Send(ctx, mailer.Message{
IdempotencyKey: "user-" + u.Login,
To: []mailer.Address{{Address: p.d.TeamAddress}},
Subject: "User " + u.Login + " added",
Text: fmt.Sprintf("%s (%s) joined the team %s.\n", u.Name, u.Login, u.Team),
})
Send returns the message's id.
- The sender is always
email.from.FromNamesets only the name shown with it. - The domain of every recipient in
To,CcandBccmust equal one inemail.to_domainsexactly, so a subdomain is not enough, and so must the domain ofReplyTo, unless it is the app's own address (E-MAIL-003). - Addresses are plain ASCII addresses such as
name@acme.example, with the person's name inName, never inside the address (E-MAIL-002). A message needs at least one recipient. - A message has
Text,HTMLor both (E-MAIL-006), and may carryAttachments, each with aFilename, aContentTypeand itsData. Headersmay set onlyIn-Reply-To,References,List-Id,List-Unsubscribe,List-Unsubscribe-Post,Auto-SubmittedandPrecedence, each with printable ASCII only, which is sent as it is; the runner writes the envelope headers, such asFrom,ToandSubject, from the message's fields. A line break or other control character in a header field, a name or an attachment's name is refused, so no one can add hidden recipients (E-MAIL-004).- One message goes to at most 50 recipients, carries at most 20 attachments and is at most 10 MiB (E-MAIL-005). Save large files in a file store instead.
The idempotency key
IdempotencyKey is required: a stable name of what the message is about, 1 to 128 visible ASCII
characters without spaces, such as invoice-42-reminder (E-MAIL-001). Sending the same key again
sends nothing and returns the first message's id, as long as the runner remembers the key: on the
platform, the app's last 10 000 keys within 24 hours, until the runner restarts, and in
aicoded dev until it restarts. A retry after that sends the message again, and so does the retry
of a send that failed. Rarely, when the runner cannot tell whether a message went out, as when the
mail server's answer is lost, its retry sends it a second time. While 10 000 of the app's messages
are still being sent, a message with a new key is refused (E-MAIL-010).
- Name the event, not the attempt:
user-alicefor "alice was added", never a random value or the time. - When the key must come from what a viewer wrote, hash it: the contact form of the people example uses the first 32 hex digits of the SHA-256 of the viewer, the topic and the message, so the same message sent twice within a day is mailed once and the key holds no personal data.
After a write
Send the mail after the data it tells about is committed. ProcessAdd in the people example
commits the new user and its photos first, then mails the team. If the mail fails, the user stays
added, and the key user-<login> makes sure the team hears of each user once, however often it is
sent while the runner remembers the key.
The mailbox
The app has one mailbox, the email.from address, with the folders mailer.Inbox,
mailer.Archive and mailer.Trash (E-MAIL-007).
| Call | Does |
|---|---|
mailer.List(ctx, folder, offset, limit) |
a page of a folder, newest first, and the number of messages in it; at most 100, and a limit of 0 means 50 |
mailer.Get(ctx, id) |
a whole message: the summary, Cc, ReplyTo, Text, HTML, Attachments and Headers |
mailer.Move(ctx, id, folder) |
moves a message to another folder |
mailer.Delete(ctx, id) |
removes a message |
An unknown id is mailer.ErrNotFound. A mailer.Get can be refused with E-MAIL-010 while other
reads of the mailbox are under way: read the message again.
mail, total, err := mailer.List(ctx, mailer.Inbox, 0, 50)
Traces
Every call is a span, mailer.send, mailer.list, mailer.get, mailer.move or
mailer.delete. Outside aicoded dev, a failed call records only its status and error code,
such as invalid_argument E-MAIL-003, since the runner's message may name a recipient's domain.
See telemetry.
In aicoded dev
Mail is caught instead of sent. It is still checked against the mail rules and the permission
list, and kept in memory while aicoded dev runs: the last 1000 messages of each app, also
across restarts of the app.
- The Mail page of the dev UI shows what each app sent and has in its mailbox. A message's HTML part shows in a sandboxed frame that runs no script and loads nothing from the network.
- "Simulate inbound mail" on the dev UI, or the
mail_receivetool ofaicoded mcp, puts a message in an app's inbox. - The
mail_listandmail_gettools let your AI assistant read the caught mail.
See aicoded dev.
See also
- The permission list: the
emailsection. - people/pages/users/add/dataprovider.go: mail after a write.
- people/pages/contact/dataprovider.go: a key made from what a viewer wrote.
- Send mail after a write: commit, then mail with an idempotency key.