Configuring Mailgun for WordPress with Sail CLI

Mailgun is a robust e-mail delivery service with both API and SMTP support, and a generous trial of up to 5000 e-mails/mo for three months. Together with Mailgun, we’ve developed a couple of default blueprints for Sail to ease the configuration.

  • mailgun-dns.yaml: this blueprint adds all necessary DNS records for mail delivery through Mailgun, as well as domain verification at Mailgun
  • mailgun.yaml: extends the default Postifx configuration with Mailgun-specific settings

If haven’t used sail before, it’s a free and open source CLI tool, that helps you provision and deploy WordPress applications to the DigitalOcean cloud. Sail is available for Windows, macOS and Linux. Click here to learn more about Sail.

Add and Verify a Domain

Before running any Sail blueprints you’ll need to get an account at Mailgun. Then add your domain name to Mailgun under SendingDomainsAdd New Domain. After the domain is added you’ll see a list of DNS records, required for mail delivery and domain verification (SPF, DKIM, MX and CNAME records).

Next, add this domain to your DigitalOcean account using Sail:

$ sail domain add example.org

Make sure the domain name server records at your domain registrar are pointed to the DigitalOcean DNS servers:

  • ns1.digitalocean.com
  • ns2.digitalocean.com
  • ns3.digitalocean.com

Here’s how to do that with common domain registrars.

To add the Mailgun DNS records to your domain, run the mailgun-dns.yaml blueprint with Sail:

$ sail blueprint mailgun-dns.yaml
> Domain Name: example.org
> DKIM Record Name: mx._domainkey
> DKIM Record Value: k=rsa; p=...
# Applying blueprint: mailgun-dns.yaml

Note: the DKIM record name should not include the full host/domain, but only the DNS record name. So if the full host name is mx._domainkey.example.org, you’ll need to enter just the mx._domainkey part (no trailing dot).

After the DNS records have been added to your DigitalOcean account, visit your Mailgun control panel and under SendingDomainsYour Domain, hit the Verify DNS Settings button.

Configure Postfix for Mailgun

After verifying the domain with Mailgun, grab your SMTP settings from your Mailgun control panel under SendingDomain SettingsSMTP Credentials. You’ll need the SMTP login and password here. You might have to reset the password if you’d like to use the default postmaster user.

Armed with these credentials, you can now run the mailgun.yaml blueprint with Sail:

$ sail blueprint mailgun.yaml
> Mailgun SMTP Login: postmaster@example.org
> Mailgun SMTP Password: ...
> From name: WordPress
> From e-mail: hi@example.org
# Applying blueprint: mailgun.yaml

The From name and From e-mail values are what’s going to be used with wp_mail() by default in WordPress, when setting the From: header for e-mail delivery. For best results, it is recommended that you use an e-mail address within the domain you’re using with Mailgun.

This blueprint will also create a mu-plugin on your production site, which sets the from name and e-mail. Be careful not to overwrite/delete this plugin when deploying changes to your production site. It is always recommended to run a `sail download` after any blueprint, to make sure your local copy is completely in sync.

Send a Test E-mail

You can send a test e-mail using Sail, to make sure it reaches your inbox:

$ sail wp shell
wp> wp_mail( 'your@email.address', 'Test from Sail', 'The body' );
=> bool(true)

If it has not reached your inbox, there are a few places you could look at for more information:

  1. Postfix logs using sail logs --postfix
  2. Mail logs in the Mailgun dashboard
  3. Your spam folder, of course

If you’re having problems with e-mail delivery in Sail for WordPress, please double-check to make sure your DNS records are correct, your SMTP credentials are okay. If they are and you’re still experiencing trouble, feel free to reach out Sail support or Mailgun support for help.

Mail Performance

I’ll be doing a mail performance test of this configuration, and possibly fine-tuning it during a live stream via Koddr.io on September 28th at 17:00 UTC. Let’s see what it takes to send 10,000 e-mails from a five-dollar DigitalOcean droplet.

If you’d like to be notified (and also support us in general), you can:

See you soon!

About the author

Konstantin Kovshenin

WordPress Core Contributor, ex-Automattician, public speaker and consultant, enjoying life in Moscow. I blog about tech, WordPress and DevOps.