What causes a DKIM signature failure when the z= tag doesn’t match canonicalization?

You sent an email that looks correct on your end—headers in place, signature generated, everything checks out. Yet it fails DKIM verification. The error? “z= tag does not match canonicalization.” You’re not broken. The system is. And the root of the issue often lies in how headers are processed between signing and receiving.

DKIM relies on strict alignment: the headers used during signing must match exactly what the receiver canonicalizes. The z= tag lists which headers were signed. If the receiver’s canonicalization alters their order, formatting, or whitespace, the z= list no longer matches—resulting in a failure, even if the signing key and domain are correct.

Key takeaways

  • The z= tag must reflect the exact set of headers canonicalized by the receiver; any mismatch causes DKIM failure.
  • Relaxed canonicalization changes line endings and whitespace, which can break alignment if the signing process assumes simple canonicalization.
  • Headers with non-standard formatting, missing newlines, or embedded tabs are common culprits in z= mismatches.

How does DKIM canonicalization actually work?

DKIM canonicalization normalizes email headers and body content before signing, ensuring that minor formatting differences—like line breaks or case—don’t break verification. The signing server applies a rule set to standardize whitespace, header order, and line endings. If the receiving server uses a different canonicalization method, or if the original signing process miscalculates the canonical form, you’ll see a "z= tag does not match canonicalization" failure, even if the signature is mathematically valid.

The relaxed method: designed for real-world email delivery

Most DKIM implementations use relaxed canonicalization by default, which tolerates minor differences in formatting. It normalizes header field names to lowercase and folds line breaks, so variations in how servers break lines or format spaces don’t invalidate the signature. This makes DKIM resilient to common email relay and transport changes. If your email passes through multiple MTA hop points, like those in shared hosting or managed services, relaxed canonicalization is the only practical choice.

Let’s say you're sending through a third-party platform that slightly rewrites line breaks in the body or modifies header spacing. With relaxed canonicalization, the recipient’s server will still accept the signature—it knows those changes are normal during transit. If you instead used simple canonicalization, even a single extra space would cause a failure, because it treats every byte difference as invalid. This is why simple canonicalization is rarely seen in live environments.

Simple canonicalization: precise but fragile

Simple canonicalization applies no normalization. It uses the exact bytes from the original email, including original line endings, mixed case, and header order. While it offers maximum strictness, it fails easily under normal email delivery conditions. A single server rewriting line breaks or adding a trailing space can invalidate the signature, even if the content is unchanged.

Because of this fragility, simple canonicalization is mostly used in testing environments or for verifying internal system behavior. It’s not practical for production use. The vast majority of email providers—including Gmail, Outlook, and Yahoo—expect relaxed canonicalization. Using simple in a real-world setup will lead to consistent failures, even when the signing key and algorithm are correct.

Understanding this is critical when troubleshooting DKIM. A signature might be correct in isolation, but if the sender and receiver apply different canonicalization rules, the validation will fail. Tools like MailTester’s email checker can help you verify whether a recipient's email policy enforces stricter validation or if the issue lies in how your email was processed before signing.

Drafting and sending emails at scale? Make sure your email service provider or email marketing platform handles DKIM canonicalization consistently. For deeper verification, use inbox placement testing to confirm that your emails reach inboxes—where DKIM alignment matters most.

Why does the z= tag exist and how is it used in DKIM validation?

The z= tag in a DKIM signature lists the exact header field names that were included in the signature's canonicalized body. This lets receiving mail servers know which headers to expect during validation. If the receiver’s canonicalization process alters a header (like folding line breaks or normalizing case) but the z= list doesn’t reflect that change, the signature fails because the expected headers don’t match the actual ones. This is a key reason why DKIM fails even when the key is correct.

How the z= tag ensures header alignment

When a sender signs an email, they choose which headers to include in the signature. The z= tag records those exact field names, preserving the sender’s intent. Receiving servers recompute the signed header list using the same canonicalization method (usually simple or relaxed). If the canonicalization strips extra whitespace, folds long lines, or normalizes capitalization, the z= list must match these changes. A mismatch here — for example, if the sender included "Subject:" but the receiver sees "subject:" after normalization — triggers a validation failure.

Let’s say you send an email with a header field named "X-Message-ID". If your domain uses relaxed canonicalization, that field might show up as "x-message-id" in the final message body. If your z= list still references "X-Message-ID", the verifier will reject the signature. The z= tag isn't just metadata — it’s a contract between sender and receiver on what should be there.

According to RFC 6376, which defines DKIM, the z= tag is essential for header integrity in signature verification. It helps prevent spoofing by ensuring only headers that were actually signed are trusted. This also protects against tampering: if an attacker modifies a header but doesn’t update the z= list, validation will fail.

Many email verification tools, including MailTester’s email checker, test for DKIM signature integrity in real-time. If you're seeing z= issues in your delivery logs, it’s a sign that your email infrastructure or signing process isn’t handling canonicalization consistently. Tools like our API can help catch these problems before you send to large lists.

How to debug a z= mismatch during DKIM verification?

When a DKIM signature fails due to a z= tag mismatch, the headers in the signature don’t match what the receiver canonicalized. You’ll need to inspect the raw email headers, compare the original signed headers against the receiver’s canonicalized version, and ensure your signing tool uses relaxed canonicalization and only lists headers that were actually signed. Use tools like MxToolbox or MailTester’s inbox placement test to examine the full header chain and spot discrepancies.

Step-by-step debugging checklist

  • Fetch the raw email headers from the receiving server—use a tool like MxToolbox’s Diagnostic Tool or a mail server log to get the full message including all headers.
  • Locate the DKIM-Signature header and note the z= tag—it should list the canonicalized header names in the order they were signed.
  • Apply the same relaxed canonicalization (as specified in RFC 6376) to your original headers and compare the resulting header list to the z= value.
  • Check your DKIM signing tool’s configuration. Ensure it’s using relaxed header canonicalization (not simple) and that the z= tag includes only the headers actually signed—no extras.
  • Verify that no header was altered (e.g., by a relay or mailing list) between signing and delivery. Even small changes, like a newline or extra space, can break canonicalization.
  • Use MailTester’s inbox placement test to simulate delivery, inspect the full header chain, and see where canonicalization diverges from what was signed.
  • If you’re using a custom signing process, validate the z= tag output against the canonicalization standard using a known test vector or tool.

Common root causes

  • Using simple canonicalization instead of relaxed when relaxed is required.
  • Signing headers that weren’t actually included in the message body (e.g., a trailing space or missing header).
  • Misconfigured mail server appending or modifying headers before delivery, especially by forwarders or BCC processors.
  • Incorrect z= tag value—manually editing it in a script or rule is a surefire way to break validation.
Even a single missing or altered header can invalidate a DKIM signature, especially if the z= tag doesn’t match the receiver's canonicalized view.

What happens when the z= tag and canonicalization differ?

If the z= tag in a DKIM signature does not match the canonicalized content of the email — particularly the body — the receiving server will reject the signature as invalid, even if the rest of the message is technically correct. This failure breaks the digital verification chain, often causing the message to be marked as spam or outright rejected by providers like Gmail or Outlook. The issue may appear as a mysterious delivery failure with no clear sender-side explanation, commonly misattributed to sender reputation.

How the mismatch disrupts delivery

DKIM relies on exact matching between the z= tag — which is a hash of the body content — and the canonicalized version of that content as processed by the receiving server. If the body has been altered during transit (e.g. via email service rewriting HTML or adding tracking pixels), or if the canonicalization method (relaxed or simple) isn't consistently applied, the hash won’t match. The server rejects the signature, and while the email might still be delivered in rare cases, it lacks cryptographic validation.

Major email providers apply strict DKIM checks. A failed signature can trigger filtering policies, leading to messages landing in spam folders or being blocked entirely. Unlike spam-triggered rejections, these failures aren’t usually logged with a clear message to the sender. This makes troubleshooting difficult — especially if the issue is rooted in how a third-party sender or ESP handles body normalization.

Why it's often misdiagnosed

Because DKIM failures don’t always result in immediate bounce messages, senders often assume the problem lies in reputation, sending volume, or content. The absence of clear error codes makes it hard to pinpoint the issue, especially if you're not auditing DKIM signatures at scale. The real root — a mismatch between the computed z= hash and the expected canonicalized body — gets overlooked.

Tools like MailTester’s email checker let you validate individual addresses and diagnose delivery readiness, including checking the integrity of email headers and body structure. This helps catch misconfigured DKIM signatures before they impact delivery. For teams sending at scale, bulk verification and inbox placement testing via MailTester’s inbox tester can surface hidden issues like incorrect canonicalization early in your workflow.

For deeper insight, the DKIM specification defines how the z= tag should be used and how body canonicalization works. Ensuring consistent implementation across your email stack is essential to avoid silent delivery failures.

How to prevent z= tag mismatches in your DKIM setup

DKIM signature failures due to z= tag mismatches happen when the list of headers in the signature doesn’t match what the receiving server expects after canonicalization. To prevent this, use relaxed canonicalization for headers, ensure your signing tool includes only actual header names in the z= tag, avoid post-signing header changes, and validate every change with real delivery testing. This alignment is non-negotiable for deliverability.

Canonicalization: start with relaxed for headers

  • Use relaxed canonicalization for headers unless you have a specific, documented reason to use simple.
  • Relaxed canonicalization strips whitespace and normalizes line breaks, which matches how receivers process headers.
  • Forcing simple often causes z= mismatches, especially when headers are reformatted in transit.

Header list precision: every name counts

  • Only include headers that exist in the actual email when generating the z= tag.
  • Do not add extra headers like X-Original-To or Return-Path unless they’re part of the original message.
  • Omitting a real header or adding a non-existent one breaks validation.
  • Many DKIM tools allow custom header lists — make sure they reflect the real message, not assumptions.

Changing any header—adding, removing, or reordering—after signing will invalidate the DKIM signature. Even a BCC insertion can trigger a mismatch if the z= tag isn’t updated. Always sign the final version of the message.

Test every change with tools that simulate real-world delivery. Use real inbox placement testers to verify if your DKIM signatures pass in practice. Don’t rely solely on debug tools or in-house validators—receiver behavior varies. The only true test is actual delivery to major providers.

For example, RFC 6376 (the DKIM standard) defines the z= tag as a list of header names used in the signature. Mismatches often occur because of subtle differences between sender-side signing and receiver-side parsing.

“The z= tag must reflect exactly which headers were used in the signature computation.” — RFC 6376, Section 6.1

Keep your signing process deterministic. Use the same tool and process for every send. If you’re managing high-volume or complex email flows, consider using MailTester’s verification API to catch deliverability risks early—especially when validating sender infrastructure integrity.

Can you simulate a DKIM z= mismatch for testing purposes?

Yes, you can simulate a DKIM z= mismatch by sending a test message with intentionally altered z= tags or improperly formatted headers to see how receiving systems respond. This helps validate how your email infrastructure handles canonicalization errors, especially during migration or configuration changes. Use real-world inbox placement testing to observe outcomes across Gmail, Outlook, and Yahoo.

How to safely test DKIM z= mismatches

Send a message where the z= tag in the DKIM-Signature header references a different set of canonicalized headers than what the receiver computes. For example, intentionally add or remove whitespace in a header field to create a drift. You won’t trigger a bounce, but you’ll see if the receiver drops the signature check or treats it as a soft fail.

Since DKIM canonicalization is defined in RFC 6376 (specifically Section 3.3), you can verify your implementation against the standard. Receiving servers like Gmail and Yahoo perform strict alignment checks—deviating from canonicalization rules may result in signature rejection, even if the key is valid.

Use inbox placement testing to observe real behavior

Tools like MailTester’s inbox placement testing let you send messages designed to trigger known issues—like a z= mismatch—while tracking how receivers interpret the DKIM signature in full headers. You'll see whether the result is a hard failure, soft fail, or silent rejection.

Monitor the full header output provided in the test results. Look for differences between the expected and actual canonicalized header set. Even small changes—like extra CR/LF or altered whitespace—can cause drift. This visibility helps you debug configuration drift in your email workflow or between systems, especially when using third-party services.

DKIM failures due to z= mismatch are common during MTA handoffs or when using content-transforming gateways. Testing these edge cases with real inbox scenarios ensures your messages aren’t silently dropped due to alignment issues. If you’re unsure, test your email’s deliverability and DKIM validation status across major providers before mass sending.

How does MailTester help diagnose DKIM z= tag failures?

You can diagnose DKIM signature failures caused by a mismatched z= tag by analyzing the canonicalization of email headers and bodies during verification. MailTester’s real-time API and inbox placement tests parse raw headers, showing exactly how the z= tag was computed versus how it was verified, pinpointing where the alignment breaks—whether in header or body canonicalization. This lets you fix configuration errors before your messages are rejected.

Real-time verification with DKIM header parsing

When you use the MailTester verification API, it doesn’t just check if an email exists—it checks the full email envelope and header structure. This includes validating the z= tag against the canonicalized version of the message body and headers. If the computed hash doesn’t match the one in the DKIM signature, it flags a z= tag mismatch. You get immediate feedback on whether the issue lies in how the body was stripped, what whitespace was preserved, or if a header was misprocessed during signing.

Inbox placement testing reveals canonicalization logs

Inbox placement tests go further by simulating delivery to providers like Gmail, Outlook, and Yahoo, then returning the full header chain used during delivery evaluation. These logs show how each provider canonicalized the message, including the specific parts of the header and body that were included in the z= hash. You can compare this to your own signing process to see if your DMARC policy, SPF/DKIM alignment, or body canonicalization is off.

For example, if your mail server uses relaxed header canonicalization but your DKIM signing tool uses simple body canonicalization, the z= tag will fail—MailTester surfaces this gap explicitly. You can see exactly which lines or characters were stripped, altered, or left in, so you can adjust your signing setup accordingly.

When you’re not sure what’s going wrong, MailTester’s in-app AI assistant lets you paste raw headers and asks it to explain the failure. It will walk through the canonicalization steps, show how the z= tag was generated, and tell you whether the issue is in the body or header processing. This reduces the guesswork and speeds up debugging.

DKIM canonicalization is defined in RFC 6376. While the specification doesn’t enforce a single standard, it outlines the two types—simple and relaxed—that affect how spaces, line breaks, and header formatting are handled. You can learn more about the standard at the IETF’s specification.

What’s the real-world impact of a DKIM z= mismatch?

A DKIM z= tag mismatch means your email’s canonicalized body doesn’t match the signature’s expected digest. Even one failure can reduce trust signals to email receivers, increasing the chance your message lands in spam. When failure rates climb across a domain, sender reputation tools may flag your sending behavior, leading to filtering or blacklisting. Automated systems relying on email—like password resets or billing alerts—can fail entirely if DKIM verification breaks.

Why one failure matters more than you think

Most email receivers don’t just reject messages outright from a failed DKIM check—they treat it as a red flag. The absence of a trusted signature means the receiver has no proof the email wasn’t altered in transit. This alone can reduce inbox placement scores. According to RFC 6376, DKIM validation is meant to provide origin authentication and integrity. A mismatch in the z= tag breaks that promise, even if the rest of the header and body appear correct.

When DKIM fails at scale, reputation suffers

If DKIM verification fails across dozens or hundreds of messages from the same domain, it signals inconsistency. Email providers use reputation systems that track failure rates, pattern anomalies, and signing errors. A high rate of z= mismatches raises a red flag that your infrastructure may be misconfigured—or worse, compromised. The result? Your domain could face rate limiting, filtering, or even blacklisting on major platforms.

For transactional senders—think password resets or order confirmations—this is a serious operational risk. These messages are time-sensitive, expected, and often automated. If a DKIM failure prevents delivery, users can’t regain access or complete orders. In some cases, these systems may retry and eventually succeed, but they often miss critical timing windows.

That’s why proactive verification matters. You can test your DKIM setup during delivery using inbox placement tools. MailTester’s inbox tester simulates real-world delivery across major inboxes and checks both DKIM and SPF alignment, so you know whether your messages are being trusted before they leave your system.

Even if your messages pass all other checks, a z= mismatch means the signature is invalid. It’s not a minor quirk—it’s a failure of integrity. The same goes for automated email workflows: no exception, no pass-through. A single invalid signature can break an entire delivery pipeline. Regular checks using trusted tools help prevent this before it impacts real users.

DKIM failure: common causes beyond the z= tag

DKIM signature failures aren't just about the z= tag mismatch. You might be using the wrong selector, placing the public key in the wrong DNS record, or having headers altered after signing. Misconfigured DNS, outdated signing tools, or email gateways rewriting headers can also break DKIM validation—even if your domain and selector are correct. The key is systematic checking.

Common technical misconfigurations

  • You're using the wrong DKIM selector. Double-check your signing configuration against the DNS record’s selector part (e.g., default in default._domainkey.example.com).
  • The public key isn’t published in DNS or is misaligned. A missing or incorrect DKIM TXT record breaks key lookup. Use MXToolbox’s DKIM checker to validate the record structure.
  • Your domain in the DKIM header doesn’t match the one in DNS. A mismatch between the d= tag and the actual signing domain breaks validation—common in forwarding or mailing list setups.

Post-signing modifications and tooling issues

  • SMTP relays or gateways alter case, add, or delete headers after signing. DKIM is sensitive to even small changes; RFC 6376 specifies canonicalization rules that must be preserved.
  • Old or non-compliant signing tools don’t follow RFC 6376. Some tools misapply header or body canonicalization, leading to signature mismatches even if the z= tag appears correct.
  • Invalid DNS records—like malformed TXT entries, extra quotes, or excessively long values—can prevent proper key retrieval. DNS standards require exact formatting; even one extra space breaks resolution.
Even a single altered header can invalidate a DKIM signature—no exceptions.

When testing, verify your setup end-to-end: check DNS records, validate the signing tool, and test a delivered email against the original signed version. Tools like MailTester’s inbox placement tester help reveal whether your email lands in the inbox—or gets flagged due to broken authentication.

Fixing DKIM z= mismatches: a full verification workflow

DKIM signature failures due to z= tag mismatches stem from inconsistent header canonicalization during signing and verification. Even minor differences in line breaks, whitespace, or header order can break alignment.

Use MailTester’s bulk verification API to identify emails in your list that may trigger authentication issues. Then, send a test message through your transactional system and extract the full received headers for inspection.

Paste those headers into MailTester’s inbox placement test. The tool will analyze canonicalization and highlight mismatches in the z= tag and header normalization. Adjust your signing process to match relaxed canonicalization, ensure consistent header order and formatting, and re-test to verify the fix.

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 do in a DKIM signature?

The z= tag lists the header field names included in the DKIM signature. The receiver checks this list against the canonicalized headers to verify consistency.

Can a DKIM failure happen even if the signature looks correct?

Yes — if the z= tag lists headers that were not in the canonicalized version due to formatting changes, the signature fails even if the cryptographic signature is valid.

Is relaxed canonicalization always better than simple?

Yes — relaxed canonicalization accounts for common formatting changes during transit and is the standard choice in production environments.

How can I check if my DKIM setup is broken?

Use MailTester’s inbox placement test to send a message and review the DKIM validation report, including header alignment and z= tag matching.

Does MailTester support testing DKIM signatures?

Yes — MailTester’s inbox placement test includes full DKIM signature analysis, including z= tag and canonicalization checks.

Why does my email pass local validation but fail in production?

Local tools may not apply the same canonicalization as major providers. Real-world delivery testing is needed to catch z= tag mismatches.

Can a single malformed header break DKIM?

Yes — a single incorrect line break, missing CRLF, or incorrect capitalization can change the canonicalized header and break the z= tag alignment.

Do all email providers enforce z= tag matching?

Yes — major providers like Gmail and Outlook require strict alignment between z= tags and the canonicalized headers to validate DKIM.

How often should I test DKIM configurations?

Test every change to signing tools, headers, or DNS records. Use MailTester’s real-time API or inbox tests for ongoing validation.

What’s the difference between DKIM and SPF?

SPF validates the sending IP; DKIM validates the integrity of the message content and headers. Both are required for strong email authentication.