Email sending

Your app sends email for sign-up codes, password reset codes and security alerts, such as "a passkey was added to your account". On your computer, nothing leaves your machine: every email goes to a local inbox called Mailpit. In production, the app sends real email through a provider: Resend or any SMTP server.

What Mailpit is#

Mailpit is a small program that pretends to be an email server. Your app hands it emails exactly as it would hand them to a real provider, and Mailpit keeps them in an inbox you open in your browser, instead of delivering them.

• Why you need it: to sign up on your own app you need the 6-digit code from the verification email. Mailpit shows it to you without a real email account, and you can't email a real person by mistake.
• Where it comes from: aps dev starts it in Docker from your app's compose.yaml, next to PostgreSQL (image axllent/mailpit).
• Where to see it: http://127.0.0.1:8025. The app sends to it on port 1025.
• If you removed it: in development, emails would fail to send and stay queued for retries; nobody could finish sign-up locally.
• In production: never. The app refuses to start with MAIL_DELIVERY=mailpit when APP_ENV=production.

Option 1: Resend (recommended)#

Resend is an email service with a simple API. You need one value from it: an API key.

New Full apps already use Resend. If you switched to SMTP earlier, switch back with aps add mail --provider resend.

Option 2: SMTP#

SMTP is the standard way to send email, supported by every provider: Amazon SES, Postmark, Mailgun, Google Workspace or your own mail server. Switch your app to it once:

aps add mail --provider smtp

aps asks for each value, hides the password as you type it, and saves secrets only in .env. Run it inside your app, with no uncommitted changes. It changes internal/app/infra_mail.go, the email block of .env.example, apistock.yaml and go.mod; commit the result.

Where each provider shows these values:

Whatever the provider, verify your sending domain there first, as with Resend.

Set the sender address#

The sender's name and address aren't environment variables: they're runtime settings, which an administrator changes while the app runs.

Sign in as an administrator (how), keep the token in $TOKEN, then:

curl -X PUT http://127.0.0.1:8080/ops/settings/mail.from_email \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"value": "hello@example.com", "version": 0, "reason": "our domain is verified"}'

version is 0 the first time. If the setting was changed before, read its current version with GET /ops/settings/mail.from_email first: the app refuses a stale version, so two administrators can't overwrite each other by accident.

Check it works#

1. See what the app will use:

   terminalCopy

   curl http://127.0.0.1:8080/ops/mail -H "Authorization: Bearer $TOKEN"
   

   jsonCopy

   {"provider": "resend", "delivery": "mailpit", "details": {"api_key": "missing"}, "from_name": "acme-api", "from_email": "no-reply@example.com"}
   

   delivery is mailpit or provider. details says whether the key or SMTP login is set, never its value.

2. Send yourself a test email:

   terminalCopy

   curl -X POST http://127.0.0.1:8080/ops/mail/test \
     -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
     -d '{"to": "you@example.com"}'
   

   The answer is 202 with {"status": "queued", …}: the email is queued, and a background job delivers it within seconds. In development, open http://127.0.0.1:8025 to see it.

3. If it doesn't arrive, look at the delivery job:

   terminalCopy

   curl "http://127.0.0.1:8080/ops/jobs/runs?kind=apistock.mail.send" -H "Authorization: Bearer $TOKEN"
   

If something goes wrong#

Temporary failures retry up to 8 times, and each email is sent at most once even when retried. Permanent refusals stop straight away, so you see the reason instead of waiting for retries.