If you’re running your own Mastodon server, email is an essential feature. It is used for account confirmations, password resets, admin notifications, and more.
Unfortunately, Mastodon doesn’t configure your server to handle emails by default. You’ll need to manually add the SMTP credentials from an email provider to handle emails.
In this guide, we’ll walk you through configuring Mastodon SMTP settings to ensure reliable email delivery for your social media instance.
Why Email Setup Is Important in Mastodon
Before we dive into the how-to, here’s why Mastodon SMTP setup matters:
Out of the box, Mastodon doesn’t send emails unless you configure an SMTP server. Without email, users can’t verify accounts, reset passwords, or receive notifications. This makes your instance pretty much unusable for most people.
Let’s fix that with a reliable SMTP setup!
SMTP is the protocol that allows your server to send emails via a mail provider like SendLayer, Gmail, SendGrid, or a self-hosted external SMTP solution.
If you’re looking for a suitable transactional email provider for use with Mastodon, SendLayer is a great choice. It is simple to set up and yet highly secure and powerful.
One of the standout features of SendLayer is its domain reputation protection. It automatically creates a subdomain for your email sending activities, which means your main domain remains protected from any potential deliverability issues. This helps to maintain your sender reputation so your emails stay out of the spam folder.
SendLayer also offers a free trial that allows you to send up to 200 emails, and paid plans start from just $5 a month. This makes it an affordable option whether you’re simply testing during development or need to scale up to sending thousands of emails through your app monthly.
How to Set Up Email in Mastodon With SMTP
Prerequisites
To get started, you’ll need:
- A running Mastodon instance
- Mastodon admin login credentials for SSH access
- Your SMTP provider details (like username, password, SMTP host, and port)
- A verified sending domain with your provider (optional but recommended for deliverability)
If you’re using SendLayer, you’ll need to make sure your domain is set up and verified before proceeding.
Step 1: Connect to Your Mastodon Server
As mentioned, this guide assumes you already have a working Mastodon server. If you’re yet to install Mastodon and configure your server, please refer to Mastodon’s guide on running your own server.
Once your server is ready, you’ll need to connect to it through a CLI. To do so, SSH into your Mastodon server using the command below:
ssh username@your-server-ip
Be sure to replace username and your-server-ip with your actual username and server IP address.
Once connected, navigate to your Mastodon directory (this is usually in the /home/mastodon/live directory):
cd /home/mastodon/live
This will direct you to the folder containing your Mastodon server files.
Step 2: Mastodon Email Configuration
Within your Mastodon files, there’s usually a .env.production file. This file contains all your Mastodon environment variables.
Open it with your preferred editor. Alternatively, you can edit the file from your CLI using the command:
nano .env.production
Once the file is open, scroll down to the email settings section and update the following variables:
SMTP_SERVER=smtp.sendlayer.net
SMTP_PORT=587
SMTP_LOGIN=your-smtp-username
SMTP_PASSWORD=your-smtp-password
[email protected]
SMTP_DOMAIN=yourdomain.com
SMTP_TLS=true
SMTP_AUTH_METHOD=plain
Pro Tip: Sensitive credentials like SMTP username and password should not be pushed directly to your server. Always use environment variables to secure these details.
In SendLayer, you can access your SMTP credentials from your account dashboard. Once you’re logged in, navigate to Settings » SMTP Credentials.
You’ll see the SMTP credentials required to use SendLayer’s SMTP server. The Host and Port number are the same for all users. However, the Username and Password details are unique to your SendLayer account.
After updating the .env.production file with your SMTP details, be sure to save your changes and close the file.
Step 3: Apply Changes
To make sure your changes take effect, restart Mastodon’s background processes:
RAILS_ENV=production bundle exec rails db:seed
After that, run the command below to restart Mastodon services:
sudo systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming
Step 4: Test Email Delivery
To make sure everything is working, test email functionality. There are different ways to do this. You could try signing up for a new account or resetting your password to see if you receive the password reset email.
Additionally, you can use the Rails console to send a test email to the server admin. Here is how to do it:
Once you’re connected to your server via SSH, run the command below to open the Rails console:
RAILS_ENV=production bundle exec rails console
After that, run the command below to send a test email to the server admin:
AdminMailer.test_email(User.first).deliver_now
If you receive the test email, you’re good to go!
Security Best Practices for Mastodon SMTP Configuration
When setting up SMTP for your Mastodon instance, following these security best practices is crucial:
- Use a dedicated transactional email service like SendLayer for better deliverability and detailed analytics.
- Set up SPF, DKIM, and DMARC records for your domain to prevent emails from going to spam.
- Ensure you keep Mastodon and your SSL certificates updated.
- Monitor your SMTP provider dashboard for any bounced or rejected emails.
FAQs – Sending Emails in Mastodon
Below, we’ve answered some of the top questions about setting up email in Mastodon.
How do I access my Mastodon admin login?
After installation, use the tootctl command to create Mastodon admin account. Then you can access /admin on your instance and log in with the credentials you used to set up the admin account.
Can I run Mastodon without email configuration?
While technically possible, Mastodon SMTP setup is essential for user registration and account management.
Why isn’t my reverse proxy working?
This can occur due to incorrect Nginx configuration or SSL certificate problems. To resolve it, double-check that your server is properly configured. Also, check that you have a valid SSL certificate. If the issue persists, you may need to contact your web hosting provider for additional help.
That’s it! Your Mastodon server is now configured to send emails through an SMTP server.
When running a Mastodon server, users in your network will often request password resets. Check out our tutorial to learn about the best practice for password reset emails.