When your Mastodon instance stops sending emails for password resets, confirmations, or notifications, users cannot complete registration or recover accounts. This problem usually stems from incorrect SMTP settings, firewall blocks, or authentication failures with your email provider. This article explains the common causes of SMTP mail delivery failures on Mastodon and provides step-by-step fixes to restore email functionality.
Key Takeaways: Mastodon SMTP Mail Delivery Fix
- Environment variables (.env.production): SMTP_HOST, SMTP_PORT, SMTP_LOGIN, SMTP_PASSWORD must match your email provider’s exact requirements.
- Docker restart: Run
docker-compose restart webafter changing SMTP settings to apply new variables. - Firewall port 587 or 465: Outbound SMTP traffic must be allowed; test with
telnet smtp.example.com 587from the server.
Why Mastodon SMTP Mail Delivery Fails
Mastodon uses the Action Mailer library in Ruby on Rails to send emails. The mailer reads SMTP credentials from environment variables defined in the .env.production file. If any variable is missing, misspelled, or contains a typo, the mailer cannot authenticate with the SMTP server. Common mistakes include using port 25 which many ISPs block, forgetting to enable an app password for services like Gmail or Outlook, and setting the wrong authentication method. Additionally, the server must have outbound access to the SMTP host on the chosen port. Without this access, Mastodon cannot establish a TCP connection, and the mail queue fills up with failed delivery attempts.
Steps to Fix Mastodon SMTP Mail Delivery
Follow these steps in order. Test after each major change to isolate the issue.
- Verify SMTP environment variables in .env.production
SSH into your Mastodon server and open the.env.productionfile with a text editor. Confirm that these variables exist and are correct:SMTP_SERVER=smtp.example.comSMTP_PORT=587SMTP_LOGIN=your_email@example.comSMTP_PASSWORD=your_app_passwordSMTP_FROM_ADDRESS=MastodonSMTP_AUTH_METHOD=plainSMTP_OPENSSL_VERIFY_MODE=peer
If you use STARTTLS, setSMTP_ENABLE_STARTTLS_AUTO=true. For SSL-only connections on port 465, setSMTP_ENABLE_STARTTLS_AUTO=falseandSMTP_TLS=true. - Restart Mastodon services after editing .env.production
Rundocker-compose restart webif you use Docker, orsystemctl restart mastodon-webfor a systemd setup. This reloads the environment variables into the running processes. - Test SMTP connectivity from the server
Use telnet to check basic connectivity:telnet smtp.example.com 587. If the connection succeeds, you will see the SMTP banner. If it fails, check your firewall rules to allow outbound traffic on port 587 or 465. Also verify that your email provider does not block connections from your server’s IP address. - Send a test email from the Mastodon console
Open the Rails console withdocker-compose run --rm web rails corcd /home/mastodon/live && RAILS_ENV=production bin/rails c. Run:ActionMailer::Base.mail(from: "test@yourdomain.com", to: "your_email@example.com", subject: "Test", body: "Test").deliver_now
If this succeeds, the SMTP configuration is correct. If it raises an error, note the error message—it often points to authentication or connection issues. - Check the Mastodon mail queue
Rundocker-compose run --rm web rails r "puts Sidekiq::Queue.new('mailers').size"to see how many emails are queued. A high number indicates that previous delivery attempts failed. Clear the queue withdocker-compose run --rm web rails r "Sidekiq::Queue.new('mailers').clear"after fixing the SMTP settings.
If Mastodon Mail Delivery Still Fails After the Main Fix
“Net::SMTPAuthenticationError” or “535 Authentication Failed”
This error means the SMTP server rejected the login credentials. For Gmail, you must use an App Password instead of your regular account password. For Outlook.com, enable SMTP authentication in the Microsoft 365 admin center and generate an app password. Also verify that the SMTP_LOGIN is the full email address, not just the username.
“Connection refused” or “Connection timed out”
The server cannot reach the SMTP host. Check that your firewall allows outbound connections on the SMTP port. Some hosting providers block port 25 by default. Use port 587 or 465 instead. Also confirm that the SMTP_SERVER hostname resolves correctly with nslookup smtp.example.com.
Emails are sent but go to spam
Set up SPF and DKIM DNS records for your sending domain. Add a TXT record for SPF: v=spf1 include:_spf.google.com ~all for Gmail. For DKIM, generate a key in your email provider’s settings and add the public key as a TXT record. Also set the SMTP_FROM_ADDRESS to a domain that matches your Mastodon instance domain to improve deliverability.
| Item | Port 587 (STARTTLS) | Port 465 (SSL/TLS) |
|---|---|---|
| Encryption | Plain connection upgrades to TLS via STARTTLS | SSL/TLS from the start |
| Environment variables | SMTP_PORT=587, SMTP_ENABLE_STARTTLS_AUTO=true |
SMTP_PORT=465, SMTP_TLS=true, SMTP_ENABLE_STARTTLS_AUTO=false |
| Firewall requirement | Outbound TCP on port 587 | Outbound TCP on port 465 |
| Common providers | Gmail, Outlook.com, SendGrid | Amazon SES, Mailgun |
After correcting the SMTP settings, your Mastodon instance can send emails reliably. Monitor the mail queue with the Sidekiq dashboard at /sidekiq on your instance. For high-volume instances, consider using a dedicated email service like SendGrid or Amazon SES to avoid hitting rate limits from free email providers.