updates

Switching Your Discourse from Mandrill to Mailgun

Jeff Atwood

Mar 28, 2016 • 6 min read

Self-hosted Discourse requires email to function, so we've always had a symbiotic relationship with third party email providers. In the past we've recommended Mandrill, we use it ourselves for some of our sites, and we've had nothing but positive experiences with Mandrill … until now. On February 24th, Mandrill announced they are essentially closing the Mandrill service forever as of April 27th, 2016.

Going forward, all Mandrill users will be required to have a paid monthly MailChimp account and verify ownership of all sending domains. Here’s the timeline: Starting 3/16, all new Mandrill users will create accounts through MailChimp, and current Mandrill users can merge their existing Mandrill account with a monthly MailChimp account. Current users will have until 4/27 to merge their accounts.

Technically you can transition to their MailChimp provider, but it's a massive increase in monthly costs – from free (for 12,000 or fewer emails per month) to about $40 per month. That's four times as much as Digital Ocean charges for a basic $10/month Discourse host VM, just for sending email!

While you can "upgrade" your Mandrill account to MailChimp, we don't recommend that, unless you feel like paying $40 per month for the privilege of sending a few emails. There are several other reliable third party email providers who offer similarly free plans below a reasonable send limit:

SparkPost (100k emails/month) — migration guide
SendGrid (12k emails/month) — migration guide
MailGun (10k emails/month)
MailJet (6k emails/month)

We've heard positive things about all of these services, but we have the most experience with MailGun, so that's what I'm going to walk through here. The steps will be roughly similar for any third party email service.

Go ahead and create your Mailgun account. No credit card is required; you can optionally add one at signup if you want to ensure continuity of service if you might exceed the allowed 10k emails per month — that's 333 emails per day, on average.

However, in addition to a verified email address, a valid telephone number is required and a SMS verification will be sent, so be ready.

2. Add the domain to your account

In MailGun, under your Domains tab, add your Discourse domain in this form:

discourse.example.com

Note that the email must come from @discourse.example.com for this to work, so be sure that your Discourse site settings for mail include that domain, particularly under notification email:

Be sure that says noreply@discourse.example.com and that the domain matches your email. Email is always judged by the domain it was sent from!

3. Update DNS records to validate your domain for email

If you visit your domain page in MailGun, you'll see a summary of the necessary DNS changes to verify your domain.

You should generally make these DNS changes at the same place you purchased the domain name from, unless you've transferred DNS functions to somewhere else. You need to add or update two TXT records here, one for SPF and one for DKIM. Here's what those two TXT records look like in CloudFlare DNS:

Once you've done that check back on your domain page using the Check DNS Records Now button to verify that Mailgun sees the change. This change may take up to 24 hours to propagate, so be patient. It definitely took a few hours in my testing. Mailgun will email you once the domain is fully verified.

Note that until you make these DNS changes to verify your domain, you will only be able to send email to the single email address that you signed up with!

4. Log in via SSH and edit your Discourse config

Now we're ready to plug in SMTP credentials for our Mailgun account for this domain into Discourse. Look at the Default SMTP Login and Default Password fields in the domain settings in Mailgun.

SSH into your server using your SSH client of choice. Once you're logged in and at the SSH command prompt, begin editing the app.yml file:

cd /var/discourse
nano containers/app.yml

You'll need to change three DISCOURSE_SMTP lines, using the account information provided for the domain on the MailGun domain page, per above:

DISCOURSE_SMTP_ADDRESS: smtp.mailgun.org
DISCOURSE_SMTP_USER_NAME: postmaster@discourse.example.com
DISCOURSE_SMTP_PASSWORD: ac9e7725d9c65fdf47dccea0f16838b0

Once you finish, rebuild your Discourse to latest. Don't worry, this won't delete anything! It will, however, take anywhere from 4 to 10 minutes depending on the speed of your server, so plan for a bit of downtime.

git pull
./launcher rebuild app

Once the build completes, you'll be at the command prompt again and your Discourse site will be rebuilt and live. You shouldn't see any errors, but if you do, scroll up to view them, and try editing app.yml again.

5. (Optional) Spring Cleaning

While you are logged in via SSH I strongly recommend you do a bit of yearly spring cleaning. Bear in mind, this is totally optional, feel free to skip to the next step if you're in a hurry and just want to get your mail fixed. But … you might as well since you're right here. It's easy, I swear!

If you're using our recommended Ubuntu 14.04 LTS, download the latest Ubuntu updates and install them:

apt-get update
apt-get dist-upgrade

Clean up leftover backups from old automatically installed Ubuntu updates to free up some disk space. The savings can be substantial, multiple gigabytes:

apt-get autoremove
apt-get autoclean

Clean up any old Docker containers left around by your previous Discourse upgrades, which can also be multiple gigabytes:

./launcher cleanup

6. Send a Test Email

To verify that everything is working properly, visit your Discourse Admin dashboard, under Emails, and read the summary. Does it match what you entered in app.yml?

If everything here matches what you entered, down at the bottom, enter your email address – the same one you originally signed up with on MailGun – and press the Send Test Email button. If this email arrives in your inbox, you're good. Once your domain is validated, you should be able to send a test email to any email address from here and it should arrive.

If the mail doesn't arrive, check the Logs tab for your domain to make sure that your settings were at least correct enough for your Discourse server to talk to MailGun:

If you don't see a log entry here, it means you probably messed up the SMTP username, password, or address settings in app.yml, so double check those.

Good luck, and I hope this guide helped! We do apologize for the inconvenience, but MailChimp decided to effectively discontinue their free Mandrill service on rather short notice.

As a gesture of goodwill, if you have an existing Discourse site and are having trouble with this, assuming you have already completed steps 1-3 we can assist with the Discourse SSH sections (steps 4 and 5) if you email us at team@discourse.org with SSH login credentials. Please note that we cannot help until you have performed steps 1-3 as they are prerequisite steps that are highly specific to you, your email address, your telephone number, and your domain name.