Authentik Uses Mailpit in Staging: Launch a Real SMTP Relay Safely

Treat outbound email as four separate release gates

Effective environment

The deployed release must use an owned relay, not inherited Mailpit defaults or an example hostname.

Credential propagation

The source Secret, Helm render, generated config Secret, and current Authentik worker are four different states.

Sender authentication

Provider verification plus same-message SPF or DKIM alignment must produce DMARC pass for the visible From domain.

Verification outcome

Command success, provider acceptance, recipient-server delivery, mailbox visibility, and link completion are not interchangeable.

What the reviewed project source proves

At BeekeepingIT revision a0d81fe2a27eb549581af6083bac82bb3ed0f94b, the umbrella chart defaults Authentik to mailpit:1025 with no authentication. The staging overlay does not override that email block or disable Mailpit, so its verification messages remain inside the cluster. The production overlay disables Mailpit but still uses smtp.beekeepingit.example and no-reply@beekeepingit.example placeholders; its own header also says no production cluster or domain exists yet.

The config template uses Helm lookup to read beekeepingit-authentik-email-credentials and copy its username and password into beekeepingit-authentik-config. That makes ordering operationally important: the source Secret must exist before a successful render, the Helm release must reconcile afterward, and the Authentik worker must consume the resulting Secret revision. Merely creating the source Secret proves none of the later boundaries.

The accepted ADR makes email verification part of login for unverified non-superusers. A relay outage therefore is not just a notification problem: it can block those users at the email stage. Keep the documented superuser path and do not enable a larger cohort until the current worker completes one real end-to-end test.

Choose the relay by evidence, not by brand

1. Confirm the provider's DPA, data region, subprocessors, retention, and deletion controls against the project's GDPR requirements.
2. Require authenticated SMTP on the exact port and TLS mode supported by Authentik. Port 587 normally means explicit STARTTLS; port 465 normally means implicit TLS.
3. Require custom From and DKIM identities, a documented Return-Path, bounce and complaint events, suppression visibility, credential rotation, and stable message identifiers.
4. Use a dedicated transactional subdomain when it simplifies ownership. Do not overwrite an existing mailbox MX or copy another sender's SPF include.
5. Start with the expected verification volume. Dedicated IP space and warmup are usually unnecessary for a low-volume authentication stream unless the provider requires them.

Prove Secret propagation without exposing a value

A safe runbook should report key presence, resource revision, and pod rollout only. It should never print decoded values. One defensible sequence is:

1. Create or rotate the out-of-band credential Secret in the exact target namespace before Helm reconciliation.
2. Reconcile the Flux HelmRelease or perform the approved Helm upgrade. A local client-only template cannot prove what a live lookup returned.
3. Check that the generated config Secret contains the expected AUTHENTIK_EMAIL__* key names and intended non-secret endpoint.
4. Prove the server and worker rolled after that update. Environment variables do not mutate inside an already-running process when a Secret object changes.
5. Keep the credential Secret and all decoded values out of Git, issue comments, CI artifacts, screenshots, and application logs.

Use one message to cross every boundary

1. From the current Authentik worker, run ak test_email <controlled-recipient>. To test a specific Email stage, add -S <stage-name>.
2. Record a bounded result: command completed or failed, failure class if any, and the provider's opaque message identifier. Do not retain the recipient or message body in public evidence.
3. At the provider, classify the same attempt as accepted, delayed, bounced, suppressed, rejected, or delivered to the recipient server.
4. At a trusted receiver, require a visible message plus dmarc=pass from aligned SPF or DKIM. DNS presence alone is not same-message proof.
5. Open only the newest one-time link once and prove the intended Authentik flow completes. Then test a bounded cohort with monitoring and rollback.

Release criteria that cannot hide a Mailpit fallback

1. Dev and CI still use Mailpit, while the target staging or production release uses one owned relay endpoint.
2. No example hostname, example From address, or ambiguous TLS combination is present in the effective release.
3. The credential Secret predates the successful Helm reconciliation, and current Authentik pods postdate the generated config Secret update.
4. The provider verifies the exact sender and public records; one fresh receiver result reports aligned DMARC pass.
5. One controlled verification message is provider-traceable, receiver-visible, and its newest link completes exactly once.
6. The runbook covers rotation, provider outage, delayed or bounced mail, suppression removal, superuser recovery, and rollback to a safe closed state.