Fixing transactional email in Ghost

I had to move my blog to a new server back in May, and that caused transactional emails to break. There was no configuration in Ghost that specified my SMTP settings, so I was somewhat stumped. In this post I'll highlight the relevant symptoms and settings.

What is transactional email used for?

Transactional emails are not blog posts being sent to subscribers, those are bulk emails. Your site will use transactional email configuration for:

• Sending admin user multi factor authentication codes
• Sending user sign up emails
• Sending user sign in emails (the code used to login to comment)

Signs that transactional email is broken

Administrators cannot login

With broken transactional email, when an administrator tries to login they won't be sent a multi factor authentication (MFA) code. Administrators are essentially locked out.

As a workaround only, you can modify your Ghost configuration to not require MFA while you get things fixed:

1. Edit config.production.json in your Ghost directory (e.g. /var/www/ghost/config.production.json)
2. Find the security section or add it
3. Set staffDeviceVerification to false
4. Save your configuration file
5. Restart Ghost

Which looks like:

"security": {
    "staffDeviceVerification": true
  },

Don't forget to set this back to true once the problem is fixed.

Users cannot sign up or sign in

Because users are sent a login code, and those emails are sent via transactional email, the user gets an error and cannot gain access.

Fix

For people self-hosting Ghost, the easiest option is to edit your config.production.json file. By default, the mail transport is set to direct, which uses whatever SMTP service is available on your server. Unless this is configured correctly, Ghost won't be able to send emails.

Ghost's own documentation takes you through using a Maligun account for transactional email. If you email blog posts to subscribers then you'll already be using Mailgun for bulk emails.

1. Edit config.production.json in your Ghost directory (e.g. /var/www/ghost/config.production.json)
2. Find the mail section and set transport to SMTP
3. Add an options sub-section and populate with the relevant values - see my example below
4. Save your configuration file
5. Restart Ghost
6. Check that transactional email is working (e.g. try to sign in to your site as a visitor, or try to subscribe to it) and confirm you receive the email
7. If you disabled staffDeviceVerification, edit your config.production.json file again
8. Find the security section or add it
9. Set staffDeviceVerification to true
10. Save your configuration file
11. Restart Ghost

Example config (mail section)

Note: If using "secure": true you'll need the port set to 465 to work with Mailgun.

"mail": {
    "transport": "SMTP",
    "options": {
      "service": "Mailgun",
      "host": "smtp.eu.mailgun.org",
      "port": 465,
      "secure": true,
      "auth": {
        "user": "postmaster@YOUR-DOMAIN-HERE",
        "pass": "YOUR-SMTP-PASSWORD-HERE"
      }
    }
  },

Banner image, the Ghost logo, from https://ghost.org/design/.