Missing documentation for mail config options – Mailgun API support

[quentin-binder]

I ran into some issues trying to set up transactional email with Ghost, and I think there’s a gap in the documentation that could use some clarification.

I wanted to use Mailgun for sending transactional emails and followed the instructions here:

Configuration - Adapt your publication to suit your needs

I tried configuring SMTP as described, but it consistently timed out after 60 seconds (without any errors). I double-checked the ports, authentication details, and tried multiple variations without success.

When I couldn’t get it working, I started looking for a full list of configuration options, but couldn’t find any comprehensive documentation— neither in the official docs nor in the forum. I also tried searching more broadly online but couldn’t find anything.

Eventually, I looked into the Ghost source code and found that it uses the @tryghost/nodemailer package (which appears to be not in the Mono Repo). In that package, I noticed there’s a “mailgun” transport option that allows sending transactional mail via the Mailgun API rather than SMTP.

I tried configuring Ghost to use the Mailgun API directly, and that finally worked.

So my questions are:

• Why isn’t this Mailgun API transport documented in the official Ghost docs? → Isn’t it more useful / reliable?

• Is there a complete list of supported mail configuration options anywhere?

• Or are we expected to look into the codebase to discover these things?

It would be really helpful if the docs included all valid config options, especially for something as important as mail.

Has anyone else run into this? Or found any reliable documentation on the mail config beyond what’s on the main site?

---

  "mail": {
    "from": "no-reply@domain.xyz",
    "transport": "mailgun",
    "options": {
      "auth": {
        "api_key": "<api_key>",
        "domain": "mg.domain.xyz"
      },
      "host": "api.eu.mailgun.net"
    }
  },

---

Related:

Make onboarding emails also work via API (not only SMTP)

The following problem: I had some issues setting up SMTP for Digital Ocean. And also other hosters, since there seems to be a tendency towards “we will not allow SMTP traffic” for a good reason. Please also refer to this thread: Use Mailgun API, instead of SMTP for onboarding-emails? The idea here is now: Why not make ghost available to use API-calls, like the one we have with mailgun, to get the onboarding emails gone right. Right now I can live with the “workarounds”, like using ports not s…

[eddywashere]

Just came across this quirk as well and ran through the code to discover the same thing.

For me, this issue came up when I tried signing up for someones Ghost newsletter and it went to my spam folder. I looked at the headers, and looked up their dmarc records. I immediately noticed the IP of their server hosting their site in the headers, which is unfortunate, but also their dmarc policy was set to none. While the dmarc issue only happens when sending to larger lists, this can often be a surprise for folks when testing initial configuration or a test newsletter before sending to their larger list.

Leaking the host server IP address on the other hand is a much bigger issue. If someone has a vps or cloud server who’s IP has been marked as spam for any reason out of their control, this alone elevates the risk that the emails sent will end up in the spam folder. It also means, self-hosting multiple ghost sites on a single address end up sharing that issue or also end up impacted when the dmarc issue starts to happen.

If Mailgun is required for newsletters, I believe it makes sense to avoid a mixed configuration of SMTP and API anywhere the mailgun configuration is mentioned.