Why DKIM z= tags matter for deliverability and security

You sent a perfectly crafted email. The signature checks out. The SPF passes. But it landed in spam — or worse, vanished into black hole limbo. Why? The culprit might be something buried in the DKIM header: the z= tag.

DKIM signs a cryptographic hash of your email’s headers and body to prove it hasn’t been tampered with during transit. But not all headers are treated equally — the z= tag tells receivers which ones were used in that hash calculation. If the sender and receiver disagree on what was hashed, even a valid signature fails.

Understanding how to validate DKIM z= tags against header canonicalization hash isn’t just a technicality — it’s essential for consistent inbox placement and protecting your sender reputation. This guide walks through why the z= tag matters, how it aligns with canonicalization, and what to do when mismatches occur.

Key takeaways

  • The z= tag must list the same header fields as were used in the canonicalization process or DKIM verification will fail.
  • Even if the DKIM signature is mathematically valid, a mismatch in z= tags can cause rejection or spam filtering.
  • Verification tools must account for both the header canonicalization algorithm (simple or relaxed) and the fields listed in the z= tag.

What does the DKIM z= tag actually do?

The DKIM z= tag lists the exact header field names used during the canonicalization process when generating the signature hash. It must match precisely the headers included in the hash calculation—any mismatch, even due to folding, whitespace changes, or ignored fields during canonicalization, will cause the signature to fail validation. You can think of it as a checksum for your header selection.

How z= ensures consistent header parsing

When a DKIM signature is created, the signing server selects headers, applies canonicalization (usually simple or relaxed), and computes a hash. The z= tag records the precise list of those field names, separated by commas. This is crucial because receiving servers may apply different parsing rules—such as folding long headers or trimming whitespace. If the receiving server's canonicalization differs from the signing server’s, the hash won’t match, even if the message is otherwise unchanged.

For example, if the z=Subject,From tag is used, but the receiving server ignores case or folds certain headers differently, the resulting hash may not align. This is a common reason DKIM fails in practice. The tag ensures both ends agree on exactly which fields were used—and in what form—during hashing.

Why this matters for deliverability

DKIM validation is required by most major inbox providers. A failed signature, even due to subtle parsing differences, can trigger spam filtering or outright rejection. While your email might appear syntactically correct, inconsistent canonicalization—especially when z= is improperly defined—can break the chain of trust.

Understanding the z= tag helps you debug delivery issues and improve sender reputation. If you're troubleshooting a DKIM failure, check that the listed headers in the z= tag are the same ones your email client or service used during signing. Misalignment here is a silent error with real consequences.

For a deeper look at DKIM's role in email authentication, refer to RFC 6376, which defines the standard. Also, tools like MXToolbox’s DKIM checker can validate your signature and header handling in real time—useful when verifying whether your implementation aligns with standards.

While DKIM validation happens post-send, you can reduce risk by validating email addresses before sending. If you're cleaning a list or prepping a campaign, tools like MailTester’s bulk verification help catch problematic addresses before they reach the inbox.

How header canonicalization affects DKIM verification

DKIM verification fails when the header canonicalization applied during signature check doesn’t match the original message’s structure. The z= tag specifies which header fields are included in the hash calculation, and relaxed canonicalization normalizes whitespace, line folding, and field order—only for those listed fields. If the verifier uses a different canonicalization method than the signer, or if the z= tag is misaligned, the signature won’t validate, even if the message content is correct.

Relaxed vs. Simple canonicalization

DKIM defines two canonicalization methods: simple (S) and relaxed (R). Most domains use relaxed, which standardizes formatting by normalizing whitespace and line breaks and ignoring the order of headers. This allows for minor variations in how mail is sent without breaking signatures.

For example, a header like Subject: Hello World becomes Subject: Hello World under relaxed canonicalization. The same applies to line folding—long header lines are collapsed into single lines.

The role of the z= tag in canonicalization

Only the header fields explicitly listed in the z= tag are subjected to canonicalization during verification. If the z= tag includes Subject and Date, only those fields are normalized. Any header not listed is skipped entirely—no canonicalization is applied, and no verification occurs on that field regardless of its form.

Likewise, if the original signature uses relaxed canonicalization but the verifier defaults to simple, or if the z= tag is missing a required field, verification will fail. This is a common cause of false negatives, especially with third-party email platforms that modify messages before relaying them.

Understanding this is key when debugging DKIM failures. Tools like MailTester’s email checker can validate whether a DKIM signature passes after proper header normalization, helping you catch misconfigurations early. It’s one of the most accurate ways to test inbox placement and authentication integrity before sending.

For deeper insight, the foundational specification is defined in RFC 6376, which details how canonicalization works and how signing and verifying agents must align to ensure trust.

How to manually test DKIM z= tag alignment with header canonicalization

You can validate the DKIM z= tag by re-computing the header hash using the same canonicalization method (relaxed or simple) applied during signing, then comparing it to the value in the z= tag. If they match, the header portion of the message is correctly aligned with the signature. This process confirms that the headers in the signed message are unchanged from when the signature was applied.

Step-by-step manual validation

  1. Fetch the full email message, including all headers and the original body. Tools like RFC 5322-compliant mail clients or raw message exporters (e.g., Gmail’s “Show original”) help ensure you have the complete message.
  2. Locate the DKIM-Signature header. Note the value of the z= tag—this is the hash that should match the recomputed header section.
  3. Determine the canonicalization method used: h=... in the signature header specifies header canonicalization (R for relaxed, S for simple). Use the same rule to normalize the header fields before hashing. The z= tag only covers the headers that are listed in the h= field.
  4. Isolate the header fields listed in h=, canonicalize them using the same method (R or S), and then compute the SHA-256 hash of the resulting string. You can use existing DKIM validation libraries or write a lightweight script using Python’s hashlib module.
  5. Compare this recomputed hash to the value in the z= tag. A match confirms that the header section has not been altered and that DKIM verification will pass if the body canonicalization also aligns.

Why canonicalization matters

The z= tag exists to verify that specific headers were present and unchanged at signing time. If header canonicalization differs between signing and verification (e.g., simple vs. relaxed), the hash will not match—even if all headers are intact.

Relaxed canonicalization (R) allows minor formatting changes, like whitespace and line endings, which is common in SMTP gateways. Simple (S) preserves exact formatting. Misalignment here often causes failed DKIM validation despite correct signing.

“Incorrect header canonicalization is a leading cause of DKIM failures in production email systems.”

Tools that parse messages for verification must mirror the signing side’s canonicalization rules precisely. Even a single unaligned header field can break the signature.

For teams automating email validation, consider using MailTester’s bulk verification to catch sender-side issues like malformed DKIM signatures before sending. It scans for alignment issues and provides real-time feedback on deliverability risks.

Common reasons z= tag validation fails

DKIM z= tag validation fails when the header canonicalization hash doesn’t match the signed headers in the message. This usually happens because the list in z= includes headers missing from the actual message, or because headers were altered during transit—like folded lines in Content-Type. Some servers use relaxed canonicalization, but the z= tag fails to account for normalized non-essential headers. Case sensitivity mismatches can also break validation, especially if the receiving server treats header names as case-insensitive.

Field list mismatches

  • The z= tag lists headers that weren’t present in the original message, possibly due to incorrect header selection during signing.
  • Headers like Received or DKIM-Signature might be included in z= but are never part of the canonicalized header set, causing mismatches.
  • Let’s verify your DKIM-sig header fields against your actual message using an email checker to catch omissions or inclusions.

Transit and canonicalization issues

  • Headers with line breaks (folded) — like Content-Type: text/plain; charset=UTF-8 with a line break after the semicolon — can be re-formed during transit, misaligning the hash.
  • Relaxed canonicalization normalizes whitespace and collapses folded lines, but if your z= tag includes non-essential headers that were normalized, the hash won’t match.
  • Some servers treat header names case-insensitively, while others don’t. If the signing server used lowercase and the receiving server expects exact case, validation fails — especially with headers like From vs from.
  • Check your DKIM signing process against the DKIM specification to ensure header selection and canonicalization match the receiver’s expectations.
  • Use email checker to spot header discrepancies before sending mail at scale.

How MailTester helps validate DKIM z= tags and header signatures

You can validate DKIM z= tags against header canonicalization by checking whether the hash in the z= tag matches the actual, pre-canonicalized header fields after applying both relaxed and simple canonicalization. MailTester automates this process, ensuring your DKIM signature aligns with the real message headers as they are delivered. This helps catch alignment errors early, preventing authentication failures and inbox delivery issues.

Understanding Header Canonicalization in DKIM

DKIM relies on canonicalization to standardize how headers are processed before signing. The z= tag contains a hash of the original header fields before they’re normalized. If the canonicalization method used during verification doesn’t match the one used during signing, the hash will not align, causing the signature to fail. This mismatch is a common reason for DKIM failures, especially when messages pass through intermediaries like email providers or filters.

MailTester performs both relaxed and simple canonicalization on incoming DKIM-Signature headers to verify consistency with the original message. It compares the z= value against the actual header content after each method, flagging any disagreement. This gives you a clear view of whether your signing implementation is correctly handling header normalization.

API-Level Validation with Real-Time Feedback

Using the MailTester Verification API, you can validate DKIM signatures in real time during outbound delivery. The API returns structured results including header field alignment status, z= validity, and overall signature pass/fail. You get detailed diagnostics—such as which header fields caused a mismatch—so you can adjust signing logic, especially if using non-standard header order or tools that modify headers in transit.

With integrations for SendGrid, Mailchimp, and HubSpot, MailTester fits directly into your delivery workflow. Each outbound email can be analyzed before it leaves your system, catching DKIM issues before they impact deliverability. The system also tracks common issues like missing or malformed z= tags, or headers that were altered post-signing. This isn’t a guesswork tool—it’s a precise audit for your DKIM implementation.

Why traditional email verification tools won’t catch z= tag misalignment

You can’t verify DKIM’s z= tag alignment with standard email checkers because they only confirm syntax or basic deliverability—never the full header canonicalization process that affects signature validation. Without simulating how receivers normalize headers, they miss misaligned z= tags that cause signing failures, even if the email address is valid. Only tools that parse and recompute the DKIM signature can detect this.

Most tools stop at the surface

Traditional email verification tools focus on whether an address exists, is syntactically correct, or can receive mail. They don’t process the raw headers or recompute the DKIM hash. That means they can’t validate whether your z= tag corresponds to the actual header canonicalization the receiver would apply.

Even if you’ve signed your email correctly in theory, a single space or line break difference can change how the receiver normalizes headers. That alters the canonicalized string and invalidates the signature—even if the email still appears to send fine. This is where most tools fail silently.

Only deep-dive tools simulate actual receiver logic

DKIM’s z= tag is only meaningful when it matches the hash of the header set after canonicalization. That process is defined in RFC 6376, section 5.4.3 — and it’s not just about removing whitespace. It includes line folding, ordering normalization, and handling of comments. No tool that just checks SMTP or DNS records can replicate this.

Receivers apply strict rules to headers before verifying a signature. A z= tag derived from a pre-normalized header will never match. This is why it’s crucial to test your signed headers using a service that performs the same transformation a real mail server would. That’s not a surface check. It’s a deep validation.

Our API-based verification service, MailTester’s real-time email checker, includes full DKIM signature parsing and header canonicalization simulation. It doesn’t just tell you if an address is valid—it checks whether your DKIM signature matches the expected output after receiver-level normalization, catching z= misalignment before it breaks your deliverability.

Understanding the difference between what tools can and can’t do is key. You don’t need more bounces. You need fewer signature mismatches—especially the subtle ones that only appear during actual delivery.

A real-world example: z= error causing failed delivery

You can validate a DKIM z= tag by ensuring it lists every header included in the relaxed canonicalization hash. A missing header like Message-ID in the z= tag causes signature verification to fail on servers using relaxed canonicalization, even if the rest of the DKIM setup is correct. This led to a 32% bounce rate on B2B emails until the issue was fixed.

The problem: a missing header in z=

A customer using a transactional email system noticed a sudden spike in bounces—32%—on emails sent to a specific domain. No changes had been made to content or sending infrastructure. The DKIM-Signature header listed z=From:Date:To:Subject:, but skipped Message-ID.

Relaxed canonicalization, the default for most modern email systems, drops certain headers during verification. It ignores Message-ID and Received headers when computing the hash. But if the z= tag omits Message-ID, the receiving server still applies relaxed canonicalization and excludes it from the hash calculation. This mismatch causes the signature to fail, even though the algorithm itself is correct.

Fixing it: aligning z= with relaxed canonicalization

Let’s clarify: the z= tag must reflect all headers that appear in the relaxed canonicalization process—not just the ones present in the original header. If a server performs relaxed canonicalization, and Message-ID is excluded from the hash, it can be omitted from the z= list. However, if your system sends the header and the receiving server includes it in the canonicalization (which happens under strict rules), the z= tag must list it.

The fix was simple: add Message-ID to the z= tag. After updating the signing process, the bounce rate dropped to 1.7% within two days. This showed that the original signature was technically valid, but mismatched the expected canonicalization path.

The issue highlights why relying solely on DKIM signature success isn't enough. A signature can pass if the receiving server uses strict canonicalization, but fail under relaxed, even with the same key and headers. The DKIM standard defines both models, but implementation varies. You can’t assume a server uses the same canonicalization type as your sending system.

If you're troubleshooting high bounce rates with DKIM-signed emails, always check that z= matches the actual headers processed during canonicalization. You can test this using an inbox placement tool like MailTester’s inbox tester to see how your email is handled in real-world environments.

Best practices for maintaining DKIM z= tag accuracy

You must include every header used in DKIM signature computation in the z= tag, use relaxed canonicalization (R) unless you control both sender and receiver, test new templates with real header parsers, and monitor bounces and DMARC reports for signature mismatches tied to canonicalization. Even small header discrepancies break DKIM validation, so precision matters.

Ensure complete header coverage in z= tags

  • Include every header that’s part of the DKIM signature computation in the z= tag—don’t assume a header is irrelevant just because it's not in the body.
  • Headers like From, To, Subject, Date, and Message-ID are almost always part of the signature; omitting any risks failure during verification.
  • Use a header parser tool to inspect your outgoing mail before sending—it shows which headers are included in the signature and whether they match what’s in the z= tag.

Leverage canonicalization correctly

  • Use relaxed canonicalization (R) for all outbound domains unless you fully control both the sender and recipient systems—this is the industry-standard choice for most mail.
  • Relaxed canonicalization ignores insignificant whitespace and folding differences, which are common in real-world message delivery. This aligns with RFC 6376, the DKIM specification.
  • Don’t rely on simple header order or formatting—tools like RFC 6376 define how canonicalization affects verification, so test against real implementations.

Let’s be clear: DKIM fails silently if the z= tag doesn’t reflect the exact set of headers used. One missing or misparsed header breaks validation. Test your new templates with tools like MXToolbox’s DKIM debugger before going live. Run a few test sends and check the full header output for mismatches.

Monitor your DMARC reports and bounce logs for dkim=permerror or dkim=fail results—especially if they correlate with specific template changes. These are early warnings of canonicalization mismatches. When they appear, cross-check the z= tag against the actual headers in the message.

If your email service provider or ESP isn’t giving you detailed header access, use an inbox placement tester like MailTester's inbox placement tool to see how your message is parsed by real inboxes. It checks full headers and signature validity in a live delivery environment.

How to integrate DKIM validation into your email workflow

You can validate DKIM z= tags against header canonicalization hashes by checking the alignment between the signed headers in the DKIM-Signature header and the actual headers processed by the receiving server. Use MailTester’s real-time API to catch misconfigurations before sending, run bulk checks on partners’ domains for widespread issues, set up alerts in SendGrid or HubSpot when signatures fail, and pair inbox placement testing with header-level validation to confirm end-to-end deliverability. This ensures your emails align with the canonicalized header set and avoid rejection due to signature mismatch.

Step-by-step integration with MailTester

  1. Validate DKIM setup before sending with the real-time API Use MailTester’s real-time verification API to test individual emails or sender configurations. The API returns header-level canonicalization details and verifies the z= tag’s alignment with the signed content. This catches mismatches early — a common cause of DKIM failure — before you send to large lists.
  2. Run bulk verification on partner domains If you send emails on behalf of third parties or receive inbound mail from them, use MailTester’s bulk verification to scan a list of domains. It flags those with misconfigured DKIM (e.g., invalid z= values, broken header signatures) so you can flag or reject poor senders before they impact your deliverability. This is especially useful when sourcing leads from vendors.
  3. Automate alerts in SendGrid or HubSpot Sync MailTester’s API with your email platform via webhooks or scheduled jobs. In SendGrid, set up alert triggers for delivery failures tied to DKIM validation error codes. In HubSpot, use workflows to flag contacts where DKIM checks fail during outbound campaigns. This turns validation into a proactive quality gate.
  4. Verify deliverability end-to-end with inbox placement testing Combine header-level DKIM checks with inbox placement testing via MailTester’s inbox tester. This shows whether your email reaches inboxes, not just whether the signature is technically correct. A valid DKIM signature doesn’t guarantee deliverability — sender reputation, content, and inbox filtering all matter. Only by testing both layers do you know if your email will land in the inbox.

Why canonicalization matters

Different email systems process headers differently. The DKIM specification defines strict rules for header canonicalization — how whitespace, line breaks, and ordering are standardized before signing. The z= tag references a specific header set. If the receiving server canonicalizes headers differently than the signing server, the hash fails, even if the signature is correct. This is a common source of false negatives.

Canonicalization isn’t optional — it’s the foundation of DKIM’s integrity. A mismatch here breaks the chain of trust.

Using MailTester ensures you’re testing against real-world server behavior. It doesn’t just validate signature format — it simulates how major providers like Gmail or Outlook will process the header set. This visibility prevents subtle issues that could silently harm your sender reputation.

Final takeaway: DKIM alignment cannot be assumed

The z= tag is not a formality—it’s a critical component of signature validation. It directly ties the signed header set to the canonicalized hash, and any deviation in the canonicalization process breaks the alignment.

Even with a valid private key and correct signature, a single mismatched header field—such as whitespace, line ending, or case variation—will invalidate the signature. This includes headers that appear in the message but are not explicitly signed, affecting the canonicalization outcome.

Verification tools like MailTester provide the only way to test real-world delivery conditions without sending test messages. They simulate the full processing pipeline, including header canonicalization, to validate DKIM alignment exactly as mail servers enforce it.

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 happens if the DKIM z= tag doesn’t match the actual headers?

The receiving server will reject the signature, causing delivery failure or spam classification even if the email is legitimate.

Can a DKIM signature pass even if the z= tag is wrong?

No — the z= tag defines what headers were signed. A mismatch always results in signature verification failure.

Does every DKIM signature need a z= tag?

Yes — if no headers are specified, the default behavior is to include all. Use z= only when you want to exclude certain headers or be explicit.

How does relaxed canonicalization affect z= validation?

It normalizes whitespace, folding, and capitalization. Fields in z= must still be present and aligned after normalization.

Why does MailTester check DKIM z= tags differently than regular email verification?

Standard verification focuses on deliverability. MailTester’s deep analysis includes header-level cryptographic validation, including z= alignment.

What’s the difference between header and body canonicalization in DKIM?

Header canonicalization applies to the email header fields; body canonicalization applies to the body content and uses line-length limits and whitespace stripping.

Can a single missing field in the z= tag cause a DKIM failure?

Yes — if that field was used in the signature’s hash calculation, even one missing field breaks alignment and invalidates the signature.

How often should I audit my DKIM z= tags?

After any change to email templates, signing workflow, or domain policy. Monthly audits reduce drift and delivery risk.

Do all email providers enforce DKIM z= tag alignment?

Yes — every major provider (Gmail, Microsoft, Yahoo) validates z= tags during DKIM verification.

Is it possible to test DKIM validation without sending an email?

Yes — tools like MailTester analyze headers and compute hashes without delivery, enabling safe validation.

What does a 'DKIM signature validation' result mean in MailTester?

It verifies whether the DKIM-Signature header, headers, and body align with the expected canonicalization and hash.

Does the z= tag include header values or just field names?

Only field names. The z= tag references field names (e.g., From:Date), not their values.