DKIM Body Hash Mismatch Email Troubleshooting Guide

A DKIM "body hash mismatch" means the verifier hashed the received message body using the canonicalization (c=) and optional body-length (l=) rules in the DKIM signature and got a different value from the signature's bh= value. It indicates a body-hash verification failure, not by itself proof that the message was malicious or that delivery will fail. Use the steps below to collect evidence, identify the cause, apply a safe fix, and verify with a controlled test.

Direct diagnosis: what the symptom usually means and what it does not prove

Observed fact

• The receiver reports dkim=fail with a body-hash detail, or the received message's DKIM-Signature contains a bh= value that does not match the verifier's calculation.

What that usually means (concise)

• The body bytes covered by the signature changed after signing, or the signing implementation produced a signature or body hash that does not match the DKIM rules. A verifier uses the c= and l= values in the signature; it does not choose a preferred canonicalization independently.

What it does not prove

• It does not prove the message is spam, malicious, or that mailbox providers will drop or quarantine the message. Authentication failures can increase the chance of quarantine or Junk routing, but delivery outcomes depend on additional signals and policy. (Illustrative.)

Important signal separation

• Treat these as separate signals: DKIM signature verification result, the published DMARC policy for the domain, any Authentication-Results header produced by the receiver, and the final delivery disposition (delivered, quarantined, rejected). None alone guarantees inbox placement.

Demo example. Authentication failure diagnosis. Synthetic results for feature explanation; not a live test or customer outcome.

Evidence to collect before changing anything

Collect the following artifacts from both sender-side and receiver-side sources; do not change DNS or message signing settings until you have at least the minimum items below.

Minimum evidence to capture (explicit steps)

• Raw received message source as delivered to the recipient (View original / Show source). Include the full set of headers and the complete MIME body.
• The Authentication-Results header as added by the receiver (exact header text).
• The DKIM-Signature header(s), especially selector (s=), domain (d=), canonicalization (c=), body length tag (l=) if present, body hash (bh=), and signature (b=).
• The Received headers to trace the message path and any intermediate MTA that might have rewritten MIME or applied transformations.
• Sender-side signing configuration: DKIM selector details, canonicalization choice, use of body length tag, signing library or MTA, and whether a mailing list or gateway was involved.
• Any gateway or mailing-list logs that show message modification (footer insertion, link re-writing, content-type or encoding changes).

Label scenarios (for clarity)

• When you collect these, label each source as "recipient raw", "sender signed copy", "gateway/intermediary snapshot" — this clarifies whether a modification happened before or after signing. All scenario descriptions below are illustrative unless you captured the evidence.

Do not perform DNS or DMARC policy weakening before evidence review

• Do not change DMARC p= (policy) from reject/quarantine to none to “fix” delivery without documented authorization and a rollback plan. Emergency exceptions must be narrowly scoped, time-limited, and owner-approved.

A symptom-to-cause decision tree

Use this compact decision table to map observed evidence to the most likely next diagnostic step. Each row is illustrative and assumes you have the raw message source and DKIM-Signature header available.

Observed evidence (illustrative)	Possible explanation (illustrative)	Next safe diagnostic action
The same DKIM signature passes against a sender-side copy, but fails against the delivered copy; the canonicalized body differs	An intermediary changed body content covered by the signature	Compare sender, gateway, and recipient copies; locate the first hop where the canonicalized body changes
The signature includes l=	Only the first l= canonicalized body octets are hashed; an edit inside that range can cause a mismatch, while content appended beyond it can remain unhashed	Calculate the covered length under the signature's c= rule; inspect for both changed signed content and any unsigned suffix
The signature's body canonicalization is simple and the body contains whitespace differences	Those differences may affect the hash; relaxed normalizes only the whitespace changes defined by DKIM	Compare the bodies after applying the signature's specified canonicalization; do not assume the receiver expects a different c= value
A gateway changed MIME or transfer encoding between sender and recipient copies	The transformation may have changed body octets that remain significant after canonicalization	Compare MIME boundaries, encodings, and canonicalized body bytes at each hop
A gateway added a footer or rewrote links, then created a second DKIM signature	The original signature can fail while the later signature passes; each signature is evaluated separately	Inspect every DKIM-Signature and its d=, s=, c=, and l= values; confirm which signer signed the delivered body

Label every scenario you evaluate as illustrative unless you have direct logs or raw-message captures confirming it.

Possible root causes to investigate

These are diagnostic categories, not a ranking by frequency. Confirm a cause against raw-message captures or gateway logs before changing configuration.

1. A downstream system modifies the message body
   • A mailing list, gateway, or transport rule can add a footer, rewrite links, or sanitize HTML after signing. Microsoft identifies post-signing body modification as a cause of a body-hash verification failure.
2. Forwarding or an intermediate relay transforms the body
   • A change to MIME encoding, line content, or other body octets can cause a mismatch if the change is not normalized by the signature's body canonicalization.
3. The body canonicalization does not tolerate a change
   • The verifier follows the body-canonicalization algorithm in c=. simple preserves more body differences; relaxed normalizes specified whitespace patterns, but neither permits arbitrary content changes.
4. A body-length tag (l=) is misunderstood or incorrectly generated
   • The verifier hashes only the first l= canonicalized body octets. A change within that range can cause a mismatch. Appended content beyond the range can remain unsigned while the body hash still verifies.
5. A MIME or transfer-encoding transformation changes covered body octets
   • Compare the actual encoded message body at each hop; a change in encoding is a lead to investigate, not proof of the cause by itself.
6. The signing library or MTA generates an incorrect signature
   • Non-standard newline handling or an implementation error can produce a bh= value that does not match a compliant verifier's calculation.
7. The message has multiple DKIM signatures
   • Multiple signatures are not, by themselves, a body-hash failure. If an intermediary changes the body and signs it again, the original signature may fail while the later signature passes; evaluate each signature independently.

All of the above are plausible; label any specific assignment of cause as illustrative unless backed by the evidence you collected.

Safe remediation steps with clear limitations

Separate observed evidence, possible causes, and recommended actions. Apply changes in a controlled manner and document owner approvals.

If evidence shows an intermediary modified the body

• Action: Coordinate with the intermediary (mailing list admin, gateway owner) to:
  • Either sign after the intermediary edits (if they support signing), or
  • Configure them to avoid changing the original signed body (stop adding inline footers, avoid rewriting links), or
  • Implement ARC (Authenticated Received Chain) on the intermediary if supported, so a receiver that trusts the sealer can evaluate preserved upstream authentication results.
• Limitation: You may not be able to stop a third-party list from modifying messages; use an alternate route or sender-domain signing strategy if needed.
• ARC does not repair the original DKIM signature or guarantee that a receiver will trust the ARC sealer.

If canonicalization is involved

• Action: Compare sender-side and recipient-side bodies after applying the body-canonicalization method specified in c=. If whitespace changes are the only confirmed difference, test a signature using relaxed body canonicalization on a test selector.
• Limitation: A verifier follows the signature's c= value; it does not expect the sender to use relaxed canonicalization. Relaxed canonicalization tolerates only specified whitespace changes, not footers, rewritten links, or arbitrary edits. A test selector is safer than replacing a production signing configuration.

If a body-length tag (l=) is present

• Action: Verify how many canonicalized body octets the signature covers and compare the changed bytes with that range. On a test selector, compare full-body signing without l=.
• Limitation: Appended bytes beyond l= can remain outside the hash and therefore unsigned; this may create a content-integrity risk even when bh= verifies. Removing l= is not a general fix for changes within the covered range.

If transfer encoding or MIME changes occur

• Action: Ensure the sending MTA emits stable Content-Transfer-Encoding and canonical CRLF line endings. Replicate the send under identical encoding.
• Limitation: Some receiving MTAs force encoding changes; test and coordinate.

If you suspect a signing library bug

• Action: Upgrade the signing library/MTA, test with a new selector, and compare bh= values between sender-saved and recipient-saved raw messages.
• Limitation: Upgrades require staging and rollback plans.

What you must not do

• Do not weaken DMARC enforcement (p=none/quarantine/reject) as a general “fix” without explicit domain owner approval and a rollback plan. Any emergency relaxation should be narrowly scoped and time-limited.

How to verify the change with a real message or controlled test

Verification steps

1. Create a controlled test message that reproduces the original message characteristics (MIME parts, attachments, HTML vs text, typical headers).
2. Send the test message through the same route(s) the original used (same ESP, same gateway, same mailing list if possible).
3. Capture the raw delivered message at a recipient mailbox and compare:
   • DKIM-Signature header(s) and bh= value in the delivered message.
   • Authentication-Results header added by the receiver.
   • Whether DKIM now shows pass for the selector you tested.
4. If available, compare the sender-side saved signed copy (what the signer produced) with the recipient raw copy byte-for-byte to identify where the first difference appears.
5. If you changed signing parameters (new selector, canonicalization), test multiple variations to confirm the minimal required change.

What the verification proves and what it cannot

• Proves: whether the modified signing configuration or upstream change removed the body hash mismatch for that message path.
• Does not prove: that all future messages will be accepted or that mailbox placement will be unchanged — mailbox providers use many signals. Do not interpret a DKIM pass as a guarantee of inbox placement.

Use a DKIM validation tool or your mailbox provider's diagnostic headers to read Authentication-Results and the DKIM result. The header name to look for is Authentication-Results (exact text).

Anonymized example adapted from a supplied product report. Selected figures retained; identifiers and layout reconstructed. Not a new live test.

Prevention and monitoring checklist

Checklist for ongoing prevention (apply progressively)

• Ensure consistent signing across all outgoing systems; centralize DKIM signing when possible.
• Consider relaxed body canonicalization only when confirmed benign whitespace changes are the issue, and test first with a non-production selector. It does not protect against arbitrary body edits.
• Avoid using l= unless there is a specific need and you understand that content beyond the covered length is not included in the body hash.
• Standardize MIME formatting and Content-Transfer-Encoding on the sending path.
• If third-party gateways or mailing lists must modify messages, consider ARC or require the intermediary to sign after editing; neither option makes the original signature pass.
• Monitor Authentication-Results headers from recipient mailboxes for new failures.
• Keep DMARC reports enabled and monitor aggregate feedback (do not use policy changes to troubleshoot).
• Follow the current sender guidance from Gmail and Microsoft. Their recommendations cover email authentication, but a DKIM pass does not guarantee inbox placement. See Sources.

Decision checklist (quick)

• Collected recipient raw message and DKIM-Signature bh= value
• Retrieved sender-side signed copy and signing parameters
• Identified any intermediary in Received headers
• Performed controlled test with alternate canonicalization or selector
• Verified Authentication-Results and DKIM pass on test message

FAQ

What exactly causes the DKIM "body hash mismatch" error?

It occurs when the verifier's hash of the covered, canonicalized body does not match the signature's bh= value. A post-signing change to covered body bytes is one possible cause; incorrect signing output is another. Use raw-message evidence to distinguish them. The verifier follows the signature's c= and, when present, l= values.

If DKIM fails, should I change DMARC to p=none immediately?

No. Do not weaken a DMARC enforcement policy without domain-owner authorization and a clear rollback window. Investigate the root cause, test fixes, and coordinate before changing DMARC.

Can a mailing list be fixed so DKIM passes?

The list can avoid changing the signed body, sign after making its edits, or use ARC to convey prior authentication results. ARC does not make the original DKIM signature pass, and receiver handling depends on whether the ARC sealer is trusted.

What does the l= tag mean for appended content?

The verifier hashes only the first l= canonicalized body octets. Content appended beyond that limit can be left unhashed without causing a body-hash mismatch, so a passing bh= does not prove the entire delivered body was signed. Without l=, the hash covers the full canonicalized body.

Run an InboxPlacement test to verify authentication signals and mailbox placement after applying the recommended changes.

Sources

• RFC 6376, Sections 3.4 and 3.7, defines body canonicalization and the bh= calculation, including the optional l= body-length limit. Read RFC 6376
• Microsoft documents dkim=fail (body hash didn't verify) as a possible result when the message body is modified after signing, and discusses ARC for intermediary changes. Troubleshoot email authentication in Microsoft 365
• Google recommends SPF, DKIM, and DMARC for senders and documents its authentication requirements. Gmail email sender guidelines

Related Reading

• DKIM Tester: How to Validate Results and Fix Common Errors
• How To Read Email Headers For Deliverability: Diagnosis, Common Failure Patterns, and Next Steps
• SPF DKIM DMARC Alignment Explained: Field Guide