One of the most annoying parts about building a Mastodon server is getting the SMTP service setup, even the free options like AWS SES and SendGrid require some level of configuration and setting DNS records to ensure deliverability and there's no guarantee you won't get hit with a bill down the road if you have a post that goes viral and generates a lot of replies.
Today I want to share a guide on setting up the easiest and a 100% free solution for your SMTP needs, and it's all provided by Google so you know your e-mails will actually get delivered. There are some downsides to this option though, but they shouldn't impact your use case unless you plan on having a lot of users join your instance.
The main downside is that you're limited to sending 500 e-mail per day which is a lot for a small instance, but can easily get maxed out by a medium sized instance. Another downside is you're using Google, which most people who use Mastodon tend to avoid. In this case though, you're just sending transactional e-mails so maybe they get a pass? Lastly, it's a free service that they can turn off one day without notice and you have no recourse or support. With those caveats in mind, lets get into the guide!
Configuring GMail
- Create a new GMail account (or login to an existing one).
- Navigate to myaccount.google.com and click on Security.
- Click on 2-Step Verification.
- Click on Authenticator (or use another method if you prefer).
- Click the Set up authenticator button.
- Scan the QR code in your MFA app of choice and then click on Next.
- Type the code from the app and click on Verify.
- Click on the Turn on button for 2-Step Verification.
- Click on the Turn on 2-Step Verification button.
- No need to enter a phone number, just click on Skip.
- Click on the Continue anyway button.
- Click the Done button to finish up this part.
- Now go to myaccount.google.com/apppasswords and enter any name you'd like then click the Create button.
- Copy down the password it created (including the spaces) and click the Done button.
- Go back to GMail and click on the cog wheel and then click See all settings.
- Navigate to the Forwarding and POP/IMAP tab and enable both POP and IMAP then click the Save Changes button.
- Click the Continue button to verify with MFA.
- Type in the MFA code from the auth app and click the Next button.
And you're all set on the GMail side of things! Now to finish up with Mastodon.
Configuring Mastodon
If you are deploying a new server, when you get the Mastodon setup portion you'll want to enter the SMTP details below. If you already have a Mastodon server deployed then you can use the SMTP details below and update your .env.production file (don't forget to restart your Mastodon services after you do).
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_LOGIN=YOUR_EMAIL@gmail.com
SMTP_PASSWORD='YOUR_APP_PASSWORD'
SMTP_AUTH_METHOD=plain
SMTP_OPENSSL_VERIFY_MODE=none
SMTP_ENABLE_STARTTLS=auto
SMTP_FROM_ADDRESS='Mastodon <YOUR_EMAIL@gmail.com>'
Be sure to update SMTP_LOGIN, SMTP_PASSWORD, and SMTP_FROM_ADDRESS with your details! Keep the single quote around the password and from address.
Now you have a functioning SMTP server for your Mastodon instance with minimal-ish setup. This is a decent solution in a pinch and I've been using this method for quite a few small servers I've deployed over the years without any issues. For anything that needs more than a few hundred e-mails per day, I use MXRoute for a few dollars a month and it's been solid so far (I even had to increase my daily limit from the default 7200 to 15000 a while back). I might do a review of the service in the future since I've been using it forever and switched away from my paid SendGrid account a while back, but that's for another day.
Hopefully this helps a few people out and reduces any concerns about costs. I'll probably do another guide for configuring AWS SES to use with Mastodon since I've been on a bit of an AWS streak lately. 😊
Go out and do good things! 👍
-KuJoe