Mailgun SPF, DKIM & DMARC Setup Guide

Overview

Mailgun (now part of Sinch, alongside Mailjet) is a developer-first transactional email API known for its powerful routing rules, log search, and deliverability tools. Its SPF record uses include:mailgun.org, costing 1 DNS lookup. Mailgun is a popular choice for development teams that want fine-grained control over email sending through a RESTful API or SMTP relay.

DKIM in Mailgun uses two CNAME records with selectors pdk1 and pdk2. This CNAME delegation model enables automatic key rotation — Mailgun introduces a new key on one selector while the old key remains active on the other, ensuring uninterrupted DKIM verification during the transition. Both 1024-bit and 2048-bit RSA keys are supported, with 2048-bit recommended for stronger security.

DMARC alignment requires configuring a custom return-path domain. Without it, Mailgun uses mailgun.org as the return-path, which breaks SPF alignment under DMARC even though the SPF check itself passes. The custom return-path is set up by adding a CNAME record for a subdomain (like email.yourdomain.com) that points to Mailgun's bounce handling infrastructure. DKIM alignment works automatically through the CNAME delegation once the sending domain is verified.

Additional Setup Notes

Dual-Selector Key Rotation

Mailgun's dual-selector CNAME approach (pdk1 and pdk2) provides seamless key rotation without any action on your part. Once the CNAME records are published, Mailgun manages the signing keys behind them. This is a significant operational advantage over providers that require manual TXT record updates for key rotation.

The rotation works by alternating the active signing selector. When Mailgun introduces a new key on pdk1, it continues verifying signatures with the old key on pdk2 until the new key's DNS record has propagated and receiving servers are seeing it consistently. Then the old key is retired and pdk2 becomes the next rotation target. This leapfrog approach means DKIM verification is never interrupted.

DKIM Key Length and DNS Provider Limits

When using 2048-bit DKIM keys, some DNS providers have trouble with the record length. If your DKIM verification fails after setup, check whether your DNS provider requires the TXT record value to be split into multiple strings within a single record. This is a DNS provider limitation, not a Mailgun issue. Most modern DNS providers (Cloudflare, Route 53, Google Cloud DNS) handle long records correctly, but legacy control panels from budget hosting providers may truncate values at 255 characters.

Custom Return-Path Configuration

Custom return-path domain setup is the most commonly missed configuration step. Without the custom return-path, DMARC reports will consistently show SPF alignment failures — the SPF check passes against mailgun.org, but DMARC alignment fails because the return-path domain doesn't match your From domain.

The return-path CNAME typically points a subdomain like email.yourdomain.com or bounce.yourdomain.com to Mailgun's bounce infrastructure. Choose a subdomain you don't use for anything else. Once the CNAME is published and verified, Mailgun sets the return-path on outbound messages to an address at your subdomain, enabling SPF alignment.

Mailgun and Mailjet (Sinch Ecosystem)

Mailgun and Mailjet are both owned by Sinch but operate on separate infrastructure. If you use both, you'll need include:mailgun.org and include:spf1.mailjet.com — 2 lookups for the Sinch ecosystem. Managed SPF can consolidate these if you're tight on lookup budget.

Despite the shared ownership, the two services have different SPF records, different DKIM selectors, and different domain verification processes. Don't assume configuration from one carries over to the other.

Troubleshooting

Domain Verification Stuck in "Unverified" State

After adding a domain in the Mailgun dashboard and publishing the required DNS records, verification can take up to 48 hours. If the domain stays unverified beyond that:

1. Check all records — Mailgun requires the DKIM CNAMEs, the return-path CNAME, and an MX record (if you're using Mailgun for inbound routing). Missing any one of these can prevent verification from completing.
2. DNS proxy interference — Cloudflare users must ensure all Mailgun-related CNAME records are in DNS-only mode (grey cloud). Proxied CNAMEs resolve to Cloudflare IPs, not Mailgun's infrastructure, which breaks verification.
3. Manual verification — Use the "Check DNS Records Now" button in the Mailgun dashboard to trigger an immediate re-check rather than waiting for the next automatic cycle.

DMARC Reports Showing SPF Alignment Failures

If your DMARC aggregate reports consistently show SPF alignment failures for Mailgun traffic, the cause is almost always a missing or misconfigured return-path CNAME. The SPF check itself passes (against mailgun.org), but DMARC alignment requires the envelope sender domain to match the From header domain.

To confirm: inspect the raw headers of a message sent through Mailgun. The Return-Path header should show your domain (e.g., bounce@email.yourdomain.com). If it shows a mailgun.org address, the custom return-path is not active.

API vs. SMTP Authentication Differences

Mailgun supports both RESTful API and SMTP relay for sending. Both methods use the same SPF and DKIM configuration — the authentication records don't change based on how you submit messages. However, SMTP relay connections require different credentials (SMTP username and password) than API calls (API key). A common mistake is using the API key as the SMTP password or vice versa.

For email authentication purposes, both sending methods produce identical headers, the same DKIM signatures, and the same return-path behavior. The choice between API and SMTP is about integration convenience, not deliverability.

Sending from Multiple Domains

Each domain you send from through Mailgun requires its own set of DNS records — DKIM CNAMEs, return-path CNAME, and SPF include. The include:mailgun.org SPF entry covers all sending from Mailgun regardless of which domain is configured, so you only need it once per SPF record. But DKIM and return-path setup are per-domain.

If your organization sends from company.com and brand.com through the same Mailgun account, each domain needs its own pdk1 and pdk2 CNAME records and its own return-path CNAME. Missing the records on one domain while having them on another is a common configuration gap that shows up as intermittent DMARC failures — messages from one domain pass, messages from the other fail.