Mailgun SPF, DKIM and DMARC setup, step by step

To configure Mailgun SPF and DKIM, add or select your sending domain and publish its account-generated sending records. SPF uses a TXT policy; DKIM uses either the supplied TXT public key or CNAME records when Automatic Sender Security is enabled. Copy the exact record names and values from your domain's settings. Mailgun domain verification, Automatic Sender Security setting

Do not replace your organization's mailbox MX records just to authenticate outbound Mailgun messages. Mailgun distinguishes receiving-mail MX records from sending authentication. Mailgun DNS FAQ

This guide covers outbound mail submitted through Mailgun's API or SMTP service using a custom domain. “MailGun” in older guide titles is the same provider. It does not configure every application that happens to share your domain, nor does it assume Mailgun should receive your staff's mail.

For the distinction between a valid signature and one aligned to your brand, see EmailAuth's raw DKIM versus aligned DKIM guide. Keep corporate mailbox authentication separate from this application-sending route.

Choose the sending domain and application route

Before editing DNS, record the visible From address, Mailgun sending domain, account, region, application, and current DKIM mode. Identify who owns the authoritative DNS zone and who can approve changes. Use an authorized account administrator for domain and signing changes; this public procedure does not establish a universal plan/role permission matrix. Save the existing SPF, DKIM, DMARC, and MX records so you can distinguish an intentional update from an accidental overwrite.

Mailgun recommends using a sending subdomain. This can make ownership and record changes easier to track, particularly when the root domain already hosts corporate mail. However, choosing a subdomain does not by itself prove DMARC alignment. Confirm the identifiers the application actually uses. Mailgun domain-name guidance

For API sending, the selected domain is part of the request URI. SMTP uses credentials associated with a Mailgun domain. Changing only the visible From address may leave the underlying sending route unchanged. Mailgun sending FAQ

For example, a receipt showing a From address under your main domain could still be submitted through a different configured Mailgun subdomain. Record both. During validation, compare them with the received envelope sender and DKIM signing domain rather than relying on the application's display name.

To provision a new approved domain, open Sending → Domains → Add New Domain, enter the intended owned domain, confirm the correct US or EU region and current DKIM settings, then choose Add Domain to obtain its record packet. For an existing domain, select it rather than creating a duplicate or silently switching regions. Account/route changes require the owner's approval. The native screenshots show these fields and generated DNS rows; they are not account-specific values to reuse. Native domain setup

Which records belong in this change?

This table is a planning aid, not a record set to paste. Obtain your actual DNS specification from the selected domain in Mailgun. If a screenshot differs from your current settings, resolve the mode and domain selection first.

Step 1: configure the Mailgun SPF record

Open the sending domain's DNS records in Mailgun. Its published SPF example is v=spf1 include:mailgun.org ~all. Apply the instruction to the exact sending hostname shown by your account, which may be a subdomain rather than the root. Mailgun verification documentation

If that hostname already has SPF, update the single existing policy to authorize the additional service instead of publishing a second policy. Mailgun's setup guide specifically distinguishes root and subdomain records. Adding an include at the root does not replace a missing policy at a different sending hostname. Mailgun setup guide

Review the whole policy before editing: existing sender mechanisms, any redirect, the terminal all mechanism, and its qualifier. Preserve intentional policy choices. Do not change -all to ~all just because a tutorial uses a different example.

SPF evaluates the actual SMTP MAIL FROM identity, or the applicable HELO identity for a null reverse path and relevant HELO checks, not automatically the visible From. SPF identities

Any all mechanism makes redirect ignored, irrespective of the qualifier. Preserve the approved qualifier and redirect design rather than adding a terminal all to a redirect policy. Qualifiers define SPF results, not guaranteed inbox delivery or rejection. SPF all processing

SPF permits one SPF policy at a name and allows a maximum of ten DNS-querying mechanisms and modifiers during evaluation. Nested includes count toward the limit; counting visible includes alone is insufficient. Validate the complete evaluated policy after merging rather than flattening provider records into a static IP list copied today. SPF specification

Step 2: identify the DKIM mode before publishing

Manual DKIM: publish the TXT public-key record provided for the active configuration. The selector is not universal. Do not assume a familiar label such as mx applies to your domain.

Automatic Sender Security: publish the generated DKIM CNAME records instead of converting the manual key into a guessed CNAME. Mailgun's API documentation says enabling or disabling this feature changes the DKIM DNS requirements and requires the domain to be reverified. Mailgun domain settings reference

Treat a DKIM-mode change as a signing migration: retain the existing DNS and configuration, publish the complete newly required set, reverify, confirm active signing and test the real application route before retiring old records. A secondary key may still serve another domain. Do not delete it merely because this domain now uses Automatic Sender Security. DNS and key-transition FAQ

Use a short worksheet to prevent mode confusion:

Sending domain: COPY_SELECTED_MAILGUN_DOMAIN
DKIM mode: RECORD_CURRENT_ACCOUNT_SETTING
DKIM owner(s): COPY_EACH_GENERATED_OWNER
DKIM type(s): COPY_TXT_OR_CNAME_AS_SHOWN
DKIM value(s): COPY_COMPLETE_KEY_OR_TARGETS

These capitalized entries are placeholders, not DNS records. Retain the generated record list with the change request and avoid inserting secrets into it. You publish DKIM public-key material or delegation targets, never a private signing key.

For a long manual TXT key, preserve the complete tagged value in one logical record. If the DNS interface requires component strings, DKIM concatenates them without inserted spaces; they are not separate competing TXT records. Never truncate the key to fit a screenshot. DKIM key-record processing

Mailgun can show older or inactive DKIM keys as unverified. Do not attempt to make every historical key green. Its guidance says verification depends on the keys required by the current configuration, and describes manual keys being deactivated when Automatic Sender Security CNAME records are verified. Investigate the active configuration before removing anything. Mailgun DKIM-status guidance

Step 3: protect inbound mail and existing DNS

Publishing a sending record does not authorize an inbound-mail migration. Mailgun's DNS FAQ says MX changes are for domains receiving mail through Mailgun and warns that replacing another provider's MX configuration disrupts that delivery. Its tracking CNAME is a separate feature. Mailgun DNS FAQ

Check each new owner name for a collision. If the DNS panel appends your zone automatically, enter the relative name it expects and verify the final fully qualified result. Keep a screenshot or export of the before-and-after records, including TTLs. Avoid deleting a working record to clear a validation error before identifying its owner.

For the illustrative full DKIM owner SELECTOR._domainkey.mg.example.com, use relative SELECTOR._domainkey.mg in the example.com zone, SELECTOR._domainkey in a separately delegated mg.example.com zone, or SELECTOR in a delegated _domainkey.mg.example.com namespace. Publish at the actual authoritative zone and preserve its NS delegation. A root-authority key uses its own issued owner, not automatically the sending subdomain's owner.

A CNAME owner cannot coexist with TXT, A, AAAA, MX or another CNAME. Resolve a collision with the DNS and Mailgun owners, using a supported nonconflicting configuration; never remove active records or delegation blindly. DNS alias rule

Keep required DKIM and tracking aliases as literal CNAME answers, not HTTP redirects or proxied address answers. On Cloudflare, use DNS only, turn an applicable per-record Flatten control off and ensure applicable zone-wide flatten-all does not suppress those aliases. Coordinate shared-setting changes before making them. If mandatory apex or same-zone behavior cannot preserve a required CNAME, stop and agree a supported design rather than inventing a switch or disabling unrelated global behavior. Cloudflare proxy status · Exact flattening controls

Tracking records support click, open and unsubscribe tracking, not authentication. Copy their exact account/region targets only for approved tracking use. Receiving MX changes require a separately approved inbound-routing plan matching the exact destination and priority; a tutorial's full DNS list is not that approval.

SPF alignment, Return-Path, and DKIM authority

The envelope sender used for Mailgun delivery and the visible From address are separate identities. Mailgun requires the sender domain to be one of your Mailgun domains; its documentation recommends matching sender and From domains but allows them to differ. For custom-domain bounce identity, start with the selected Mailgun sending domain and verify the result in headers rather than assuming a Postmark-style Return-Path control exists. Mailgun sending FAQ

DKIM authority can differ from the sending subdomain. The older DNS FAQ describes root/subdomain authority when both are registered. The current create-domain API additionally documents force_root_dkim_host=true for root-domain DKIM even if the root is not registered, with SPF verified at the sending subdomain and DKIM at the root. It explicitly says this does not change SMTP MAIL FROM, which remains the created domain. Do not confuse root DKIM authority with a root bounce identity. Current create-domain reference · DNS authority FAQ

The same API documents dkim_host_name as an explicit domain/root signing authority that cannot be combined with the force flags. force_dkim_authority distinguishes a subdomain's own DKIM authority from an available root authority. Separately, domain updates document mailfrom_host as a lower-case hostname setting. These are different controls, not permission to issue an API change from this guide. Have the authorized administrator inspect the current supported combination and generated records; never infer a universal Return-Path from the UI domain or DKIM mode. Current domain-update reference

A passing SPF or DKIM result must align with the From domain to satisfy DMARC. Relaxed alignment compares Organizational Domains; strict alignment requires identical domains. Verify the policy and message together. DMARC identifier alignment

For a hypothetical intended From receipts@example.com, a passing Mailgun signature with d=mg.example.com aligns in relaxed mode, but not under adkim=s. A passing intended signature with d=example.com aligns in both. A passing envelope at mg.example.com similarly aligns with that From only under relaxed SPF alignment, not aspf=s. These are illustrative identities, not measured results. Keep the current alignment policy; fix the signing design rather than loosening policy just to match a tutorial.

Preserve DMARC protection and report permissions

Read the direct policy for the intended From domain and any applicable inherited parent policy before changing DNS. Preserve enforcement, sp, alignment modes and approved reporting destinations. Do not duplicate DMARC, replace a working p=reject with a provider's p=none, or introduce an obsolete pct rollout.

Only if there is no direct or applicable inherited policy and the domain owner approves an appropriate monitoring plan, a first-policy example is:

Type: TXT
Full owner: _dmarc.example.com
Value: v=DMARC1; p=none

Use relative _dmarc in the example.com zone. For a policy at _dmarc.mg.example.com, use _dmarc.mg in the parent zone or _dmarc in an authoritative delegated mg.example.com zone. These are hypothetical owner mappings, not instructions to replace an existing parent policy. p=none alone does not request reports. Add rua only for an approved mailbox and report-monitoring process.

If the report destination is in a different Organizational Domain from the policy domain, the report-generating receiver must check DNS authorization supplied by the report-destination operator. A destination within the same Organizational Domain is excepted; a different hostname is not automatically external. Aggregate-report authorization This DNS check does not replace the owner's decision about sharing message metadata, access and retention. Do not copy a vendor report recipient or enable message-level failure reports without separate privacy approval.

Verify the configuration in three stages

1. Public DNS. Query the exact supplied owner names. Replace these placeholders with values from your account:

dig TXT MAILGUN_SENDING_DOMAIN +short
dig TXT MANUAL_DKIM_FULL_HOSTNAME +short
dig CNAME AUTOMATIC_DKIM_FULL_HOSTNAME +short

Use only the DKIM command appropriate to your mode, and repeat it for every required owner. Compare the authoritative answer with a public recursive resolver. Save the result and timestamp. Short output alone hides response status: if it is empty or inconsistent, inspect the full answer for missing data, timeout or SERVFAIL, and distinguish authoritative errors from positive/negative caching. For a CNAME, follow its target and confirm that the expected key is available.

2. Mailgun status. In Sending → Domain settings → DNS records, select the intended domain and use Check status. Mailgun also documents a domain-verification action in its control panel and API. Public DNS can take time to converge, but an incorrect authoritative record needs correction rather than waiting. Mailgun verification FAQ

3. Delivered email. Trigger the actual application workflow to an external test mailbox you control. Save a redacted original message and inspect its From, Return-Path, DKIM d= and s=, and the trusted receiver's SPF, DKIM, and DMARC results. Confirm the message used the intended domain and current selector. A key's presence in DNS alone cannot prove that application used it.

Use authentication results generated inside the actual receiving service's known processing boundary. Confirm from its documentation or administrator how it removes or distinguishes externally supplied Authentication-Results. Header position and a familiar authserv-id alone are not trustworthy. Ignore attacker-supplied fields; use a controlled receiver with a documented boundary or its trusted trace if needed. Authentication-Results trust boundary

Accept the branded DKIM setup only when the intended Mailgun signature passes and aligns with the intended visible From under current policy, and the trusted receiver reports dmarc=pass for that From. A generic DMARC pass via SPF does not prove DKIM works. A rewritten provider-owned From is not successful authentication of the intended brand. Inspect SPF independently even when aligned DKIM supplies DMARC pass. Repeat controlled tests for each production API/SMTP application, From domain and materially different route. A Mailgun acceptance/event log is not a substitute for the final recipient's authentication evidence

Troubleshooting and handover

DKIM verified, SPF unverified: Query SPF at the selected sending hostname. Check for duplicate SPF policies, a missing include, or an edit made only at the root.

SPF fails despite DKIM-based DMARC pass: For fail or softfail, compare the actual connecting IP and evaluated envelope/HELO owner with its approved policy. For permerror, investigate duplicate SPF policies, malformed terms, recursive limits or other permanent processing errors. For temperror, check authoritative/resolver availability and retry after recovery. Do not broaden an unrelated apex policy or ignore errors because DMARC passed.

Some DKIM keys remain unverified: Compare the keys with the active mode. Historical keys are not all mandatory. Keep required rotation records, and investigate dependencies before deleting old ones.

Verified domain, failing DMARC: Check the API domain or SMTP credential identity, From domain, envelope sender, and DKIM authority. Repeating DNS verification cannot fix a route using the wrong identities.

An inbox stops receiving after setup: Compare MX with the pre-change export immediately. Restore the intended inbound provider through the approved rollback process; do not continue an unintended receiving-domain migration.

If a new signing mode or application route fails, pause the affected rollout and coordinate restoration of the approved prior configuration and records. Reverify and retest after rollback; preserve shared keys and other domains. Keep originals restricted and redact unnecessary message content and personal identifiers before sharing diagnostics.

Keep one acceptance row per application, domain and signing mode, separating expected from observed identities. Include timestamp, DNS capture, From, evaluated SPF identity/result, all DKIM d=/s=/results, alignment, DMARC and restricted original-message location; mark untested fields pending. Also check links, replies and any intentionally changed receiving route, using more than one controlled recipient where practical. Include a forwarded sample if required, without confusing forwarding-specific SPF changes with the direct route.

Hand over the DNS record set, Mailgun domain and mode, public-query results, and message evidence. Review later DMARC reports for continuing traffic patterns and recheck after DNS migrations or domain changes.