aicoded.dev

Mail

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

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.

See aicoded dev.

See also

Markdown · Source on GitHub · framework f46741f