Mailgun for Outbound Email

The one click Ghost deployment provided by Digital Ocean is configured with an default email sender. However, this is will be likely to cause your emails to get stuck in the junk folder of your recipients. Read on for details on how I solved this problem using the services provided by Mailgun.

If you want emails from your domain, whether simply notifications of new content or direct marketing drives, to get into inboxes, you will need to adopt an outbound email strategy. This could mean building up a positive reputation as a responsible domain, which sends emails in low volumes from the same IP address over time. This can be a time consuming way and you may miss a lot of opportunities.

After you have just set up a blog, the reputation of both the new server and new domain are probably insufficient to give the sophisticated algorithms employed by most mail servers confidence that your emails are not junk. It is more likely that the previously unknown IP address is what will be treated as especially suspicious as well as the fact that there is no way for the receiver to verify that the email originated from your domain.

Using the Labs option with Ghost, available from the navigation bar, you can click the Send button in the “Test email configuration” section. This will send an email to your registered email account. Keep an eye for the status bar at the top of the screen as it might indicate a problem. Go to your email client and investigate if it arrives in the inbox. Also check the junk or spam folder - that’s where it will probably be placed.

A solution is to use a third party service, such as Mailgun or Amazon SES to act as your mail server. The former offers up to 10,000 outgoing free emails per month which should be sufficient for a blog during the startup phase. The latter may be a better option for some but I was put off by only having access to the free tier for twelve months. Gmail can also be configured but may not be be a great choice if you intend to send marketing emails.

These services already operate from a position of trust and avoid being labled as spam by charging money for companies or individuals that send enormous amounts of email. They use public key signatures to prove that you as the sender, definitely own the domain. They will also enforce anti-spam conventions by providing unsubscribe options for your direct email so that people can opt out and never receive the email you send.

Setting up Mailgun for You Domain

The first thing to note is that while Mailgun is free up to 10,000 emails per month, that it does ask for credit card details when signing up. You will not pay unless you exceed this limit. From the Account Settings page you can set an absolute limit to avoid getting charged.

On sign-up, you will get a curl command that you can test the sandbox sender that is setup immediately. Paste it into a Terminal window (on mac) and verify that you got the email. You can only use the sandbox to send to your sign-up email or to specifically authorised addresses.

Adding a domain and proving that you are the administrator of that domain takes a few minutes but is also straightforward. You need to make DNS entries at your domain's configuration site so make sure that you have the passwords ready.

Click the Add New Domain button from the Domains tab. They recommend using a sub-domain such as “mail” for your site. So for “mydomain.com”, you should set the domain name to “mail.mydomain.com”. Depending on what you want to achieve this advice may not necessarily be the best way to set up the system.

If you intend to receive email to your Mailgun account, for example forwarding it or simply logging the receipt, then this setup will not be sufficient! If you set up the domain as mail.yourdomain.com then only emails to user@mail.yourdomain.com will be handled correctly.

Although Mailgun can accept emails to user@yourdomain.com, it will not allow these to be forwarded. I got the following response:

550 5.7.1 Relaying denied

My target state for Mailgun is for it to act as an email sender, and potentially in the future, to send any marketing emails that I come up with. I also want to be able to handle inbound emails to the domain address, but I am not convinced that Mailgun is the best candidate to handle these inbound emails. So I need to retain the option of changing this in the future without impacting the sending capability.

I setup and deleted mine a few times before I was happy; note that you cannot rename a domain in Mailgun once set up, a new one should be created before deleting the old one. There may be reputation issue caused by doing this in the future, so best to try to get things right in the first place.

Domain Verification

My solution (it works for now anyway) is to setup both a sub-domain for sending and a domain for receiving. I started by adding the base domain and verifying it before adding the sub-domain “mail.failedtofunction.com”.

After adding a domain to Mailgun it will be in an unverified state. On its configuration page, look for the “Domain Verification & DNS” section. In here you will find the DNS records that you need to add to your DNS configuration. This site is using Cloud Flare so I went there to add the details.

At a minimum you will need to add the TXT records; for my setup, I added the following records. Note that the name of the first was entered as “@” on Cloud Flare.

The first two were added at the domain level and only one at the sub-domain level. The v=spf1… records indicates to a receiving mail server that emails from either the main or sub-domain are allowed to be sent from mailgun.org; all other sources should be denied. The other entry is a public key which allows a signature in the header to be verified.

Mailgun recommends setting up MX records if inbound email is desired. While I do not absolutely require this on both the domain and sub-domain, I am going to add it anyway as follows:

The final entry Mailgun recommends is a CNAME record that can be used for tracking opens, clicks and unsubscribes. Note that this should have the grey Cloud Flare icon to indicate DNS only.

It can takes a few minutes and sometimes up to a couple of days for the DNS entries to propagate but I've found Cloud Flare to always be quick with changes. From the Mailgun Domains tab, click the “Check DNS Records Now” button to immediately check, but the system should check periodically.

Also Mailgun will send an email to your registered address as soon as the domain is verified. The status will turn to active on the dashboard as soon as the setup is verified. If you are copying my setup, remember to check both the domain and sub-domain.

Ghost configuration

The steps for setting up Mailgun within Ghost are pretty straightforward and provided in the Ghost documentation.

There is not much to change in Ghost to point it to the email sending service. Nevertheless I'd make a backup of the configuration file before attempting to modify it:

sudo cp /var/www/ghost/config.production.json ~/config.production.json.backup

If necessary you can revert with the following:

sudo cp ~/config.production.json.backup /var/www/ghost/config.production.json

To change the settings use an editor you are comfortable with, such as vi, to edit this configuration file:

sudo vi /var/www/ghost/config.production.json

You will need to change the mail section and expand it to contain details from the Mailgun settings page. Find the values there for Default SMTP Login and Default Password and change the JSON block to look like the following:

"mail": {
  "transport": "SMTP",
  "options": {
    "service": "Mailgun",
    "auth": {
      "user": "<Default SMTP Login>",
      "pass": "<Default Password>"
    }
  }
}

Note that if you are unfamiliar with JSON it can be tricky to get the syntax correct. Use an on-line JSON validator to check the syntax of the entire file if in doubt.

Once happy you will need to restart Ghost for the configuration to take effect. You need to be in the installation folder of the Ghost instance you are restarting:

cd /var/www/ghost/
sudo ghost restart

If you made a mistake with the configuration then you should get immediate feedback. Also you can open the administration page to ensure that you can log in before continuing - revert to the backup as indicated above if there are any issues and try again.

Go back to the Labs section and resend an email. This one should make it to your inbox. You can double check to ensure that it was sent via Mailgun using the following methods.

Check email was sent via Mailgun

The easiest way to test this is to log in to the Mailgun site and go to the Analytics tab. You should see the number of messages sent to your domain increase on the graph as you send emails. Here's mine after sending a few emails:

You can also open the message and check the message headers on the email to verify that it was routed through the Mailgun servers. Most email clients have some way of displaying the headers. It can be difficult to interpret, but if there is any reference to a Mailgun server, then it has probably gone the correct route.

Inbound Email Routes

Setting up an email route is straigtforward. Log into Mailgun and go to the Routes tab. Click Create Route.

You can add a route that takes all email that hits the domain and forwards somewhere, but probably better is to only accept specific users. Use the Match Recipient option for this, but note that there are other options such as Match Header that allows the email headers to be checked.

The simplest action is to simply forward the email to another email or to a website. There is also an option to store and notify.

Gmail

Note that if you are setting up a forward rule that will send to a gmail account, testing is not that easy. If you send from the same gmail account that will ultimately receive the email, then gmail hides the email without showing it for some reason. Either test by sending from some other email address or verify it is working by checking the analytics and log tabs in the Mailgun console to ensure the email was routed by the correct path.

Let me know how you get on by sending me an email at ronan@failedtofunction.com.