Sign in to fill these examples with your own keys. Sign in Start free trial

Send emails with Mastodon

Point Mastodon's SMTP settings at PostShiba.

What you'll build

A self-hosted Mastodon server that sends its sign-up confirmations, password resets, and notification emails through PostShiba over SMTP.

Before you start

  • A Transactional cluster. Server notification mail belongs on a transactional cluster, and the type is locked after create. See Clusters.
  • An SMTP username and password. Open your cluster in the dashboard, go to its SMTP credentials, and choose Create SMTP credential. Copy the password right away, because it is shown once. You can also use the SMTP credentials API.
  • A verified sending domain. See Add and verify a domain. SMTP_FROM_ADDRESS must be on it.
  • A cluster that is ready to send (sending_ready is true).
  • Shell access to the Mastodon server, so you can edit .env.production.

Install

Nothing to install. Mastodon has SMTP support built in.

Send your first email

  1. Set these variables in .env.production. On a standard install it is /home/mastodon/live/.env.production. SMTP_ENABLE_STARTTLS=auto upgrades the connection with STARTTLS on port 587, and SMTP_OPENSSL_VERIFY_MODE=peer keeps certificate checks on. Leave SMTP_TLS and SMTP_SSL unset, because they are for port 465.
.env.production
1SMTP_SERVER=smtp.postshiba.com 2SMTP_PORT=587 3SMTP_LOGIN=smtp_9 4SMTP_PASSWORD=YOUR_PASSWORD 5SMTP_FROM_ADDRESS=hello@mail.example.com 6SMTP_AUTH_METHOD=plain 7SMTP_ENABLE_STARTTLS=auto 8SMTP_OPENSSL_VERIFY_MODE=peer
  1. Restart Mastodon so it reads the new settings. Sidekiq sends the mail, so restart it as well as the web process.
restart.sh
1sudo systemctl restart mastodon-web mastodon-sidekiq

With Docker Compose, run docker compose up -d from the directory with docker-compose.yml. It recreates the web and sidekiq containers with the new .env.production. docker compose restart does not reload it.

  1. Mastodon has no test email button. Sign out, choose Forgot your password? on the sign-in page, and enter your own address. The reset email goes through PostShiba and shows under Events in the dashboard.

Every SMTP setting is on Send emails with SMTP.

Troubleshooting

Mastodon 4.4 and later can send server announcements and terms of service updates through a second set of BULK_SMTP_* variables. They reach every user at once. If you leave them unset, those emails use the settings above and count against the same cluster's caps. If they would go over, set BULK_SMTP_* to a credential from a second cluster sized for them. When a cap is full, SMTP answers 451 4.7.0 hourly send limit reached or 451 4.7.0 daily send limit reached and does not keep the message. See What happens at your cap.

What you see in the Sidekiq log What to do
Authentication fails Check SMTP_LOGIN and SMTP_PASSWORD, and set SMTP_AUTH_METHOD=plain. PostShiba accepts AUTH PLAIN only. Restart Sidekiq after each change.
550 unverified domain or 550 from header not aligned with verified domain Set SMTP_FROM_ADDRESS to an address on your verified domain. If you set SMTP_RETURN_PATH, it must be on that domain too.
550 domain_suspended The From domain is paused. Resume it from Managing domains.
550 kyc_required Your team is pending production approval. Until then, send only to team members, live inbox addresses, and inbox forward-to addresses. See Does PostShiba require production approval?.
550 suppressed or 550 firewall: <rule> The recipient is on the suppression list or failed an email firewall check. PostShiba suppresses addresses that hard bounce or report spam.
451 4.7.0 hourly send limit reached or 451 4.7.0 daily send limit reached The cluster is at its cap and did not keep the message. Retry later, or resize the cluster.

Next steps