What causes a DKIM verification error with z= tag mismatch?

You sent a message that passed SPF, but DKIM fails with a z= tag mismatch. The header values in the signature don’t match the headers when the receiver processed the email. That’s not a typo. It’s a canonicalization mismatch.

DNS records can be perfect, but if the headers don’t align between signing and verification, the key doesn’t unlock. It’s like handing a locksmith the right key, but the door was installed with a different lock format.

Here’s what actually breaks it: how whitespace, line breaks, and folding are handled differently between sender and receiver. The z= tag is a checksum of the canonicalized header set. If one side treats line endings or extra spaces differently, the checksum fails—even if the content is correct.

Key takeaways

  • A z= tag mismatch means the canonicalized headers during signing don’t match those used during verification
  • Header folding, inconsistent whitespace, or differing line-end formatting between sender and receiver are the most common causes
  • Verification tools that simulate real receiving servers help catch these issues before deployment

How does header canonicalization affect DKIM validation?

DKIM validation fails if the header canonicalization method used by the sender doesn't match the one applied by the receiver. The header field names and values must be normalized identically during signing and verification—differences in whitespace, capitalization, or line folding can invalidate even a correct DKIM signature. This mismatch is a common cause of "z= tag mismatch" errors. You can catch these issues early with thorough email verification.

What is header canonicalization in DKIM?

When a message is signed with DKIM, the sender applies a canonicalization method to the email headers before creating the digital signature. There are two methods: simple and relaxed. The relaxed method ignores certain whitespace and treats field names as case-insensitive, while simple preserves exact formatting. If your email client or ESP uses simple-lf (no line folding), but the receiving server applies relaxed-lf, the resulting header digest will differ—leading to a signature failure.

For example, if a header field like Subject is split across lines with a soft line break, simple treats that as part of the content, but relaxed folds it into a single line. If the sending system uses simple but the receiving server expects relaxed, the hash won’t match—resulting in a z= tag mismatch. This isn’t a key problem, but a formatting inconsistency in the canonicalization step.

How to prevent header canonicalization mismatches

Let’s say you're sending emails via an ESP or custom SMTP. Always confirm that the canonicalization method used in signing matches what the receiving server expects. Most modern servers default to relaxed, so if you sign with simple, you risk failure. The error won’t be obvious in a bounce—it only appears as a DKIM validation failure in logs or DMARC reports.

This is why testing your sending setup with tools that simulate real inbox conditions is critical. You can test how your messages are interpreted by checking deliverability before going to scale. MailTester’s inbox placement tester lets you verify how your emails behave across major inboxes, including whether DKIM and SPF align correctly during real-world delivery.

Why does the z= tag in DKIM signatures matter?

The z= tag in a DKIM signature lists the exact headers included in the digest calculation. If your email client or server canonicalizes headers differently than the sender did — for example, signing only From and Subject but canonicalizing Date too — the resulting digest changes. The z= tag no longer matches the actual headers used, causing DKIM verification to fail, even if the signature is mathematically valid.

How header canonicalization affects the z= tag

Let’s say you sign just From and Subject. The sender’s DKIM signature includes z=From:Subject:. But when the receiver applies relaxed header canonicalization, it normalizes the Date header as well. Since Date wasn't in the original hash, the digest no longer matches. The receiver sees a mismatch: the expected headers don’t match what was actually signed. This triggers a DKIM verification error.

It’s not just about the values. The order, spacing, and inclusion of headers during the signing process are baked into the hash. Different canonicalization rules (relaxed vs. simple) on sending and receiving ends can lead to silent failure. The z= tag is a checksum of your process — if the process differs, the tag becomes meaningless.

Fixing the mismatch: alignment is key

Most reputable email providers expect aligned canonicalization. If your system uses relaxed header canonicalization during signing, the receiver must apply the same during verification. This is why DKIM alignment with SPF and DMARC matters more than just having valid signatures.

For senders, always test how your software handles canonicalization. Check the raw headers of your outbound emails — tools like RFC 6376 define the exact rules for relaxed and simple header processing. Tools that don’t enforce consistent canonicalization will consistently fail validation.

For recipients, use tools that check both the signature and the header match explicitly. You can test this manually with MXToolbox’s DKIM analyzer, or use automated solutions that verify both the cryptographic validity and header alignment.

Preventing z= mismatches isn’t about changing the signature — it’s about ensuring your email system signs and the receiving system checks using the same rules. If you're sending at scale, verify your DKIM setup with a tool that checks the entire chain. MailTester’s inbox placement tester can help spot delivery issues tied to authentication failures — including those from malformed or mismatched DKIM signatures.

What happens when header canonicalization is inconsistent?

When header canonicalization differs between the signing and validating servers, the DKIM signature digest fails to match, triggering a "z= tag mismatch" error. Even a single extra space, a line break where expected, or reordered headers can produce different canonicalized output, invalidating the signature—despite the message content being otherwise correct. This inconsistency breaks authentication, often resulting in email rejection or marking as spam.

Why small differences matter in header processing

DKIM relies on exact agreement in how headers are processed before signing and verifying. Let’s say your email client adds two spaces after a header field separator instead of one—this tiny change alters the canonicalized input. Because the signature is computed from a hash of the entire header block, even one character difference produces a completely different digest.

Line folding (wrapping long lines) must be handled identically. If the signing server folds a header at 78 characters but the verifier treats it as unfolded, the resulting canonicalized string will differ. Likewise, field order isn't arbitrary—signing servers typically use the order they receive headers, while receivers may reorder them during processing. This leads to mismatched outputs.

Common real-world triggers of these mismatches

Mail transfer agents (MTAs) and content filters often modify headers en route, especially after passing through gateways or content sanitizers. A rule set that strips whitespace or rewrites line breaks can break DKIM verification. Even email clients inserting tracking pixels or rewriting URLs might alter header structure during delivery. These changes are invisible to the sender but lethal to validation.

The RFC 6376 specification (which defines DKIM) explicitly requires strict conformance to canonicalization rules—both the simple (simple) and relaxed (relaxed) forms. If one side uses relaxed and the other simple, the results diverge. Misconfigured DMARC policies can compound confusion by flagging even valid emails as failed when DKIM doesn’t align.

Understanding this helps explain why some emails pass validation in one environment but fail in another. If you're troubleshooting DKIM, ensure your MTA, ESP, and any middleboxes apply the same canonicalization rules. You can test this by sending a message with known headers through multiple endpoints—tools like MailTester’s email checker help verify header integrity and signal if anomalies exist before sending.

How to debug a DKIM verification error with z= tag mismatch

When a DKIM verification fails with a z= tag mismatch, it means the headers used during signature verification don’t match the ones listed in the z= tag. The most common cause is inconsistent header canonicalization between signing and validation. Let’s walk through how to isolate and fix it step by step.

  1. Retrieve the full email header, including the full MIME structure, from your mail server or sending tool.Many tools strip or alter headers during transit. You need the original, unmodified version to compare accurately to the DKIM signature.
  2. Extract the DKIM-Signature header and note the z= tag and the list of fields it references.Look for something like z=from:to:subject;. Each field must precisely match the one used in the signature process.
  3. Apply the sender’s canonicalization method — either relaxed-lf or simple-lf — to the header portion of the email.DKIM uses header canonicalization to normalize whitespace and line breaks. RFC 6376 defines these methods; using the wrong one will invalidate the signature.
  4. Compare the final set of canonicalized header fields with the ones listed in the z= tag.If any field is missing or a field appears that wasn’t listed, you’ve found the mismatch. This typically points to misconfigured signing logic or header modifications in transit.
  5. If fields don’t match, the issue lies in how headers were processed during signing or reception.Common causes include third-party email gateways rewriting headers, misconfigured DKIM signing tools, or incorrect canonicalization in your email system.

Common Missteps to Watch For

Even small changes — like removing a header field, adding a blank line, or altering case — can break the canonicalization. Some ESPs or email relays silently modify headers, especially in the Received: or Message-ID: fields.

Let’s say your mail system signed with relaxed-lf but the receiving server used simple-lf. The resulting header digest won’t match, triggering a z= tag mismatch error.

Verify Before You Send

Proactively avoid this issue by testing your email setup with real inbox placement tools. MailTester’s inbox placement tester checks how your emails appear across real inboxes — including DKIM validation and header consistency. This helps catch misconfigurations before your campaign goes live.

Common causes of DKIM z= tag mismatch

DKIM z= tag mismatches often occur when the header canonicalization used during signing doesn’t match what the receiving server applies during verification. This happens most frequently when MTAs inject or alter headers without re-signing, when email clients fold whitespace inconsistently, or when sending tools use different canonicalization rules than expected. Let’s break down the real-world triggers.

Header modifications during transit

  • MTAs adding custom headers like X-Message-ID or X-Original-To without re-signing the message breaks DKIM validation—only the signed headers should be trusted.
  • Forwarding services (like Gmail or corporate relay systems) often rewrite To:, CC:, or Subject: fields. If the DKIM signature isn’t adjusted, the z= tag fails during canonicalization.
  • Some inbound email gateways rewrite Received: headers. Even minor changes like timestamp updates can alter the expected digest.

Client-side and tooling misconfigurations

  • Outbound email tools (like Mailchimp or SendGrid) may apply relaxed header canonicalization by default, but receiving servers enforce strict rules. Mismatched modes cause signature failure.
  • Many email templating engines insert nonstandard whitespace or line folding (e.g., using CR LF where LF is expected). This alters the digest value in the z=tag.
  • When email clients or rendering engines strip or reorder headers during display (e.g., moving Reply-To: to the top), it invalidates the original signing path.

According to RFC 6376, the z= tag is a canonical representation of the signed header section. Any deviation in how that section is normalized between signing and verification will fail. The most common root cause? Inconsistent header handling across the email delivery stack.

“Header canonicalization is one of the most frequently overlooked parts of DKIM implementation.” — RFC 6376 (DKIM)

It’s not just technical—it’s procedural. Even if your DKIM signature is mathematically valid, the wrong canonicalization mode at any stage (sending tool, MTA, forwarder) will result in a z= mismatch.

If you’re auditing your email deliverability, verify that every component in the chain—including templates, relays, and client servers—is treating headers the same way. Tools like MailTester’s Inbox Placement Tester can detect these issues by simulating real-world delivery paths and testing how your DKIM signature holds up through multiple hops.

How to fix inconsistent header canonicalization in DKIM

If your DKIM-signature header shows a z= tag mismatch with header canonicalization, you're likely using inconsistent header processing—some systems apply relaxed-lf, others simple-lf. The fix is to standardize on one canonicalization method across every system involved in sending or forwarding. Ensure all intermediaries (like forwarders or filters) preserve the original DKIM-Signature header exactly. Never sign a message after it's been modified by a system that alters headers. Keep header formatting consistent—use one space after colons and avoid extra line breaks.

Standardize canonicalization method

  • Choose either simple-lf or relaxed-lf and use it everywhere—mail servers, sending platforms, forwarding services.
  • DKIM canonicalization is specified in RFC 6376; always verify implementation matches the standard.
  • If your sending system uses relaxed-lf, ensure the recipient’s mail server processes it the same way—most do, but testing is critical.

Preserve the DKIM-Signature header at every stage

  • Forwarding services and filters should not rewrite, remove, or alter the original DKIM-Signature header.
  • Some services (like Google Workspace forwarding) can break DKIM by modifying headers—verify their behavior with MXToolbox or a header validator.
  • Use tools like MailTester's inbox placement test to validate real-world delivery and signature integrity before sending at scale.
  • Never re-sign a message that’s already been DKIM-signed—this invalidates the original signature and creates a z= mismatch.

Header canonicalization fails when systems differ in how they handle whitespace, line endings, or capitalization. Even a single space added after a colon or a line break in a header can shift the hash value. Consistency is what matters. Tools like MailTester help catch these issues early—test emails before sending with real-time email validation or bulk list verification, especially if you're managing multiple sender environments. The goal isn’t perfection in each message, but predictable, reproducible verification. Let’s be honest: small formatting quirks cause big delivery failures. Fix them at the source—before they reach the inbox.

Why checking DKIM on a real email matters more than theory

DKIM verification errors with a z= tag mismatch due to header canonicalization usually only surface when you test a real, sent email. Simulated tests often skip the nuanced header formatting changes that occur during transit—like line breaks, ordering shifts, or whitespace adjustments—making them unreliable predictors of actual delivery failure. Only by sending and inspecting a live message with intact headers can you catch these issues in real time.

Header canonicalization is invisible in most testing tools

Most DKIM checks, especially in bulk or API-based tools, treat headers as static. But in reality, email headers are subject to transformation during routing—some MTAs normalize line endings, others reorder fields. These differences matter because DKIM’s z= tag includes a canonicalized representation of the headers used to generate the signature digest. Even a single space change or line break shift can invalidate the signature.

This level of detail is lost in synthetic testing. You can pass a DKIM simulation and still fail in production due to subtle header differences that only appear in live email flow. That’s why tools like the MailTester inbox placement tester exist: they send real messages through actual email infrastructure to simulate real-world conditions, including how headers are processed across recipients' systems.

Real-world validation beats theoretical accuracy

Even when your DKIM setup passes in a sandbox, it may break when delivered to Gmail, Outlook, or enterprise mail servers—because no two systems canonicalize headers the same way. The DKIM RFC explicitly defines two canonicalization methods: relaxed and simple. The server used to verify must apply the same rules as the signing server; mismatches here trigger the z= tag error.

Only by testing with live mail can you confirm whether your canonicalization aligns with the recipient’s expectations. You can’t simulate the edge cases seen in production: gateway rewrites, proxy adjustments, or header normalization by security filters. That’s why sending a real email—ideally with known header structure—through tools like MailTester’s inbox placement tests provides results no theory-based check can match.

Let’s be clear: you don’t just need to sign emails correctly. You need to sign them in a way that survives transit unchanged. A real test, with real headers, is the only way to verify that.

How MailTester helps catch DKIM errors like z= mismatches

If your email bounces with a DKIM verification error due to a z= tag mismatch, it’s likely because the canonicalized headers in your message don’t match the list of headers referenced in the z= field. MailTester checks this exact condition by validating the full DKIM signature against real receiver logic, flagging mismatches before you send.

What real receivers check — and why it matters

DKIM validation isn’t just about signature correctness. It uses header and body canonicalization rules defined in RFC 6376. If you don’t apply those rules consistently, even a valid signature fails. This is where MailTester adds real value: it simulates the same validation logic used by Gmail, Outlook, and other major providers.

How MailTester detects z= mismatches

  • It runs full header and body canonicalization using the same rules that real email servers apply.
  • It verifies the DKIM signature against the actual output of that canonicalization process.
  • It checks that every header listed in the z= tag appears in the canonicalized header list — no more, no less.
  • If a header in z= is missing, duplicated, or incorrectly folded, MailTester flags it immediately.
  • You get a clear breakdown: which header caused the mismatch and how it should be fixed.

For example, if your sender includes Received: lines that weren’t present in the original message, or if you use a non-standard field like Precedence: without including it in z=, MailTester will catch it. These are common causes of silent failure.

Let’s say you’re sending through SendGrid, Mailchimp, or HubSpot. MailTester integrates with them via API or batch. That means you can verify your list or test your campaign’s deliverability *before* sending, catching DKIM issues in real time.

Use MailTester’s inbox placement test to see how your email actually lands in inboxes — including whether DKIM is verified across different providers. It’s not just a syntax checker. It’s a real-world test.

For teams that need to validate thousands of addresses at once, MailTester’s bulk verification tool can catch mass DKIM errors across your list before you send. This prevents reputation damage and wasted delivery resources.

DKIM is complex, but you don’t need to guess how it works. MailTester handles the heavy lifting — from canonicalization to header matching — so you don’t have to.

Best practices to prevent DKIM verification errors

DKIM verification errors from a z= tag mismatch usually happen when the header or body canonicalization used during signature verification doesn’t match the one used when signing. To prevent this, always use relaxed-lf canonicalization, ensure header order and content stay unchanged after signing, and verify signatures with tools that parse real messages—not simplified simulators. Test your full email setup end-to-end.

Apply consistent canonicalization

  • Use relaxed-lf for both header and body canonicalization. This is the standard used by most email providers and reduces errors from line-ending or whitespace differences.
  • Never mix canonicalization modes. If you sign with relaxed-lf, verify with the same method. Using simple or different line rules causes z= tag mismatches.
  • Refer to RFC 6376, section 3.4 for how canonicalization works in practice: DKIM canonicalization rules.

Preserve message integrity post-signing

  • Once DKIM is signed, do not rewrite, reorder, or alter headers. Even small changes—like appending a tracking parameter to the From or To field—break the signature.
  • Use consistent message rendering pipelines. If your email service rewrites headers (e.g., for routing or tagging), do it before signing, or risk verification failure.
  • Validate DKIM signatures with tools that parse full raw messages, not just simplified test inputs. Many simulators skip real-world quirks like folded headers or encoded fields.
  • Use inbox placement testing with actual email clients—this reveals how your full message is processed, including DKIM validation, before you send to real users.
A single header reordering after signing can render a valid DKIM signature unusable, even if the private key and domain are correct.

Let’s be clear: testing your email address alone isn’t enough. You need to verify the full message, including headers, body, and the signing chain. That’s why tools like MailTester, which parse real messages using live parsing engines, are essential for catching mismatches before they impact sender reputation.

Conclusion: fixing DKIM requires real-world validation

A z= tag mismatch isn’t a standalone failure — it’s a signal that header canonicalization differs between the signing and verification stages.

Only by inspecting the full email as it travels through the network can you identify where and why the header handling diverges during transit.

Email verification tools that only check syntax or basic reachability won’t catch these errors. You need real-world email testing to validate how headers are processed across different providers and routes.

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 z= tag mean in a DKIM signature?

The z= tag lists the header fields included in the DKIM signature’s canonicalized digest. A mismatch means the receiver saw different headers than the sender signed.

Why does DKIM fail even when the key is correct?

DKIM checks the content digest, not just the key. If headers are canonicalized differently during signing vs. verification, the digest won’t match.

Can a single space cause a DKIM failure?

Yes — even one extra or missing space in a header field can change the canonicalized output and invalidate the signature.

Do email clients affect DKIM verification?

Directly, no — but clients that forward or modify messages can break DKIM if the original signature is preserved but headers are altered.

Is relaxed-lf better than simple-lf for DKIM?

Relaxed-lf is more forgiving and commonly used in practice. It standardizes whitespace and line folding, reducing mismatch risks.

How can I test DKIM signatures before sending?

Use tools like MailTester that validate the full email, including headers and body, using real-world receiver rules.

Are all DKIM errors caused by header issues?

No — other causes include expired keys, incorrect selector or domain, or misconfigured DNS records. But header canonicalization is a frequent culprit.

Does MailTester check DKIM with header canonicalization?

Yes — MailTester processes full email headers and body with real canonicalization rules, identifying z= mismatches and other signing flaws.

Can forwarders break DKIM signatures?

Yes — if a forwarder modifies headers without re-signing, the original DKIM check fails, often due to canonicalization mismatches.

What’s the role of header canonicalization in email authentication?

It ensures consistent interpretation of headers across systems, which is essential for DKIM and DMARC to function correctly.

How does MailTester’s accuracy impact DKIM testing?

With 98.9% accuracy, MailTester reliably identifies real DKIM issues, including z= tag mismatches, without false positives or missing edge cases.

Do I need to test every email for DKIM?

No — but testing a representative sample of sent emails, especially high-volume campaigns, catches configuration issues before they harm deliverability.