Skip to content

ADR 0046

github-actions[bot] edited this page Nov 22, 2026 · 2 revisions

Status: accepted · Built: done · Date: 2026-11-22

The Mail phase of the ecosystem's ADR 0005. Built: the mail service (smtp-server and nodemailer) on the edge network; a token per app in secrets.json, SMTP_URL and MAIL_FROM in the app's env; the senders file the agent writes; the email entry in the legal facts; GET /apps/:name/mail and the Email section of the app's Domains page. Changed after acceptance (0.14.1): MAIL_FROM is the instance's sender, noreply@<APPS_DOMAIN>, shared by every app, so a provider verifies one domain; every app may send from APPS_DOMAIN as well as its own hosts. Later: an app with its own domain sends as noreply@ once the provider has verified it, through Lettermint's API, falling back to the instance's sender until then. Not yet: Spotstrap's words for the email entry (it shows a generic sentence until then), and a sender domain per hosted instance, which comes with the Studio.

Apps send mail through the instance's relay, to one provider

Context

Apps need to send email: sign-up confirmations, password resets, notices. The app contract reserved SMTP_URL and MAIL_FROM from the start (ADR 0034), and spotcraft dev already points them at Mailpit. The ecosystem's ADR 0005 asks for one EU provider (Lettermint first), apps sending through the instance, allowed senders per app, and no per-app settings.

Giving every app the provider's own credentials would let any app send as any other, and would put the provider's key in every app's env.

Decision

  • One relay per instance: the mail service, an SMTP server on the edge network that apps reach as mail:2525. It forwards each message unchanged to the one provider in MAIL_SMTP_URL, over TLS.
  • Each app signs in as itself. The agent makes a token per app on its first deploy, keeps it in secrets.json, and gives the app SMTP_URL=smtp://<name>:<token>@mail:2525 and MAIL_FROM=noreply@<its public host>.
  • An app sends only from its own hosts. The agent writes the relay's senders file (each app's token as a hash, and its hosts) before a new version starts, after a removal, and at start. Any address on those hosts is allowed; there is no sender setting.
  • Fixed limits: 60 messages a minute per app, 50 recipients, 10 MB.
  • Without a provider, the relay still accepts sign-ins and answers 451 (try later), so apps behave the same everywhere.
  • The legal facts gain an email entry with the provider (Lettermint B.V., Netherlands, from its host), basis contract.
  • The dashboard shows each app's sender and the SPF and DMARC records DNS has for its hosts. DKIM keys belong to the provider, whose dashboard shows them.
  • Locally, Mailpit stays the relay (spotcraft dev).

Consequences

  • An app's token can't send as another app, and leaking it can't reach the provider directly.
  • The provider's key lives in one place on the server, .env.
  • The owner sets up SPF, DKIM and DMARC for each sending domain at the provider and in DNS; the dashboard shows what receivers will find.
  • Hosted instances will use Kodentuzo's Lettermint account, with a sender domain per instance; that comes with the Studio.
  • Traffic between an app and the relay stays on the Docker network without TLS.

Clone this wiki locally