# Configure outbound email

> Set up SMTP delivery for verification and account emails on your self-hosted instance.

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

> **Branding mail for a custom domain?**
>
> See [Email sender](/en/custom-domains/email-sender) for that separate feature. This guide configures the instance’s delivery transport.

## 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:

```dotenv
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](/en/reference/environment-variables).                                |
| `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](/en/install/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](/en/install/reverse-proxy-and-tls).

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.

## Related

* [Environment variables](/en/reference/environment-variables)
* [Configure authentication](/en/configure/authentication)