necrux - Blog

Getting Started with Mailgun

Mailgun is a developer-centric approach to email. It can be used to simply relay email, but it can do so much more! In this article I am going to discuss basic configuration for using Mailgun as a relay with Postfix and briefly discuss some of the additional features offered by Mailgun.

Step 1) Account creation and domain verification

Once you have a Mailgun account set-up, the first thing you need to do is verify your domain by adding the provided txt DNS records. If you need the ability to track opens, clicks, and unsubscribes, Mailgun gives you the option to add a CNAME as well . Additionally you can add an MX record if you want to relay incoming email through Mailgun. Utilizing Mailgun for incoming email is outside the scope of this article, but in short the received email is stored on Mailgun servers and can be retrieved with API calls; you can also format the received email in JSON to more easily parse with your application.

Step 2) Configure Postfix

The required Postfix configuration is relatively simple, just append the following information to the end of /etc/postfix/main.cf (replace with the "Default SMTP Login" and with the "Default Password" from the Mailgun control panel):

smtp_sasl_security_options = noanonymous
smtp_sasl_password_maps = static:<login>:<password>
relayhost = [smtp.mailgun.org]:587
smtp_sasl_auth_enable = yes

Be sure to restart Postfix! service postfix restart or systemctl restart postfix.service

Note: If you have multiple domains hosted on the same server it is possible to route them through their respective domains in Mailgun. To do this requires configuring Sender-Dependent SASL authentication in Postfix. I plan to cover this topic in a future article.

Testing & Troubleshooting

To test that the configuration is working, you can use the mail command:

echo "Test email to verify relay." > test_email.txt
mail -s "Relay Test" me@example.com < test_email.txt

If you do not receive the test email then login to the Mailgun control panel and check the logs. If there is no entry for the test email then the email never reached Mailgun. You will need to view the mail log from the server to help diagnose the problem:

tail /var/log/maillog

Two of the more common problems you may find relate to connectivity and authentication (examples below):

mailgun postfix/smtp[3455]: 241AFC010A: to=<me@example.com>, relay=none, delay=20, delays=0.01/0/20/0, dsn=4.4.3, status=deferred (Host or domain name not found. Name service error for name=smtp.mailgun.org type=MX: Host not found, try again)

mailgun postfix/error[5369]: AF597C011F: to=<me@example.com>, relay=none, delay=0.03, delays=0.02/0.01/0/0, dsn=4.7.0, status=deferred (delivery temporarily suspended: SASL authentication failed; cannot authenticate to server smtp.mailgun.org[50.56.21.176]: no mechanism available)

In the case of connectivity issues (the first example) you will simply need to verify the server can connect to smtp.mailgun.org on port 25. In the case of authentication issues (the second example) there are a couple of possibilities: A) The login and/or password that you entered in /etc/postfix/main.cf is incorrect or B) the server does not have a method to authenticate to the Mailgun server; to rectify this you will need to install a couple of packages and restart Postfix:

yum install cyrus-sasl-plain cyrus-sasl-md5

Additional Mailgun Features

In addition to relaying email, Mailgun can also handle lists, subscriptions, and unsubcribes. To get started simply create a list of recipients in Mailgun and when it comes time to send out bulk email, e.g. a newsletter, have your server send the email to the list. This allows you to completely offload all of that work to the Mailgun servers, meaning that regardless of the number of recipients your server never handles more than 1 email!

Mailgun has superb documentation on their APIs with plenty of examples. But if you are interested in a quick and dirty test to get started, try out the steps below:

Build a list

There are API calls available, but in this example we are going to use the Mailgun control panel. Simply navigate to “Mailing Lists”, click “Create Mailing List”, hit “Save” after filling in the required fields, and finally click “Create Recipient”. From that point you can either manually add people to the list or else upload a CSV (formatting example below):

John Doe, john@example.com Jane Doe, jane@example.com

Sending a test email to the list

From bash run the following API call. Be sure to replace anything in CAPITAL letters with your details:

curl -s --user 'api:key-API_KEY' \
https://api.mailgun.net/v2/MY_DOMAIN/messages \
-F from='ME <ME@EXAMPLE.COM>' \
-F to=MY_LIST@MY_DOMAIN \
-F subject='List Test' \
-F text='This email to is verify that my newly created list in Mailgun is functioning as expected. Yay!’

Mailgun for Rackspace Customers

Being a Rackspace cloud customer offers a few unique twists in regards to Mailgun. For starters, if you have a Rackspace cloud account you automatically have a Mailgun account that you can access from the Rackspace control panel. If you navigate to the Mailgun panel you will see that there is already a domain set-up. This “sandbox domain” is primarily meant for quick testing without having to configure DNS. Sandbox domains are not meant for use in production as they carry the following limitations:

  1. They are limited to 300 emails per day.
  2. All messages relayed through this domain will say “mailed-by: mailgun.org” in the header.
  3. Sandbox domains do not help you establish a positive email reputation.
  4. Mailgun is less suspicious of traffic that is being sent on verified domains; using one reduces the likelihood of being disabled.

In addition to the above, Rackspace customers receive 50,000 free emails per month whereas non-Rackspace customers only have 10,000 free emails per month. And lastly, Rackspace customers with the Managed Operations support level automatically have Postfix configured on all newly provisioned servers to relay email through their default domain in Mailgun.