Why does DKIM fail with h= tags and uncanonicalized headers?

You send a message with a valid DKIM signature, but the recipient’s server rejects it. The key checks out. The headers look correct. So why does the signature fail? Because of a tiny gap in the process: how headers are normalized before signing.

DKIM isn’t just about having the right cryptographic key—it depends on strict header canonicalization. Even one uncanonicalized header or a misconfigured h= tag can break the entire signature, regardless of the key’s validity.

The h= tag defines which headers contribute to the signature. If the sender lists headers that aren’t actually in the message, or includes ones with inconsistent capitalization, the receiving server computes a different canonical form—and the signature fails. This isn't a flaw in the algorithm—it's a mismatch between what was signed and what the server expects.

Key takeaways

  • The h= tag in DKIM must perfectly match the actual headers used in the canonicalized message; any mismatch causes signature failure.
  • Headers with inconsistent capitalization or extra whitespace are rendered uncanonicalized, breaking DKIM even if the key is valid.
  • Adding custom headers without ensuring they are consistently formatted across systems commonly leads to signature mismatches during validation.

What is header canonicalization in DKIM, and why does it matter?

DKIM requires that email headers be formatted consistently before signing—this is called header canonicalization. Without it, the signed headers on your server won’t match the ones the recipient’s server checks, causing verification to fail even if the key is correct. This mismatch breaks authentication and can trigger spam filters or outright rejection.

How canonicalization works: simple vs. relaxed

DKIM defines two canonicalization methods: simple and relaxed. Simple applies no changes—exact headers are used as signed. Relaxed lets you normalize capitalization and trim extra whitespace, making it more forgiving of minor formatting differences in transit.

Most modern email systems use relaxed canonicalization. But if your server signs with relaxed while the receiving server expects simple (or vice versa), the signature fails. That’s a common reason DKIM passes in testing but breaks in real-world delivery.

Why h= tag issues happen and how to fix them

The h= tag in DKIM signatures lists which headers were included in the signature. If the headers in h= don’t match the canonicalized version of the actual headers, the validation fails. For example, if a server lists from and to in h= but the actual message has a trailing space in From:, and relaxed canonicalization strips it—boom, mismatch.

Relaxed canonicalization is the norm today, but many older or misconfigured systems still expect simple. If your outbound server uses relaxed but your recipient expects simple, validation fails. The same applies in reverse. You can’t fix this just by changing a setting—both sides must agree on the canonicalization method.

For developers and admins: always verify your signing server and the receiver’s expectations match. This starts with checking your h= tag against the actual header order and formatting. A single case mismatch or extra space can break the chain.

Testing is essential. Use inbox placement tests to see how your emails perform across real mail providers. You’ll catch canonicalization mismatches before they hurt sender reputation—before a single bounce occurs.

For more granular control: ensure your email infrastructure uses consistent canonicalization. If you rely on third-party tools like SendGrid or AWS SES, confirm they’re using relaxed (which they typically are). Mismatched methods between sender and receiver remain one of the top overlooked causes of DKIM failure.

For deeper analysis: study RFC 6376, the standard that defines DKIM. It’s the authoritative source on how header canonicalization should work in theory and practice. You can’t guess—accuracy is non-negotiable.

How does the h= tag influence DKIM’s signature verification?

The h= tag in a DKIM signature explicitly defines which headers are included in the cryptographic hash during signing. If critical headers like From, Date, or Subject are missing from h=, or if the list contains duplicates or non-standard names, the verification process will fail—even if the rest of the signature is correct. Servers compute the hash using only the headers listed in h=, so any mismatch between the signing and verifying ends leads to rejection.

Why missing or incorrect h= values break verification

Let’s say you sign a message but forget to include the From header in h=. The receiving server will compute the hash without it, while your signature includes it—resulting in a hash mismatch. This is a common point of failure, especially in automated systems that don’t validate the full header list during signing. The same rule applies to Date and Subject: if they’re excluded from h= and not properly canonicalized, even small differences in formatting or order can invalidate the signature.

If h= lists multiple instances of the same header (like two From lines), or includes malformed or nonstandard header names, different email servers may canonicalize them differently. This leads to inconsistent hash results. For example, a server might remove duplicate headers during parsing, while another preserves them. Since canonicalization is part of DKIM’s verification steps, any deviation breaks alignment.

Case sensitivity and canonicalization traps

Some systems expect header names in the h= tag to match exactly—uppercase for From, lowercase for subject. Using mixed case like "from" or "FROM" can cause mismatches if the verifier enforces strict case rules. Even though RFC 6376 (the DKIM standard) allows for case-insensitive header name matching, many providers still enforce strict compliance. The key is consistency: if you sign with From, sign with From.

For real-world validation of these issues, tools like MailTester’s inbox placement test can simulate DKIM checks across major providers with real-world feedback, catching configuration problems before you send to real users.

DKIM is only as strong as its signing consistency. Always review the h= tag before sending. Use standard header names, avoid duplicates, and ensure the list matches exactly what’s being signed. When in doubt, validate the entire header set using a reputable email verification service such as MailTester’s API for real-time checks and detailed feedback.

How to diagnose DKIM failures caused by h= tag or uncanonicalized headers

You can diagnose DKIM failures tied to the h= tag or uncanonicalized headers by inspecting the email source for the exact header list in the signature, verifying that header names match exactly (case, spacing, order), and testing the message against a tool that logs the canonicalized header set. Use MxToolbox or MailTester’s inbox placement test to validate the signature in real-world conditions. Let’s walk through the key steps.

Check the DKIM-Signature header and verify the h= tag

  • Open the raw email source and locate the DKIM-Signature header.
  • Find the h= tag and list the header names it includes, like from:subject:date:message-id.
  • Compare each one exactly as written — no case changes, no added spaces, no missing or extra colons.
  • If your mail server adds or modifies headers (like Received: or Return-Path:), make sure they're not being included in h= without being listed in the signature.

Validate the canonicalization process and test with real tools

  • Use a DMARC/SPF/DKIM checker such as MxToolbox to input the raw message and see how the headers are canonicalized.
  • Check the tool’s report to see if the h= list matches the actual headers in the canonicalized form.
  • Replay the message through a testing tool that logs the canonicalized header list — this helps you spot mismatches between the signature and the actual message.
  • Test your email with MailTester’s inbox placement test to see if signature validation passes in real inbox environments.
  • If you're sending in bulk, use the bulk verification tool to catch misconfigured DKIM signs across your list early.
  • Refer to RFC 6376 (Section 3.5) on header canonicalization for how the rules apply in practice — the standards define how whitespace, line breaks, and case must be handled before signing.
Even small differences in header names — like Subject vs subject — will break DKIM validation. The system is case-sensitive and exact.

Common DKIM configuration errors involving h= tag and uncanonicalized headers

You’re signing the From header but leaving it out of the h= list — that breaks DKIM. You’re including Message-ID in h= even though some servers skip it during canonicalization. You’re using inconsistent capitalization in h= (like 'from' vs 'From') — DKIM is case-sensitive. You’re adding custom headers like X-Feedback-ID without listing them in h= — that causes a canonicalization mismatch. And you’re using trailing colons or extra whitespace in header names within h= — these aren’t trimmed properly, leading to signature fails. Fix these, and your DKIM alignment improves.

What’s actually going wrong with h= and headers

  • Don’t sign the From header unless it’s in the h= list. Omitting it breaks the signature — even if the header is present in the body. This is a common misstep in email infrastructure.
  • Don’t include Message-ID in h= unless your receiving server validates it. Some systems skip canonicalization for Message-ID, making it irrelevant in the signature. Refer to RFC 6376 for header canonicalization rules.
  • Use exact header names including capitalization. 'From' is not the same as 'from'. DKIM treats header names case-sensitive. Use consistent casing across your configuration.
  • Any custom header (like X-Feedback-ID, X-Notification-UID, or other non-standard fields) must be included in h= if you're signing it. Otherwise, the receiving server will treat it as uncanonicalized and reject the signature.
  • Remove any whitespace or trailing colons from header names in h=. For example, 'From:' or 'From ' breaks the canonicalization process. The standard specifies that header names should be normalized to lowercase and trimmed.

How to catch these issues before they cost you deliverability

These errors are hard to detect in isolation. Most tools won’t flag a DKIM failure unless you test the full email chain. Let’s test it with real-world data.

You can verify DKIM alignment alongside other email health signals using MailTester’s inbox placement test. It simulates real delivery across multiple inboxes and checks for alignment issues, including header canonicalization problems that break DKIM.

DKIM works only when the signature matches exactly what the receiver processes. Canonicalization isn’t optional — it’s enforced by RFC 6376 and widely implemented in modern email infrastructure. If you're seeing DMARC failures or inconsistent deliverability, check your h= list first.

How to fix DKIM with relaxed canonicalization and correct h= tags

Use relaxed canonicalization on both sending and receiving ends—it’s the most widely supported method and handles common header variations without breaking signatures. Ensure the h= tag lists only headers actually present in the message, in correct case, with no duplicates or extra spacing. Always test with a real email sent to a monitored inbox and inspect the full source to verify signature validation.

Step-by-step: Fixing DKIM with relaxed canonicalization

  1. Use relaxed canonicalization for both sending and receiving servers. It standardizes header processing across platforms and tolerates common formatting differences. This is recommended by the DKIM specification (RFC 6376) and widely adopted in modern mail systems.
  2. Verify the h= tag includes only headers present in the message. Include only headers your system adds, such as From, Date, Subject, and any custom headers used in your sending flow. Omit unused or optional headers like List-Id, Precedence, or Return-Path unless they’re part of your standard.
  3. Match header names exactly in case and spelling. Headers are case-sensitive in DKIM. "From" is valid; "from" or "FROM" is not. Use the exact case used in the message.
  4. List headers in the h= tag without spaces or extra characters. Use the format h=From:Date:Subject. Do not use spaces, such as h=From : Date : Subject. Extra spaces or formatting errors break signature validation.
  5. Test the full flow with a real sent email. Send a test message to a monitored inbox (like one from your MailTester inbox tester). Examine the full source via email client or mail server logs to confirm the signature matches the relaxed canonicalized header set.
  6. Validate all DKIM records via DNS and email tools. Use a service like MXToolbox or dmarcanalyzer.com to check DNS records and verify DKIM signature status in real time.

Common pitfalls and how to avoid them

One frequent error is assuming DKIM signs headers just because they're present in the message. It only signs the headers listed in the h= tag. If you include a header not actually sent (e.g., Reply-To) or misspell one (e.g., "Subect"), the signature will fail during validation.

Another issue is using strict canonicalization when relaxed is more appropriate. Strict mode requires exact header ordering and formatting. If your sending system modifies whitespace or adds headers on the fly, strict mode will consistently fail. Relaxed canonicalization handles these variations gracefully, making it the practical default.

Don’t rely solely on tools that show "valid" without testing real delivery. Valid DKIM in isolation does not mean inbox placement. Test delivery and signature validation in context using a real email sent to a monitored recipient. Use MailTester's inbox placement tool to verify how your emails land in real inboxes and ensure DKIM is processed correctly end-to-end.

Why uncanonicalized headers break DKIM signature verification

DKIM signatures rely on a strict, predictable format. If headers aren’t canonicalized—meaning they haven’t been normalized in case, whitespace, and line folding—the signing and verification processes disagree on what the message should look like. This mismatch causes validation to fail, no matter how correct the key or domain is. Even small inconsistencies, like extra spaces in the From: header, can break the signature.

Canonicalization isn’t optional—it’s mandatory

When you sign an email with DKIM, the signing agent canonicalizes the headers using specific rules from RFC 6376. This removes redundant spaces, lowers case, and folds multi-line headers into a single line. The h= tag in the signature lists which headers should be included in the process—and it references the original, uncanonicalized header names. If the From: header has extra spaces, the canonical version strips them, but the h= tag still expects the original format. This mismatch breaks the signature.

Let’s say you sign a message with From: John Doe. The canonical form becomes From: John Doe, but the h= tag still points to From: John Doe. The verifier processes the header normally and gets a different result than the signer. The signature is valid only for the canonicalized version. If the h= tag doesn’t match the original format, the check fails.

Received headers and line folding are common pitfalls

Headers like Received, which contain timestamps, IPs, and nested text, often span multiple lines. DKIM requires these to be folded into a single line with a single space between the parts. If you leave line breaks or multiple spaces, the canonicalization process produces a different string than expected—and the signature fails.

For example, a multi-line Received header without proper folding may look like:

Received: from mail.example.com (mail.example.com [192.0.2.1]) by mx.yourdomain.com with ESMTP; Tue, 15 Apr 2025 10:00:00 +0000

But DKIM needs it folded into a single line with one space between each part. If your signing agent doesn’t apply this rule, or if the h= tag includes the folded version but the signing process didn’t, verification fails.

It’s not just about the header name—it’s about the exact sequence of characters as they appear in the message. Any deviation between signing and verification causes a fail. This is why tools that test DKIM signature validity are essential. You can check whether your email headers are properly canonicalized and whether your h= tag lines up with expectations.

Use MailTester’s inbox placement and email checker tools to validate deliverability and header integrity before sending. They test your setup against real-world email infrastructure, helping catch issues like malformed DKIM signatures early.

How to ensure consistent header canonicalization across your sending platform

Relaxed canonicalization in your email service provider (ESP) is critical—many default to it, but you still need to verify it’s active. If your ESP applies strict canonicalization, headers with minor variations in spacing or order can break DKIM validation. Always test signatures with real receivers using tools that simulate inbox checks. Let’s break down the steps to keep header canonicalization consistent and avoid h= tag failures in DKIM.

Check your ESP’s default canonicalization behavior

  • Log into your ESP dashboard and check the DKIM signing settings—look for "relaxed" vs "strict" canonicalization.
  • Most modern ESPs default to relaxed canonicalization for headers, but this isn't universal. Verify it’s active for your sending domain.
  • If your ESP uses strict canonicalization, you’ll likely see signature failures on receivers that expect relaxed alignment—this includes Gmail and Outlook.
  • Refer to RFC 6376, Section 3.4 for how relaxed canonicalization treats whitespace and header order: RFC 6376.

Prevent post-signature header changes

  • Never modify headers after signing—adding or reordering them invalidates the DKIM signature, especially when h= tags don’t match the actual header set.
  • Your ESP or email system should apply canonicalization before signing, not after. If you're manually appending headers (like X-Tracker), do it before DKIM is applied.
  • Use the MailTester email checker to test individual addresses and verify that the final message structure aligns with DKIM expectations before sending.
  • Set up periodic testing of bulk campaigns with inbox placement tools like MailTester’s inbox tester to catch header misalignments before they affect deliverability.

Malformed headers aren’t always visible in the source—hidden whitespace, missing CRLF, or unquoted fields can break DKIM even if they look correct. Automated validation in modern ESPs helps, but you can’t rely on it alone. Combine built-in checks with independent verification.

  • Enable your ESP’s validation or integration check features—even if they’re not perfect, they flag the most common header errors.
  • Run full list verification through a tool like MailTester's bulk verification to catch addresses with bad headers before you send.
  • If you’re using the API for sending, integrate email validation into your workflow using the MailTester verification API to clean lists and reject invalid or misconfigured entries early.

DKIM works only when the signing and verification processes see the same header set. The h= tag must align exactly with the canonicalized headers. Consistent canonicalization across your senders, tools, and platforms is non-negotiable.

How MailTester helps catch DKIM configuration errors before they impact delivery

MailTester catches DKIM signature flaws—like incorrect h= tag values or uncanonicalized headers—before they cause bounces or spam filtering. It validates signatures using the full header context, simulates real inbox behavior, identifies bulk-sending risks, and even uses AI to spot header inconsistencies in raw messages.

Real-time API validation with full header context

You can’t verify DKIM without seeing how headers are actually structured when sent. MailTester’s real-time verification API checks the full header set, including all standard and custom fields, to ensure the h= tag matches the exact headers used in the signature. This prevents failures caused by inconsistent canonicalization—like when one header is added but not included in the h= list, or when whitespace differs between the signed and received headers.

For example, if your system adds a Received header during transit but omits it from h=, the signature fails. The API detects this mismatch by comparing the signed header set with the actual sent headers. You’ll catch it before a single message hits an inbox.

Learn how the API works in real time: verify individual addresses with full header analysis.

Simulating inbox placement and authenticator checks

Even if your DKIM signature passes technical validation, it may still be rejected. ISPs like Gmail and Microsoft use multiple checks—including header consistency—when evaluating deliverability. MailTester’s inbox-placement testing simulates how these systems assess your email, including DKIM validation using the full header chain.

Because it evaluates real-time header structures, it exposes issues like uncanonicalized header fields (e.g., “X-Header” vs. “x-header”) that are common in poorly configured systems. These small differences can trigger alignment failures even if the signature itself is technically valid.

For teams sending at scale, MailTester’s bulk list verification scans for sending patterns that lead to inconsistent headers across campaigns—such as dynamically inserted headers not reflected in h=. Fixing these early prevents high rejection rates on large mailings.

The in-app AI assistant can parse raw headers and flag issues like missing or incorrect h= values. It doesn’t just tell you the signature failed—it explains why, using plain language.

DKIM is strict. The h= tag must match exactly. Even a single header field not included causes failure. That precision is why tools like MailTester exist: to catch problems invisible to manual review.

For more on how email authentication works, see the official specification: RFC 6376 — DomainKeys Identified Mail (DKIM) Signatures.

What happens when recipients receive emails with failed DKIM due to h= tag errors?

When DKIM verification fails because of incorrect or missing h= tag settings, emails are often rejected, quarantined, or marked as spam by major ISPs like Gmail, Yahoo, and Outlook—even if SPF and DMARC are properly configured. This failure undermines sender reputation, and repeated issues can trigger throttling or blocklisting, ultimately damaging your domain’s long-term deliverability. Even a single flawed header canonicalization can undermine trust across the email ecosystem.

How DKIM failures impact deliverability and reputation

  • ISPs use DKIM as a core signal for authenticity. Failures lead to inbox placement drops, even if SPF passes.
  • Gmail and Yahoo apply strict DKIM validation; errors in h= often cause immediate rejection or spam filtering.
  • DKIM failure, even when SPF and DMARC are valid, can reduce your sender reputation score over time.
  • High volumes of DKIM failures correlate with increased risk of being flagged by blocklists like Spamhaus or Spamcop.
  • Some providers throttle or pause sending from domains with consistent DKIM failure rates, especially when paired with high bounce or complaint rates.

Common root causes and real-world consequences

  • The h= tag defines which headers are included in the DKIM signature. Misconfiguring it can cause signing to use the wrong header order or content.
  • If headers are not canonicalized correctly—especially with line folding, trailing whitespace, or capitalization mismatches—signature verification fails.
  • Some email systems add or modify headers post-signing (e.g., auto-adding tracking tags), breaking the signature if the h= list doesn’t account for them.
  • Using a non-standard or uncanonicalized header (like Subject: Re: Meeting with inconsistent capitalization) can cause mismatches during verification.
  • A single email with a misconfigured h= tag can be flagged by spam engines, especially when sent at scale.
  • Over time, repeated failures can result in permanent domain reputation damage, requiring weeks or months to repair.

DKIM is only effective if the signing and verification processes agree on what headers are signed and how they’re formatted. For detailed testing, you can check how your headers are canonicalized using real inbox placement tools that analyze the full message chain. MailTester’s inbox placement tester simulates delivery across inboxes and validates header integrity before you send.

Key takeaway: Fix h= tags and canonicalization to ensure reliable DKIM

DKIM signatures can fail silently if headers aren’t canonicalized or if the h= tag lists incorrect or inconsistently formatted headers. Even a single typo in the h= tag can cause rejection across multiple ISPs.

These issues are often missed in isolated tests. Validate DKIM under bulk sending conditions to catch subtle problems that affect real-world deliverability.

Use tools like MailTester—with 98.9% accuracy—to detect configuration flaws before they harm your sender reputation or list hygiene.

Sources

Keep reading

Ready to put this into practice? MailTester verifies emails with 98.9% accuracy — start with 100 free verifications.

Frequently asked questions

What does the h= tag in DKIM do?

The h= tag specifies which headers are included in the DKIM signature. If the header list is incomplete or mismatched, the signature won't validate.

Why does DKIM fail when headers are uncanonicalized?

DKIM requires standardized header formatting. If headers are not normalized in case or whitespace, the signed content differs from the verified version, causing failure.

Can case sensitivity cause DKIM signature failure?

Yes. Header names in the h= tag must exactly match the case used in the message. Mismatched case breaks canonicalization and signature validation.

How do you know if you're using relaxed canonicalization?

Check your sending platform’s documentation or use a DKIM verifier. Relaxed allows case normalization and whitespace trimming across headers.

What’s the difference between simple and relaxed canonicalization?

Simple maintains exact header content. Relaxed standardizes case, trims whitespace, and folds multiline headers. Relaxed is preferred in practice.

Should I include Message-ID in the h= tag?

No. Most mail servers do not include Message-ID in DKIM signature checks. Including it can cause unnecessary failure if not handled correctly.

Can custom headers break DKIM?

Yes. If a custom header is included in the signature but not listed in h=, or if it’s improperly formatted, it breaks the signature.

How can I test my DKIM configuration?

Use tools like MxToolbox or MailTester’s inbox placement test. Examine the full email source, verify the h= tag, and ensure headers are properly canonicalized.

Why use MailTester for DKIM verification?

It checks DKIM validity as part of inbox placement testing with 98.9% accuracy. It identifies malformed headers and h= tag errors before sending to real users.

What happens if I change the order of headers in h=?

DKIM signatures are sensitive to ordering. The h= tag must list headers in the exact order they appear in the message.