The fastest way to troubleshoot DKIM failures is to prove four things in order: the message was signed, the selector resolves to the right public key, the receiver validates the signature, and the authenticated domain matches the domain path DMARC expects. I use a layered set of tools for that: a DKIM record checker, Gmail Show original, Outlook.com or Microsoft message headers, authoritative DNS lookups with dig, and a controlled Postfix plus OpenDKIM test inbox when the failure is stubborn.
The key point is that DKIM troubleshooting is not one test. A public checker tells you whether the DNS record and key syntax are sane. A mailbox provider tells you how a real receiver judged the signed message. A local validator helps prove whether your own code is wrong or the sender really broke the signature.
The fast answer
When the error says DKIM failed, I avoid changing DNS first. I separate the failure into signing, DNS, validation, message mutation, and DMARC domain match. That keeps the investigation short and stops teams from rotating keys when the body hash was changed after signing.
- Signed: Confirm the delivered message has a DKIM-Signature header. If there is no signature, the sending system never signed that message.
- Selector: Read the s= and d= values, then query the selector record at the exact domain shown by the signature.
- Receiver: Send the same stream to Gmail and Outlook.com, then inspect Authentication-Results instead of trusting only one validator.
- Mutation: Check for body hash failure, MIME rewriting, footer injection, link rewriting, line-ending changes, or gateway changes after signing.
- Decision: If several independent receivers fail, fix the sender. If only your validator fails, debug your parser or crypto library.
A DKIM troubleshooting flow from signature capture to fixing the source.
Rule I use
No single mailbox provider is a reference implementation. Gmail is useful because it is widely used and practical. Microsoft receivers are useful because they expose DNS and encoding issues that other receivers miss. A clean answer comes from comparing more than one result.
First decide what failed
People often say DKIM failed when they mean different things. DKIM itself can fail because the cryptographic signature does not validate. DMARC can also fail its DKIM path even when DKIM passes, because the signing domain does not match the visible From domain closely enough for the DMARC policy.
DKIM validation failed
This is a signature problem. The receiver found a DKIM-Signature header, fetched the public key, and still rejected the cryptographic check.
- Key: The public key does not match the private key used to sign.
- Body: The message body changed after signing.
- Header: A signed header was added, removed, folded, or rewritten.
- DNS: The selector record is missing, stale, malformed, or intermittently unavailable.
DMARC DKIM path failed
This is a domain match problem. DKIM can pass, but DMARC still rejects the DKIM route because the d= domain is not the visible From domain or an accepted organizational match.
- From: The visible From domain is the domain DMARC evaluates.
- Signer: The d= domain in the DKIM signature belongs to the signer.
- Match: The signer domain must match DMARC's domain rules.
- Fallback: SPF can still pass DMARC if its authenticated domain matches.
This distinction matters because the fix lives in a different place. A validation failure belongs with the sender, DNS host, or post-processing gateway. A DMARC domain match failure belongs in the sending domain setup, vendor configuration, or From domain strategy.
Which tools to use
For a quick public selector check, use Suped's DKIM checker. It validates the DKIM DNS record, parses the public key, and shows whether the selector is ready for signing. For a broader check across authentication records, I use the domain health check so I can see DKIM, SPF, and DMARC together.
After that, the best tools depend on what you need to prove. I use DNS tools for selector existence, mailbox headers for receiver behavior, and a local OpenDKIM validator when I need to isolate a validator bug from a broken sender.
|
|
|
|---|---|---|
Suped DKIM checker | Selector DNS | No body mutation test |
Suped health check | SPF, DKIM, DMARC | Broader than one selector |
Gmail Show original | Live receiver result | Forgiving DNS behavior |
Outlook.com headers | Receiver sensitivity | Noisy with forwarding |
dig or nslookup | DNS proof | Manual interpretation |
Postfix and OpenDKIM | Controlled lab | Takes setup |
Practical DKIM troubleshooting tools and when to use them.
Gmail Show original displaying SPF, DKIM, DMARC, and Authentication-Results.
A practical troubleshooting sequence
I start with the exact delivered message, not a screenshot of a failure badge. DKIM verification depends on the final headers and final body as received. If a forwarding service, mailing list, security gateway, CRM, or footer tool changed the message after signing, the sending platform can look correct and the receiver can still be right to reject the signature.
- Capture: Save the full original source from the receiver that reports the failure.
- Parse: Read d=, s=, a=, c=, h=, bh=, and b= from the DKIM-Signature header.
- Resolve: Query selector._domainkey.domain from authoritative DNS and a public resolver.
- Compare: Confirm the public key is the active key for the sending service.
- Send: Send a fresh test to Gmail and Outlook.com, then compare Authentication-Results.
- Repeat: If the result is split, send to a controlled Postfix and OpenDKIM validator.
- Fix: Change one variable at a time, then send a new message through the same route.
Header fields to capturetext
Authentication-Results: mx.example; dkim=fail reason=signature did not verify header.d=example.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=example.com; s=selector1; h=from:subject:date; bh=base64-body-hash; b=base64-signature
The selector record check belongs early in the sequence because it is cheap and removes a large class of false leads. If the selector does not resolve, has a malformed key, or returns different answers across resolvers, signature validation cannot be trusted.
DKIM checker
Check selector records and public key configuration.
?/7tests passed
After the selector is clean, the live message matters more than the DNS record alone. A correct public key does not save a message whose body changed after the signature was created.
DNS and selector checks
Most DKIM DNS problems are selector mistakes, stale keys, split DNS, missing CNAME targets, or TXT records that were pasted with broken quotes. I check both the exact selector from the message and the selector that the sending platform says it uses. Those are not always the same after a key rotation.
Example DKIM public keydns
selector1._domainkey.example.com TXT v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
DNS checksbash
dig +short TXT selector1._domainkey.example.com dig @8.8.8.8 +short TXT selector1._domainkey.example.com dig @1.1.1.1 +short TXT selector1._domainkey.example.com dig +trace TXT selector1._domainkey.example.com
Intermittent DNS matters
Intermittent DKIM failures often come from DNS inconsistency. One resolver has the new key, another resolver has the old key, and a receiver lands on the wrong answer. That creates failures that look random until you check authoritative DNS and public resolvers side by side.
- Authoritative: Check the domain's real name servers, not only the cached answer from one resolver.
- Public: Compare a few public resolvers so propagation and cache behavior are visible.
- Rotation: Keep the old key published long enough for in-flight mail to finish delivery.
- CNAME: Follow delegated selector records to the final TXT answer and validate that target too.
When the signature itself breaks
A valid selector record does not guarantee a valid DKIM result. The signature can fail after DNS is perfect because the message was changed after signing. If the receiver reports a body hash mismatch, work through body hash failures before rotating keys.
Hosted mail systems add another trap. A tenant can have DKIM enabled in the admin portal, but a custom domain, selector, or CNAME target is still wrong. For Microsoft tenants, I separate DNS setup issues from known receiver behavior and keep a focused path for Microsoft DKIM failures.
Broken before signing
- Wrong key: The platform signs with a private key that does not match DNS.
- Bad selector: The message points at a selector that is not published.
- Weak method: The signature uses an algorithm receivers reject.
- Bad header: The signer includes the wrong header set in h=.
Broken after signing
- Footer: A compliance or marketing footer changes the signed body.
- Gateway: A security appliance rewrites links or attachments.
- MIME: A relay changes transfer encoding or line endings.
- Forwarding: A forwarder changes content before the final receiver checks DKIM.
Body hash cluetext
Authentication-Results: mx.example; dkim=fail reason=body hash did not verify header.d=example.com
Decision confidence
Use the number of independent signals to decide whether to fix the sender, DNS, or your validator.
Low confidence
1 signal
One private validator fails and receiver headers pass.
Medium confidence
2 signals
One live receiver fails and DNS has a clear mismatch.
High confidence
3+ signals
Several receivers and a local validator fail the same message.
Ready to close
pass
New test mail passes at live receivers and DNS is stable.
Where Suped fits
Suped's product is the best overall practical choice when DKIM troubleshooting needs to connect to ongoing authentication monitoring. A one-off checker is useful for a selector lookup. Suped connects that check to DMARC monitoring, SPF and DKIM visibility, automated issue detection, real-time alerts, and steps to fix the exact source causing failures.
DKIM checker sample results showing selector, DKIM DNS record, validation checks, parameters, and share link
The workflow I like is simple: validate the selector, monitor the domain, then use issue history to prove whether a failure belongs to DNS, a sender, or a receiver path. That is where Suped's hosted DMARC, hosted SPF, SPF flattening, hosted MTA-STS, MSP dashboard, and blocklist (blacklist) monitoring fit into the same operational view.
- Detect: Suped surfaces authentication issues and groups them by domain, source, and failure type.
- Alert: Real-time alerts help catch a broken selector or sender change before it becomes a long incident.
- Fix: Issue pages give concrete steps, so the team has the DNS or platform action to take next.
- Scale: Multi-tenant views help agencies and MSPs manage many domains without mixing up clients.
Views from the trenches
Best practices
Check selector DNS before debugging code, then compare authoritative and cached answers.
Send fresh tests to at least two major mailbox providers before blaming one validator.
Keep old DKIM keys published during rotation so delayed messages still validate.
Common pitfalls
Treating a DNS lookup pass as proof that a delivered message still validates at the inbox.
Ignoring body changes from footers, link rewriting, relays, and MIME normalization.
Assuming Gmail pass means every receiver will pass the same DKIM signature without testing.
Expert tips
Use a controlled OpenDKIM inbox when you need to separate sender bugs from parser bugs.
Compare Gmail and Microsoft headers because they expose different failure patterns.
Look at the exact d= and s= values in the failed message, not the expected setup.
Marketer from Email Geeks says a second validator helps separate a local parser bug from a sender signature that is broken everywhere.
2022-07-12 - Email Geeks
Marketer from Email Geeks says a Postfix and OpenDKIM test inbox in debug mode can expose unusual algorithm behavior.
2022-07-12 - Email Geeks
The practical answer
To troubleshoot DKIM failures, start with the failed message source, read the DKIM-Signature fields, verify the selector in DNS, compare live receiver headers, then test with a controlled validator if the answer is still unclear. The tools are not interchangeable: DNS checkers prove record validity, mailbox headers prove receiver behavior, and local validators prove whether a parser or sender is at fault.
If the signature fails everywhere, fix the sender, key, selector, or post-signing modification. If it fails only in your tool, debug the validator. If DKIM passes but DMARC fails, fix the domain match between the signing domain and the visible From domain. Suped is strongest when that work needs to move from one-off troubleshooting into continuous monitoring, alerts, and repeatable fixes across domains.
