Contents
Why DKIM failure is a family of problems
DKIM authentication is foundational to email delivery in 2026, required by the bulk sender rules and weighed heavily by every major mailbox provider. When DKIM fails, mail risks the spam folder or outright rejection. But the phrase DKIM failure hides an important truth: it is not one error, it is a family of distinct failures, each with a different root cause and a different fix. An operator who treats DKIM failure as a single problem and applies a single fix will frequently fix nothing, because the fix for one failure type does not address another.
This guide exists to give operators a clear map of that family. The four failure types, body hash mismatch, key not found, signature verification failure, and alignment failure for DMARC, look superficially similar in a DMARC report (they all show as a DKIM fail) but are entirely different problems. The structure of this guide: how DKIM verification actually works, the four failure types laid out, then each one in depth with its cause and fix, configuring PowerMTA's domain-key directive correctly, DKIM key rotation, and the diagnostic workflow that identifies which of the four an operator is facing. The central message is that diagnosis begins with classification: identify which failure type, then apply that type's fix.
How DKIM verification works
To understand the failure types, start with how DKIM verification works when it succeeds.
When PowerMTA signs an outbound message, it does several things: it computes a hash of the message body and stores it in the bh= tag of a DKIM-Signature header; it computes a cryptographic signature over a set of selected headers plus that body hash, using the private signing key; and it records, in the DKIM-Signature header, the signing domain (the d= tag) and the selector (the s= tag) that identify which public key the receiver should use.
When a receiving server verifies the signature, it does the reverse: it reads the DKIM-Signature header to get the d= domain and the s= selector, retrieves the corresponding public key from DNS, independently computes the hash of the body it received and compares it to the bh= value, and uses the public key to verify the cryptographic signature over the headers and body hash.
For DMARC, one more check applies: alignment. The receiver checks whether the d= signing domain matches the From header domain. DMARC requires the signature to both verify and align.
Each step in this process can fail independently, and that is why DKIM failure is a family: a body modification breaks the body hash comparison, a DNS problem breaks the key retrieval, a key mismatch breaks the signature verification, and a domain mismatch breaks the alignment, while the other steps may all be fine.
The four failure types
The four DKIM failure types, summarized:
| Failure type | What broke | Root cause category |
|---|---|---|
| Body hash mismatch | The body was modified after signing | An intermediary altered the message |
| Key not found | The receiver could not retrieve the public key | A DNS publishing problem |
| Signature verification failure | The cryptographic signature did not validate | A key mismatch or corruption |
| Alignment failure | DKIM verified but the d= domain does not match From | Signing with the wrong domain |
These four are genuinely different problems. A body hash mismatch and a key-not-found error have nothing in common except that both appear as a DKIM fail in a DMARC report. Fixing a DNS publishing problem does nothing for a body modification problem.
The diagnostic discipline this guide builds toward is simple to state: when DKIM is failing, the first job is not to fix it, it is to classify it. Identify which of the four types is occurring, and only then apply that type's specific fix. The classification comes from reading the DKIM result detail, in the message headers and in DMARC aggregate reports, which distinguishes the types.
Body hash mismatch
The body hash mismatch is the most common DKIM failure type. It occurs when something modifies the email body after the sending server signed it.
PowerMTA signs the message and stores the body hash in the bh= tag. The receiving server computes the hash of the body it received. If the two differ, the body was changed in transit, and DKIM fails with a body hash error, frequently reported as body hash did not verify or dkim=neutral (body hash did not verify).
The culprits are intermediaries that alter the message between the sender and the recipient:
- Footer injection. Mailing lists such as Mailman, Google Groups, and Listserv, and corporate email systems, append disclaimers or unsubscribe links to outbound messages. The appended text changes the body, so the hash no longer matches.
- Link rewriting. Security gateways like Proofpoint URL Defense, Mimecast, and Barracuda rewrite URLs in the message body for click-time scanning. Every rewritten link changes the body.
- Content scanning. Antivirus and data-loss-prevention gateways decode, inspect, and re-encode MIME parts. Even normalizing line endings or character encoding breaks the hash.
The important realization: a body hash mismatch is frequently not a problem with the sender's configuration at all. It is the expected consequence of an intermediary modifying the message. For mail passing through a mailing list that appends a footer, a body hash failure is essentially expected behavior, the list changed the body, so of course the hash no longer matches.
The sender's response:
- Minimize post-signing modification under the sender's own control. Ensure nothing in the sender's own pipeline modifies the body after PowerMTA signs it.
- For forwarding and mailing-list scenarios, ARC. Authenticated Received Chain is the mechanism designed to preserve authentication results across intermediaries that modify messages. ARC lets a forwarder vouch for the authentication results it saw before it modified the message.
- Accept that some body hash failures are not the sender's to fix. A body hash failure caused by a recipient's corporate gateway re-encoding MIME is the gateway's behavior, not a sender misconfiguration.
Key not found
The key-not-found failure occurs when the receiving server cannot retrieve the DKIM public key from DNS. It is reported as dkim=neutral (no key found), dkim=temperror, or key not found.
The receiver reads the d= domain and the s= selector from the DKIM-Signature header and looks up the public key at the corresponding DNS location, the selector under _domainkey under the signing domain. If that DNS lookup fails to return the key, verification cannot proceed.
The causes of a key-not-found failure are all DNS publishing problems:
- The DNS record was never published. The DKIM public key TXT record was not added to DNS.
- The selector is wrong. The s= selector in the DKIM-Signature header does not match the selector name the DNS record was published under.
- DNS has not propagated. The record was added recently and has not propagated to the receiver's resolver yet.
- The record was deleted. The DKIM TXT record was removed, perhaps accidentally or during a DNS change.
- A syntax problem in the record. Missing tags, broken quotes, truncated values, or extra spaces in the DKIM DNS record can prevent the receiver from reading it.
The fix is to correct the DNS publishing: publish the record if it is missing, correct the selector name so it matches what PowerMTA signs with, wait for propagation if the record is new, restore a deleted record, or fix the syntax. The key consistency that must hold is that the selector PowerMTA uses to sign, and the domain it signs with, must point at a DNS record that exists, is correctly named, and contains the matching public key.
Signature verification failure
The signature verification failure occurs when the receiver found the public key and the body hash matched, but the cryptographic signature itself does not validate.
This means the signature is present, the key was retrieved, but the math does not check out: the signature was not produced by the private key corresponding to the published public key, or the signed headers were altered, or the signature value is corrupted.
The causes:
- A key mismatch. The private key PowerMTA signs with does not correspond to the public key published in DNS. This is the most common cause, frequently arising when keys were rotated and the DNS record holds an old public key while PowerMTA signs with a new private key, or vice versa.
- A miscalculated or corrupted signature. The signing process produced an incorrect signature value, or the DKIM-Signature header was corrupted.
- A modified signed header. If one of the headers covered by the signature was altered after signing, the signature over those headers no longer validates.
- An incorrect public key in DNS. The published public key value is wrong, perhaps from a copy-paste error introducing a subtle alteration.
The fix centers on the key correspondence: the private key PowerMTA uses to sign and the public key published in DNS must be a matching pair. The diagnostic is to confirm that the public key in the DNS record genuinely corresponds to the private key in PowerMTA's domain-key configuration. If they do not match, either the DNS record needs the correct public key, or PowerMTA needs to be configured with the private key matching what is published. A copy-paste error in the DNS record, even a subtle one like an extra space, can break the correspondence, so the published key should be verified carefully.
Alignment failure for DMARC
The alignment failure is the type that, by practitioner consensus, trips up more operators than the actual verification failures, because the DKIM signature appears to pass.
DKIM verification and DKIM alignment are separate checks. Verification confirms the signature is cryptographically valid. Alignment confirms the signing domain, the d= value in the DKIM-Signature header, matches the From header domain. DMARC requires alignment: for DKIM to satisfy DMARC, the signature must verify AND the d= domain must align with the From domain.
So a message can have a perfectly valid, cleanly verifying DKIM signature and still fail DMARC, because the signature was applied with a domain that does not match the From domain.
The alignment failure is dangerous precisely because it hides. The operator checks DKIM, sees it pass verification, and concludes DKIM is fine, while DMARC continues to fail on the DKIM side because the signature does not align. The signature is genuinely valid, it just was not applied with a domain matching the From header. When DMARC is failing but DKIM appears to pass, do not stop at the verification result, check alignment specifically: compare the d= domain in the DKIM-Signature header against the From header domain. If they do not share the organizational domain, that is the alignment failure, and it is the real problem.
The classic alignment failure: a sender's mail is DKIM-signed with an ESP's or a third party's domain rather than the sender's own domain. The signature verifies fine because the ESP holds the matching key, but the d= domain is the ESP's domain while the From header shows the sender's domain. DKIM does not align, and DMARC fails on the DKIM side.
The DMARC adkim tag governs how strict the alignment check is. Relaxed alignment, the default, requires the d= domain and the From domain to share the same organizational domain, so a subdomain can align with the parent. Strict alignment requires an exact match. Either way, an ESP's entirely different domain does not align.
The fix is to ensure DKIM signing uses the sender's own domain as the d= value, so the signing domain aligns with the From domain. For PowerMTA, this means the domain-key directive must sign with the correct domain matching the From header. For mail sent through an ESP, it means configuring custom domain authentication in the ESP so the ESP signs with the sender's domain rather than its own.
Configuring the PowerMTA domain-key directive
PowerMTA performs DKIM signing through the domain-key directive. Correct configuration prevents the failure types that originate in the sender's setup.
The domain-key directive associates a selector, a signing domain, and a private key file:
<virtual-mta primary-vmta>
smtp-source-host 203.0.113.60 mail.example.com
domain-key selector1,example.com,/etc/pmta/keys/example.pem
</virtual-mta>The three parts of the domain-key value:
- The selector (selector1) names the DKIM selector. This must match the selector name the public key is published under in DNS, at selector1._domainkey.example.com.
- The signing domain (example.com) is the d= value the signature will carry. This must match the From header domain for alignment, the critical point for avoiding the alignment failure.
- The private key file path points to the private key PowerMTA signs with. This private key must correspond to the public key published in DNS, the critical point for avoiding the signature verification failure.
Getting the domain-key directive right addresses two of the four failure types directly. Signing with the correct domain matching the From header avoids the alignment failure. Signing with a private key that corresponds to the published public key avoids the signature verification failure. The key-not-found failure is a DNS problem outside PowerMTA, but the selector in the domain-key directive must match the DNS record's selector. The body hash mismatch is caused by intermediaries and is not a PowerMTA configuration matter.
For a sender using multiple From domains, each domain needs its own domain-key configuration so each message is signed with a domain matching its own From header. A message from one domain signed with a key for a different domain produces an alignment failure.
DKIM key rotation
DKIM keys should be rotated periodically as a security practice, and rotation is a common source of signature verification failures if done carelessly.
The risk in rotation is the window where the private key PowerMTA signs with and the public key published in DNS do not correspond. If PowerMTA is switched to a new private key before the new public key is published, or the old public key is removed before PowerMTA stops using the old private key, signatures fail to verify during the gap.
The safe rotation procedure uses a new selector so old and new keys coexist:
- Generate a new key pair and choose a new selector name for it.
- Publish the new public key in DNS under the new selector, alongside the existing record.
- Wait for the new DNS record to propagate.
- Update PowerMTA's domain-key directive to sign with the new selector and the new private key, and reload.
- Confirm via DMARC reports that mail signed with the new selector is verifying.
- After a grace period, at least 7 days and 14 for safety, during which no mail still in transit is signed with the old key, remove the old selector's DNS record.
The new-selector approach means the old and new keys are both valid simultaneously during the transition: mail signed with the old selector still verifies because the old DNS record is still there, and mail signed with the new selector verifies because the new record is published. There is no gap where signatures fail. Rotating by reusing the same selector and swapping the key is what creates the dangerous gap; using a fresh selector avoids it.
The diagnostic workflow
The workflow for diagnosing a DKIM failure:
Step 1: get the DKIM result detail. The classification depends on detail beyond a bare DKIM fail. Two sources provide it: the Authentication-Results header of a received test message, which states the specific DKIM result, and DMARC aggregate reports, which show DKIM results across the sending sources. Send a test message to an account that exposes full headers, or read the DMARC reports.
Step 2: classify the failure type. From the result detail, identify which of the four:
| Result detail | Failure type |
|---|---|
| body hash did not verify | Body hash mismatch |
| no key found / temperror / key not found | Key not found |
| signature did not verify (key present, body ok) | Signature verification failure |
| dkim=pass but DMARC fails on DKIM | Alignment failure |
Step 3: for a body hash mismatch, identify the modifying intermediary. Is the mail passing through a mailing list, a forwarder, or hitting a recipient's security gateway? Confirm whether the modification is under the sender's control (fix the sender's pipeline) or an external intermediary (consider ARC, and recognize some failures are expected).
Step 4: for a key not found, check DNS. Verify the DKIM TXT record exists at the selector the signature uses, the record is syntactically correct, and DNS has propagated. Use a DKIM record lookup tool.
Step 5: for a signature verification failure, check the key correspondence. Confirm the public key published in DNS corresponds to the private key in PowerMTA's domain-key configuration. A mismatch, often from a careless rotation, is the usual cause.
Step 6: for an alignment failure, compare d= against From. Read the d= domain in the DKIM-Signature header and compare it against the From header domain. If they do not share the organizational domain, fix the signing to use the sender's own domain.
Step 7: apply the type-specific fix and verify. Apply the fix for the identified type, then send a fresh test and confirm via the Authentication-Results header and the DMARC reports that DKIM now passes and aligns.
Step 8: monitor with DMARC reports. DMARC aggregate reports show DKIM results across all sending sources over time. Ongoing monitoring catches a DKIM failure trend early, before it significantly affects inbox placement, and shows which specific stream is failing so the fix is targeted rather than guessed.
An operator we worked with was investigating persistent DMARC failures. Their DMARC aggregate reports showed a steady rate of DMARC failures, and they were puzzled because they had set up DKIM long ago and every test they ran showed DKIM passing. They would send a test message, check the Authentication-Results header, see dkim=pass, and conclude DKIM was working. Yet DMARC kept failing. The issue was the alignment failure, the type that hides behind a passing DKIM result. Their mail was sent through an ESP for one particular stream, and for that stream the ESP was DKIM-signing the messages with the ESP's own domain, not the operator's domain. The signature was genuinely valid, it verified cleanly every time, which is why every test showed dkim=pass. But the d= domain in those signatures was the ESP's domain, while the From header carried the operator's domain. DKIM passed verification and failed alignment, so DMARC failed on the DKIM side for that entire stream. The operator had been checking the wrong thing for a year: they kept confirming DKIM verification, which was fine, and never checked DKIM alignment, which was the actual failure. The fix was to configure custom domain authentication in the ESP, so the ESP signed that stream's mail with the operator's domain instead of its own. Once the d= domain matched the From domain, DKIM aligned, and the DMARC failures for that stream stopped. The lesson is the core point about the alignment failure: DKIM passing verification is not the same as DKIM satisfying DMARC. A valid signature applied with the wrong domain passes every DKIM verification test and fails DMARC alignment every time. When DMARC fails while DKIM appears to pass, the alignment is what to check, and the d= domain versus the From domain is exactly the comparison that reveals it.
DKIM signature verification failure is not one problem but four: a body hash mismatch from an intermediary modifying the message, a key-not-found error from a DNS publishing problem, a signature verification failure from a key mismatch, and an alignment failure where a valid signature does not match the From domain. They look alike in a DMARC report but have entirely different causes and fixes, so diagnosis begins with classification. PowerMTA's domain-key directive, configured to sign with the correct domain and a private key matching the published public key, prevents the two failure types that originate in the sender's setup. Careful key rotation with a fresh selector avoids the verification failures rotation can cause. And the alignment failure, the one that hides behind a passing DKIM result, deserves specific attention, because checking DKIM verification is not the same as checking DKIM alignment. Operators who classify the failure type before reaching for a fix, and who check alignment whenever DMARC fails while DKIM appears to pass, resolve DKIM problems precisely; operators who treat DKIM failure as a single error apply fixes that miss the actual problem.