Configure Mastodon to send email over SMTP

Mastodon sends sign-up confirmations, password resets and notification emails from its Sidekiq workers, using the `SMTP_*` variables in `.env.production`. `SMTP_FROM_ADDRESS` falls back to `notifications@localhost`, which Unitpost rejects, so set it to an address on your verified domain.

1. 1

   Create a send-only key

   In Unitpost, open Settings → SMTP and create a send-only key. Verify the domain you'll use in SMTP_FROM_ADDRESS.

2. 2

   Set the SMTP variables

   Edit .env.production in the Mastodon directory. SMTP_ENABLE_STARTTLS=always requires the upgrade on 587; the default auto only tries it when offered.

   Env

   SMTP_SERVER=smtp.unitpost.com
   SMTP_PORT=587
   SMTP_LOGIN=unitpost
   SMTP_PASSWORD=pk_live_...
   SMTP_AUTH_METHOD=plain
   SMTP_ENABLE_STARTTLS=always
   SMTP_FROM_ADDRESS=notifications@yourdomain.com

   For port 465, use SMTP_PORT=465 and SMTP_TLS=true, and remove SMTP_ENABLE_STARTTLS: STARTTLS and implicit TLS can't be on together.

3. 3

   Restart Sidekiq and reload the web process

   Sidekiq delivers the mail, so it has to restart to load the new values. The web process reloads without downtime.

   Shell

   sudo systemctl restart mastodon-sidekiq
   sudo systemctl reload mastodon-web

4. 4

   Send a test

   A running server has no test button. Sign out and use Forgot your password? on the sign-in page with an account whose inbox you can read. On a fresh install, RAILS_ENV=production bin/rails mastodon:setup offers to send a test email after its SMTP questions.

5. 5

   If nothing arrives

   Failed deliveries wait as retries in the Sidekiq dashboard at /sidekiq, with the SMTP reply. 550 5.7.1 means SMTP_FROM_ADDRESS isn't on a verified domain; 535 5.7.8 means SMTP_LOGIN isn't unitpost.