Configure outbound email

Deze inhoud is nog niet beschikbaar in uw taal.

Set up SMTP delivery before users depend on verification or account-recovery emails.

Prerequisites

SMTP credentials and a sender address authorized by your mail provider.
Network access from the application or email worker to the SMTP service.
A working public HTTPS hostname for links in account emails.

Steps

1. Configure the transport

Supply these variables through your deployment’s protected environment configuration, replacing the example host, credentials and sender:

EMAILER_MODE=smtp
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=replace-with-smtp-username
SMTP_PASSWORD=replace-with-smtp-password
SMTP_AUTH=login
SMTP_TLS=true
SMTP_SSL=false
FROM_EMAIL=secrets@example.com
FROM_NAME=Example Secrets

Match the provider’s authentication and encryption settings. This example uses STARTTLS. For a provider requiring implicit TLS, commonly on port 465, use its port and SMTP_SSL=true; that option takes precedence over STARTTLS. The example is environment-file syntax, not a shell command. Use your deployment system’s quoting rules when supplying a value containing spaces.

SMTP is the shipped default, but replace both placeholder values: SMTP_HOST=smtp.provider.com and FROM_EMAIL=CHANGEME@example.com. Do not treat a successful application boot as a delivery test.

For a different transport, set EMAILER_MODE explicitly:

Value	Delivery behavior
`smtp`	SMTP using the settings above.
`ses`, `sendgrid`, `lettermint`, `smtp2go`	Provider-specific delivery; configure that provider’s credentials using the environment reference.
`logger`	Prints the message, including account links and bodies, to standard output instead of sending it. Restrict access to those logs.
`disabled` or `none`	Does not transmit mail. Use only when the intended account flows do not depend on emailed links.

An unknown mode logs Unknown provider and falls back to logger, so a spelling error can leave a running instance that sends no mail. A non-empty mode also takes precedence over credential auto-detection and the RACK_ENV=test logger fallback. Custom sender-domain provisioning is separate: CUSTOM_MAIL_PROVIDER selects that provider, not the delivery transport.

2. Apply the configuration to the sending process

Restart the application and any email workers that consume this configuration. If you enabled background jobs, confirm the workers and broker are running; Run as a service describes the deployment components.

3. Send an account email

Use a test account and request a verification or password-reset email through the normal interface. Use only accounts and mailboxes you control.

Verify it worked

Confirm actual receipt, the sender address, and the hostname in the link. Follow the link and finish the account action. A success message in the browser alone does not establish delivery.

Troubleshooting

Connection failure: check outbound network access, host and port from the sending service.
Authentication rejected: check the provider’s SMTP credentials and permitted authentication method.
No email, but messages appear in logs: check that EMAILER_MODE is not logger, which is for development and does not deliver mail.
Wrong link hostname: review the deployment’s public-host and reverse proxy configuration.

Look for [mail] Delivery failed via SMTP in the sending process’s output; other transports substitute their backend name. Recipients are obscured, so searching for a complete email address can miss the entry. Backend selection ([mail] Using smtp delivery backend) and normal delivery records are info-level messages; enable DEBUG_APP=1 temporarily if your logging configuration hides them.

Do not assume a failed send will retry. The RabbitMQ email worker retries transient delivery errors and sends exhausted or permanent failures to its dead-letter queue. The publisher’s in-process fallback has no retry loop. When jobs are disabled or the broker is unavailable, investigate that fallback’s output as well as the web request; a browser success message is not proof of receipt.