Set up SMTP for self-hosted Sentry

Self-hosted Sentry emails issue alerts, weekly reports and the links that verify a user's email address. Outbound mail comes from the `mail.*` keys in `sentry/config.yml`, which point at the bundled `smtp` relay container until you change `mail.host`. The catch: `sentry/sentry.conf.py` builds `mail.from` from `SENTRY_MAIL_HOST`, and that wins over anything you put in `config.yml`.

1. 1

   Create a send-only key

   In Unitpost, open Settings → SMTP and create a send-only key. Copy it now; it's shown once. Mail goes out as sentry@ plus the domain in SENTRY_MAIL_HOST, so that domain must be verified.

2. 2

   Set the From domain in .env

   sentry/sentry.conf.py sets mail.from to sentry@ plus SENTRY_MAIL_HOST. Set that variable in the .env at the root of your self-hosted checkout to your verified domain.

   Env

   SENTRY_MAIL_HOST=yourdomain.com

   Want another address, such as alerts@yourdomain.com? Delete the mail.list-namespace and mail.from lines under # Mail # in sentry/sentry.conf.py, then set mail.from in config.yml.

3. 3

   Point mail.* at Unitpost

   In sentry/config.yml, replace mail.host: 'smtp' (the bundled relay) and uncomment the connection keys. mail.use-tls is STARTTLS on port 587 and mail.use-ssl is implicit TLS on 465. The file warns they must not appear together, so uncomment only one.

   YAML

   mail.backend: 'smtp'
   mail.host: 'smtp.unitpost.com'
   mail.port: 587
   mail.username: 'unitpost'
   mail.password: 'pk_live_...'
   mail.use-tls: true

   For port 465, set mail.port: 465 and mail.use-ssl: true, and leave mail.use-tls commented out.

4. 4

   Rebuild and restart

   The containers read .env and config.yml when they start. Re-run the installer from your self-hosted checkout; it rebuilds and restarts them.

   Shell

   ./install.sh

5. 5

   Send a test from the admin Mail page

   As a superuser, open /manage/status/mail/ on your instance. SMTP Settings lists the host, port, username and STARTTLS or SSL flag that loaded. Under Test Settings, the Send a test email button mails your own account address; find it in Unitpost Emails.

6. 6

   If the test fails

   535 5.7.8 Username must be 'unitpost' means mail.username holds an email address. 550 5.7.1 means the From domain isn't verified, so check SENTRY_MAIL_HOST. A hang on port 465 usually means mail.use-tls is set where mail.use-ssl belongs.