SMTP and local email

Keycloak sends account setup and recovery emails. The API sends existing-account workspace invitations. Both use the configured transport; the panel never holds mailbox credentials.

Authenticated SMTP

Configure a verified hostname, sender and credentials in the ignored .env:

Setting	Required value
SMTP_HOST	Hostname covered by the server certificate.
SMTP_PORT	Implicit TLS submission port, normally 465.
SMTP_SECURITY	tls
SMTP_FROM	Sender address permitted by the server.
SMTP_USERNAME, SMTP_PASSWORD	Mailbox or SMTP credentials.
SMTP_ALLOW_INSECURE_LOCAL	false

Quote passwords containing spaces or # in the environment file. Never include them in a command or a support transcript. Run pnpm auth:configure after changing settings and restart the API so both senders use the updated configuration.

tls means TLS from connection start. This bootstrap does not offer authenticated STARTTLS submission on port 587. Certificate and hostname checks remain enabled.

Local Mailpit

Use the optional mailbox in Local setup, or reuse an existing local Mailpit instance whose address and ports you have verified.

Plaintext transport requires SMTP_SECURITY=none, SMTP_ALLOW_INSECURE_LOCAL=true and empty credentials. It is accepted only for supported local hostnames outside production.

If Keycloak and the host API need different addresses to the same local mailbox, set SMTP_APP_HOST and SMTP_APP_PORT for the API. Do not use those overrides for authenticated remote SMTP.

Validate delivery

Send an intentional invitation to an address you control. Verify that the message arrives and the account or workspace flow completes. The application’s accepted delivery status means SMTP acceptance, not inbox placement.

For remote delivery, the mail operator should check certificate validity, sender authorization and the domain’s SPF, DKIM and DMARC configuration. Those records depend on the actual sending infrastructure; do not copy another installation’s DNS records.

Failed or uncertain delivery

Fix SMTP reachability, certificate or credential errors first. Check the mailbox for delayed delivery. For a workspace invitation, use its explicit Resend control; for an incomplete operator invitation, use --resend as described in Operator invitations.

Test suites always use an isolated Mailpit instance and never reuse real SMTP credentials or clear existing inboxes.