Fix DKIM h= Tag Error

Why Is Your DKIM Signature Failing with an 'h=' Tag Error?

You sent an email. It passed DNS checks. The SPF aligned. But the DKIM signature failed—specifically with an "h=" tag error. You’re not alone.

This error isn’t about your content or timing. It’s about the exact format of the headers your email server included during signing. Even a single space too many, a capitalization mismatch, or an unexpected newline can break the signature when the validator expects a rigid, canonicalized list.

DKIM signatures are strict. They rely on a precise, predictable header order and formatting. If your email client, script, or third-party tool alters that structure—even slightly—the validator rejects it as unverifiable.

You’re not misconfiguring your domain. You’re just sending with headers that don’t match the spec. The fix? Not a domain change. Just making sure your signing process follows the canonicalization rules precisely.

Key takeaways

A DKIM 'h=' error means your email headers weren’t formatted in the exact order and syntax required by the DKIM specification.
Even minor formatting differences—extra whitespace, inconsistent capitalization, or missing line breaks—can break the signature verification process.
Third-party tools and custom scripts are common sources of uncanonicalized headers; verify your email engine’s header output before sending.

What Does the 'h=' Tag in DKIM Mean, and Why Does It Matter?

The h= tag in a DKIM signature defines exactly which headers are included in the signature’s canonicalization process. It’s not a suggestion—it’s a strict instruction: only the headers listed in h= must be present, in the exact order specified, or the signature will fail. Even a single missing header, a reordering, or a minor format change breaks verification.

Headers Are Not Just Included—They’re Verified Exactly as Listed

DKIM works by hashing a specific set of headers and comparing that hash to the signature. The h= tag tells the receiver: “These are the only headers that matter.” If your email has a h=From:Subject: list but the server sees From:Date:Subject:, the signature fails—not because the headers are wrong, but because the order changed.

Even a space or case difference in a header name can trigger a mismatch. For example, From: versus from: might seem minor, but DKIM treats them as different. This is standardized in RFC 6376, which governs DKIM. The canonicalization process is precise, and deviations are not tolerated during verification.

Why This Matters for Deliverability and Authentication

If the h= tag includes headers that don’t exist in your email, or if they’re altered in transit (by a relay, filter, or mailing system), the signature will fail. A failed DKIM check often leads to rejected emails, placement in spam folders, or blocked inbound messages. You might be sending legitimate content, but the technical mismatch breaks trust.

This is especially common in email platforms that auto-add headers (like Received: or Message-ID:) without updating h=. Or when email clients or forwarding systems modify existing headers. The sender must either exclude unnecessary headers from h= or ensure those headers are preserved exactly as signed.

Use tools like MailTester's email checker to validate the full DKIM structure, including header list integrity, before sending. It tests real-world delivery conditions, not just syntax.

For ongoing sender health, especially in high-volume environments, regularly verify your DKIM configuration using a real verification API. MailTester’s API helps catch alignment and signature issues across bulk sends, ensuring h= remains accurate and consistent.

The Root Cause: Canonicalization Mismatch Between Sender and Recipient

You’re seeing the "DKIM signature h= tag with uncanonicalized header list error" because your DKIM signature lists specific headers in the h= tag, but the receiving server canonicalizes headers differently—either using a different method (like relaxed vs. simple) or including extra headers not in the list. This mismatch breaks verification, even if the signature itself is mathematically correct. It often happens when the signing process doesn’t match the recipient’s canonicalization expectations.

How DKIM Canonicalization Works

Digital signatures in DKIM rely on a consistent input. That input starts with the header and body canonicalization process—one of two standard methods defined in RFC 6376. The sender must agree with the receiver on which headers to canonicalize (simple vs. relaxed) and which ones are included. If you use h=From:Subject:Date, but your server adds Message-ID during header cleaning (a relaxed canonicalization), the receiver sees extra headers not in the list, rejecting the signature.

Even subtle differences matter. For example, if you set h=From:Subject and your sender includes To or CC in the signature process, but the receiver only checks the headers listed, it fails. The receiving server will reject the signature because it can't validate what it didn’t expect. This happens even if you sign correctly—your implementation doesn't align with the recipient’s expectations.

Why Mismatch Occurs in Practice

Many email systems apply relaxed canonicalization by default, which strips whitespace and normalizes case. If you’re using simple canonicalization but your provider expects relaxed, the headers don’t match. Or, you may have used automated tools that inject headers like DMARC-Result or Feedback-ID during signing but forgot to include them in h=. These extra headers break the validation check, even if they're technically harmless.

It’s not always your fault—some providers assume relaxed and some don’t. The key insight is that the DKIM signature is only valid if the entire message, from sender to receiver, has been canonicalized the same way. Even one misaligned header or a mismatched canonicalization method breaks the chain.

You can test DKIM alignment using tools like MXToolbox or RFC 6376, which define the canonicalization standards. Checking the actual headers in flight with real-world recipients helps spot mismatches early.

If you're managing email sends at scale, running a bulk verification beforehand can catch domains that are known to be inconsistent or poorly configured. You can test your full list with MailTester’s bulk verification tool, which checks deliverability, syntax, and common signing issues—including DKIM alignment—before you send.

How to Diagnose a DKIM h= Tag Error in Your Email

Open the full email headers and check the DKIM-Signature line for the h= tag. Compare it exactly—case, order, and spacing—to the actual headers in the message. Even a single missing header or extra space breaks the signature. Use a tool like MxToolbox or MailTester’s inbox placement test to inspect the raw headers and validate the list against what your server actually signed.

Step-by-Step Diagnosis Process

Fetch the raw email headers from your inbox or delivery log. Most mail clients let you view them via "Show Original" or "View Source." This is the only way to see the full DKIM-Signature header with the h= tag.
Locate the DKIM-Signature header in the output. It starts with Dkim-Signature: and contains a list of headers like h=from:subject:to:date:…. Note every header listed there.
Compare the list in h= to every actual header in the email. Check for: case mismatches (e.g., From: vs from:), extra spaces, omitted headers, or reordering. Even a single difference invalidates the signature.
Verify header order and formatting. The DKIM specification requires the list in h= to match the order and syntax of the headers as they appear in the message, without altering case or whitespace. See RFC 6376 for the full rule set.
Reproduce the signing process on your mail server or sending platform. If you’re using a service like SendGrid or Amazon SES, confirm it’s not altering headers before signing. Some systems normalize headers in ways that break the original.

Tools That Help You Spot the Error

Use a trusted header analyzer like MxToolbox’s DKIM checker or MailTester’s inbox placement test to inspect the full DKIM-Signature line and validate it against your actual email headers. These tools show exactly what’s signed and where the mismatch occurs.

The 5 steps described in “Step-by-Step Diagnosis Process”, in order.

A DKIM signature must be applied to a consistent, unaltered header set. The h= tag is the contract between sender and receiver: if the list doesn’t match the actual headers, the DMARC policy will fail and the email may be rejected or marked as spam.

Step-by-Step: Fix the DKIM h= Tag Uncanonicalized Header List Error

When your DKIM signature fails with an "uncanonicalized header list" error, it means the headers listed in the h= tag don’t match the actual headers in your email, or their order, spacing, or capitalization is off. Fixing it requires checking the exact list in h=, aligning the real headers to that list, and resending with proper canonicalization. The key is precision — DKIM checks every character.

Extract and Verify the Header List

Open your email’s raw source (in Gmail, click “Show original” or in Outlook, use “View > Source”). Look for the DKIM-Signature: header.
Identify the h= value — for example, h=from:to:subject:date:content-type:. This is the exact list your server must use in canonicalization.
Compare this list to the actual headers in the raw email. Any mismatch — extra headers, missing ones, or different order — will break DKIM validation.

Fix the Headers and Resign

Ensure every header listed in h= appears exactly once in the email, in the exact order. No duplicates, no omissions.
Remove any headers not in the list (e.g., reply-to if not in h=). Add any missing ones (e.g., if message-id is needed but absent).
Check capitalization: From and from are different. DKIM is case-sensitive. All header names must match the h= tag exactly.
Ensure no whitespace, extra punctuation, or line breaks between headers in the h= list. The list must be contiguous and exact. Use tools like RFC 6376 to review canonicalization rules for relaxed and simple methods.
Resign the email using the correct header list and the intended canonicalization method. Most modern services default to relaxed for headers but verify your provider’s choice.
Resend the email. Use a header analyzer tool, like the one at MXToolbox, to re-check the new DKIM-Signature line and confirm the h= list is now valid.

Once fixed, your DKIM signature will pass validation. This error is common when using legacy email tools or manually editing headers. Regularly auditing your email headers can prevent resubmission delays and delivery issues. Test your sender reputation with a real inbox placement check before sending to large lists.

The 3 steps described in “Extract and Verify the Header List”, in order.

For bulk list validation to avoid sending to invalid or improperly formatted addresses, use our bulk email verification tool. It checks for syntax, syntax, deliverability, and other issues that can break DKIM and SPF.

Common Mistakes That Trigger h= Tag Failures

You’re getting DKIM signature errors with h= tag mismatches because your signed headers don’t match the list in the h= parameter. The most common causes are: adding custom headers without listing them, using mixed-case header names, adding unexpected whitespace or newlines, and letting tools auto-inject headers without updating h=. Let’s walk through the exact missteps to fix.

Header List Mismatches

Adding tracking headers like X-App-ID or X-Tracking without including them in the h= list breaks the signature.
Using inconsistent capitalization—e.g., From instead of from—triggers mismatches because DKIM is case-sensitive on header names.
Spelling or formatting changes in header names (like extra spaces or line breaks) alter the canonical form and invalidate the signature.

Automated Tools and Canonicalization

Using email tools or libraries that inject headers (like X-Message-ID or X-Sent-With) without updating the h= list can cause signature failures. These tools assume you’ll handle it—often you don’t.
Switching from simple to relaxed canonicalization mid-implementation without adjusting the h= list leads to mismatches. The signing process treats the headers differently, so alignment must be complete.
Many systems assume header order doesn’t matter, but DKIM canonicalization does depend on it—reordering or inserting newlines between headers breaks the hash.

These errors are common because DKIM signature implementation is easy to get wrong. The RFC 6376 standard specifies how headers must be processed, but few tools enforce it strictly. It’s not about being “more secure”—it’s about following the exact rules to avoid rejection.

If you’re sending bulk emails, use a service that checks DKIM alignment before sending. MailTester’s inbox placement tests include DKIM validation and highlight header mismatches before you send.

DKIM Canonicalization: Simple vs Relaxed — Which One Should You Use?

Use relaxed canonicalization for headers unless your provider explicitly requires simple. Most modern email systems expect relaxed, and forcing simple can break signatures even when the content is correct. The key is consistency: what you use to sign must match what the verifier expects.

What’s the Difference Between Simple and Relaxed?

Simple canonicalization treats every character exactly as it appears—case, spacing, and order matter. A single extra space or mixed-case header name breaks the validation. Relaxed canonicalization ignores minor formatting differences: headers are converted to lowercase, extra whitespace is normalized, and order can vary.

For example, if your DKIM signature includes "From: [email protected]" with a trailing space, simple canonicalization sees that as different from "From: [email protected]" without it. Relaxed ignores the space and still validates. This makes relaxed more practical for real-world email delivery.

Which One Do You Actually Need?

Most major email providers—including Gmail, Outlook, and Yahoo—require relaxed canonicalization. Their systems are built to handle the natural variations in how headers get formatted across different email clients and servers. Trying to force simple validation often leads to false failures.

That said, some mail systems—particularly those in regulated industries or internal compliance environments—still enforce strict, simple canonicalization. If you’re sending through a private email gateway or a compliance-heavy platform, confirm their expectations first. Mismatched canonicalization is a silent failure: no warning, just lost delivery.

And here’s the rule: the signing and verifying sides must agree. If you sign with relaxed but verify with simple, the signature fails. The same holds if you swap them. It's not about which is "better"—it’s about alignment.

According to RFC 6376 (the standard for DKIM), relaxed canonicalization is the norm. The spec explicitly defines it as the preferred method for header processing. You’ll find this practice echoed in guides from major senders and deliverability resources like the Spamhaus Project and the official DKIM specification.

Let’s say you're testing a DKIM signature and hitting the "h= tag with uncanonicalized header list" error. You're likely using simple when you should use relaxed. Or worse—your sending platform uses relaxed, but your validation tool expects simple. Always check the tool’s documentation and ensure the settings match your configuration.

Before sending bulk emails, verify your DKIM setup with a real inbox placement test. Use MailTester’s inbox placement report to see how your message lands in real inboxes, including whether DKIM validation passes.

How MailTester Helps You Prevent DKIM Signature Failures

MailTester catches DKIM signature issues like malformed h= tags early by validating the full header structure during inbox placement tests and real-time checks. You fix errors before they trigger bounces or spam filters.

Detailed Header and DKIM Validation

When you test an email’s inbox placement with MailTester, we don’t just check deliverability—we validate the entire cryptographic chain, including DKIM signatures. This includes examining the h= tag for correctly listed headers, ensuring they match the canonicalized header set used in the signature. A mismatch here often leads to rejection by receiving servers.

Our inbox placement tester simulates real-world delivery conditions across major inboxes like Gmail and Outlook. If a DKIM signature fails due to uncanonicalized header lists, you receive an exact, actionable report—not just a generic failure. This is part of why major email providers rely on standards like RFC 6376 for DKIM validation.

Proactive Detection via Real-Time and Bulk Verification

Using our real-time verification API, you can detect malformed DKIM signatures—including issues with the h= tag—before sending campaigns. This is especially useful when integrating with transactional systems or automated workflows.

For larger lists, our bulk verification feature identifies domains with recurring header canonicalization problems. You see which domains consistently fail DKIM validation, allowing you to clean or exclude them before sending. This prevents reputational damage from sending to domains with broken signing practices.

The in-app AI assistant doesn’t just flag errors—it explains them. Need to understand why a header was dropped during canonicalization? It references Section 6.2 of RFC 6376, which defines header canonicalization rules, and suggests how to adjust your signing configuration. It’s not guessing—it’s helping you apply standards correctly.

Verify DKIM and Sender Identity Before Every Major Send

You can prevent DKIM signature errors like the h= tag mismatch by validating your domain’s DKIM setup before sending to new lists or after email infrastructure changes. Use real-time verification tools to catch issues early, ensuring your messages arrive in inboxes—not spam folders. This step directly reduces bounce rates and strengthens sender reputation.

How to catch DKIM issues before they cost you deliverability

Run a full DKIM signature check on your sender domain using MailTester’s email checker before launching any major campaign.
Verify that the h= tag in your DKIM signature matches the exact header names sent in the email — including capitalization and order — as outlined in RFC 6376.
Check for uncanonicalized header lists by testing your email in MailTester’s inbox placement tester to see how your message appears across major providers.
Use MailTester’s verification API to automate DKIM checks when adding new domains to SendGrid, Mailchimp, or HubSpot.
Integrate MailTester with your ESP via the integrations page to validate all outbound messages at scale, catching malformed headers before delivery.
Run a dry run on a sample list of 100–1,000 addresses using bulk verification to detect infrastructure misconfigurations across multiple recipients.

Why this matters: the consequence of unverified DKIM

DKIM failures — especially header mismatches — are a red flag to inbox providers. A single invalid signature can trigger filtering even if the rest of your email is clean. The h= tag must exactly reflect the canonicalized header list used in signing. If it doesn’t, your message is rejected or marked as suspicious.

According to RFC 6376, the header list in the DKIM signature must be in the same order as the message, with standardized capitalization and no extras. Even minor deviations break validation.

Validating DKIM before every major send isn’t just about avoiding bounces. It’s about maintaining sender reputation. ISPs like Gmail and Outlook use signature validity as one of many signals to determine inbox placement. A verified signature reduces spam risk and improves long-term deliverability.

Let’s be clear: you can’t trust your email infrastructure unless you test it. Use MailTester’s real-time checks to verify that your domain signs messages correctly — before they go out.

Final Word: DKIM Errors Are Not Just Technical—They’re Deliverability Risks

An uncanonicalized DKIM header list directly undermines email authentication. When the 'h=' tag lists headers in a non-standard order, DMARC policies fail to validate the message, meaning delivery is blocked or marked as suspicious.

These errors are not isolated parser glitches—they degrade sender reputation, trigger spam filters, and increase the risk of blacklisting. A single misconfigured DKIM signature can affect all subsequent outbound messages from the domain.

Catching and fixing the 'h=' tag issue early prevents bounces, protects domain reputation, and ensures consistent inbox placement. Regular audits with tools like MailTester help maintain strong authentication, not just after problems arise but as part of routine deliverability hygiene.

Sources

Since May 5, 2025, Microsoft Outlook requires SPF, DKIM, and DMARC from domains sending 5,000+ emails per day, rejecting non-compliant mail outright at the SMTP level with error 550 5.7.515. — Microsoft Outlook requirements (via MailOver bulk-sender requirements guide) (2025)
DMARC adoption among top domains surged 75% between 2023 and 2025 — from 27.2% to 47.7% — in the wake of Google and Yahoo's bulk-sender authentication requirements. — EasyDMARC 2025 DMARC Adoption Report (2025)

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 DKIM 'h=' tag mean in an email signature?

The 'h=' tag lists the exact headers included in the DKIM signature’s canonicalization process. Any deviation causes validation failure.

Can extra headers in an email break DKIM signing?

Yes, if the extra header isn't listed in the 'h=' tag, it invalidates the signature. All headers in 'h=' must be present, and only those headers should be included.

Why does capitalization matter in DKIM header lists?

DKIM header values are case-sensitive. 'From' and 'from' are treated as different headers. Use lowercase in the 'h=' tag to avoid errors.

Does mail server software handle DKIM canonicalization automatically?

Most modern email systems do, but only if configured correctly. Misconfigured senders or third-party tools often break canonicalization order.

Can inconsistent whitespace break a DKIM signature?

Yes. Extra spaces, newlines, or tab characters alter header structure and cause canonicalization mismatches, invalidating the signature.

How do I test if my DKIM is properly canonicalized?

Use MailTester’s inbox placement test or MxToolbox to analyze the DKIM-Signature header. Compare the 'h=' list to actual headers in the email.

Is it safe to use 'relaxed' canonicalization instead of 'simple'?

Yes, but only if the receiving server supports it. Most do, but some require 'simple'. Always match your signing method to your receiver’s expectations.

Do DKIM failures affect my sender reputation?

Yes. Repeated DKIM failures signal poor authentication, which harms sender reputation and increases spam risk.

How often should I verify DKIM signatures?

Verify before every major send, or during list cleaning. Use automated testing via MailTester’s API to catch issues early.

Can MailTester detect DKIM h= tag errors?

Yes, MailTester checks DKIM signatures in real-time and flags issues like uncanonicalized header lists or misaligned 'h=' tags.