Repository navigation
ADR 0046
Status: accepted · Built: done · Date: 2026-11-22
The Mail phase of the ecosystem's ADR 0005. Built: the
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.
-
One relay per instance: the
mailservice, an SMTP server on theedgenetwork that apps reach asmail:2525. It forwards each message unchanged to the one provider inMAIL_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 appSMTP_URL=smtp://<name>:<token>@mail:2525andMAIL_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
emailentry with the provider (Lettermint B.V., Netherlands, from its host), basiscontract. - 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).
- 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.
Published from docs/. Edit the files there; changes here are overwritten.