What Causes DKIM h= Tag Uncanonicalized Header List Errors in Amazon SES?

You sent an email through Amazon SES. It passed SPF. It passed DKIM—except the validation failed because of a single, hidden mismatch in the header list. Why does a seemingly small discrepancy in the h= tag cause a full DKIM failure? DKIM signing requires perfect alignment between the headers listed in the h= tag and the actual headers used in the signature. Amazon SES canonicalizes headers in a strict way—ordering, whitespace, and MIME folding all matter. If your mailer adds extra spaces, changes header order, or breaks a folded line improperly, the hash won't match. One difference, and the signature fails. This isn’t a configuration flaw—it’s a precise technical alignment issue. The sender’s header list must mirror the canonicalized version exactly. Misaligned headers aren’t rare. They’re common when third-party tools or custom code modify the message without respecting canonicalization rules.

Key takeaways

  • DKIM h= tag values must exactly match the canonicalized header list used in the signature
  • Amazon SES enforces strict header ordering and whitespace handling during DKIM signing
  • Extra spaces, incorrect MIME folding, or non-standard header ordering trigger h= uncanonicalized header list errors

Why Does This Error Break Email Deliverability?

When Amazon SES fails to canonicalize the DKIM h= tag headers, the DKIM signature invalidates entirely. Even one uncanonicalized header—like a misaligned From or To—breaks the entire signature. Without a valid DKIM check, strict mail servers reject your message or flag it as spam, especially under enforced DMARC policies. This means your emails won’t reach inboxes, even if the content is legitimate.

DKIM Failure Means Rejection

DKIM validation isn’t a suggestion—it’s a gatekeeper. If the headers listed in the h= tag don’t match the ones actually signed, the signature fails. This can happen if your email client or ESP like Amazon SES adds or alters headers (like Received, Deliverystatus, or Resent- variants) not in the original h= list. The result? The mail server doesn't trust the message. Major providers like Gmail, Microsoft, and Apple now enforce DMARC with reject policies, which means a DKIM failure means outright delivery failure.

Let’s say you’re sending transactional emails via Amazon SES. You’ve set up DKIM, but the h=From:To:Subject list doesn’t account for a header Amazon SES injects—like Precedence: bulk. That single mismatch invalidates the entire signature. A single email, one uncanonicalized header, and your deliverability crumbles. Even a well-written message ends up in spam or lost entirely.

Even a Tiny Misalignment Can Kill Inbox Placement

There’s no leniency here. DMARC policies don’t care if it’s just one header or minor formatting difference—validation is binary. The message either passes or fails. And since DMARC enforcement is increasingly standard across large inboxes, even a few failures can trigger sender reputation penalties.

You can test how your emails will land across major providers before sending. Use a real inbox placement tester to see if your DKIM setup holds up. Tools like MailTester's inbox placement test simulate delivery across Gmail, Outlook, and Apple Mail, catching these errors before they hurt your reputation.

For developers and marketers using Amazon SES, this means: verify your header list carefully, ensure every header in the message is either listed in h= or excluded from signing, and always validate using a DKIM validator. It’s a small step—but it prevents major delivery breakdowns.

For bulk sends, it’s wise to clean your list in advance. Use real-time verification tools to detect invalid or malformed addresses before you send. MailTester’s bulk verification checks each address for syntax, existence, and mailbox health—reducing bounce and failure rates before they occur.

How Does Amazon SES Canonicalize Headers by Default?

Amazon SES canonicalizes headers by converting field names to lowercase, collapsing multiple whitespaces into one, trimming trailing whitespace, and reassembling folded lines with single spaces. Headers are ordered by appearance in the message, not alphabetically. This ensures consistent DKIM signing regardless of how headers are formatted during transmission, which is critical when dealing with canonicalization issues like uncanonicalized h= tags.

Standard Header Normalization Process

When you send an email through Amazon SES, it applies a well-defined normalization process before signing the DKIM signature. The system takes each header field, converts the name to lowercase (like From → from), and normalizes the value by collapsing multiple spaces into a single space and removing any trailing whitespace.

Line folding—where a header value is split across multiple lines using a soft newline and whitespace—is handled by reassembling the content into a single line with a single space between words. This prevents discrepancies between the original message and the signed header list, which could break DKIM verification if the h= tag in the signature references fields in a different order or format than expected.

Order Matters: Headers Are Preserved in Sequence

Unlike some systems that sort headers alphabetically, Amazon SES preserves the order in which headers appear in the raw message. This behavior is intentional and aligns with the DKIM specification’s default simple canonicalization method. If your email includes From, To, and Date headers in that sequence, the DKIM h= tag will reference them in that exact order.

This means if you manually construct a message or use a library that sorts headers, it can result in a mismatch during DKIM validation. The signature may be valid, but the h= list will fail if the field order differs from what Amazon SES canonicalized.

For a detailed breakdown of how DKIM header canonicalization works at a protocol level, see RFC 6376, which defines the standard behavior for both simple and relaxed mode signing. You can reference it here: RFC 6376.

It’s also worth testing your DKIM setup with real email infrastructure before large-scale sending. Tools like inbox placement testing can help validate how your messages are perceived by receiving servers, including whether DKIM alignment is properly recognized.

How to Verify the Canonicalization of Your DKIM Headers

You must inspect your email’s raw source and confirm that the h= tag in the DKIM signature lists only the exact headers present in the message body, in the same order they appear. If the header list is incorrect or uncanonicalized—such as missing a header, listing it out of order, or including one not present—your DKIM signature will fail. Use tools like MxToolbox or a custom SMTP debugger to extract and verify the full header set during transmission. The DKIM spec (RFC 6376) requires strict canonicalization to preserve signature integrity.

Check Your Headers Against the Signed List

  • Open the raw message source from your sent email (in your email client or via a logging tool).
  • Locate the DKIM-Signature header and find the h= tag—this shows all headers used in the signature.
  • Confirm each header listed in h= appears in the message, is spelled exactly as in the raw source, and appears in the same sequence.
  • If you find extra headers, missing ones, or mismatches in capitalization, your signature will fail validation.

Use Trusted Tools to Inspect and Debug

  • Use MxToolbox's DKIM Checker to enter your email's raw source or public key and see how DKIM handles your header list.
  • When sending via Amazon SES, capture inbound or outbound SMTP logs to extract the full signed message, including all headers.
  • Compare the h= values against your actual message headers—no exceptions.
  • For complex email templates or dynamic content, test with multiple versions to catch variations in header ordering or injection.

Let’s be clear: DKIM canonicalization is not forgiving. A single mismatch in header order or spelling breaks the signature. The DKIM specification (RFC 6376) mandates that the signing process preserve header sequence and case exactly. If you’re sending through Amazon SES, ensure your email generation logic doesn’t add headers during transport that aren’t reflected in the h= tag.

If you're testing for deliverability risks, use MailTester’s inbox placement tester to see how your DKIM signature holds up across major providers. It checks not just the signature, but also alignment, content, and spam risk—all in one test.

Real-World Example: Fixing a Misconfigured DKIM h= List

When Amazon SES signs your email, the DKIM h= tag must list every header included in the signature. In this case, the signature includes X-SES-Template-Name, but the h= tag omits it—causing verification failure. The fix is simple: align the h= list exactly with the headers in the signature. Update the tag to h=from:subject:date:message-id:x-ses-template-name;.

What Went Wrong

You’re using Amazon SES with custom templates. The email header block includes: From, Subject, Date, Message-ID, and X-SES-Template-Name. But the DKIM h= tag only lists the first four. The signature algorithm includes all headers, so this mismatch triggers a DKIM verification failure.

How to Fix It Correctly

  1. Inspect the raw email headers using tools like MxToolbox or a debugging SMTP relay. Verify which headers are actually present in the signed message.
  2. Check the DKIM signature's h= tag in the email’s raw source. It must contain every header listed in the signature, in the same order. Missing or extra items break the validation.
  3. Update the h= tag to match the exact list: h=from:subject:date:message-id:x-ses-template-name;. Use lowercase, lowercase-only header names, and omit any extra whitespace or punctuation.
  4. Re-sign the message with the corrected header list. Amazon SES handles signing when you send via the API, but if you're generating the signature manually, ensure it matches the header order and content exactly.
  5. Test the result using a DKIM validator like the one at dkimvalidator.com or RFC 6376, Section 3.4—which defines canonicalization and header inclusion rules.

Amazon SES automatically adds X-SES-Template-Name to your email headers when you use templates. If your DKIM setup doesn’t include it in h=, the signature will fail. This is not a unique issue—it's a common misstep when managing custom headers with SES.

Using real-time email verification tools can help catch issues like this before sending. You can test a single address or your entire list with MailTester’s email checker to ensure deliverability is aligned with sender authentication standards.

Common Pitfalls in DKIM Header List Construction

If your DKIM h= tag includes headers not present in the final message, uses inconsistent casing, ignores the exact order delivered to Amazon SES, or allows mailers to reorder headers before sending, your signature will fail validation. Even one misaligned header can cause rejection, especially with strict receivers like Gmail or Yahoo. Use consistent header names, preserve the original order, and only include headers actually sent.

Header List Errors That Break DKIM

  • Include only headers that exist in the final message. Adding custom or fake fields—like a X-Tracking-ID not present in the actual email—invalidates the signature. DKIM signs what’s sent, not what you intended to send.
  • Use lowercase header names as defined in RFC 822, such as from, to, subject, and date. Even minor casing mismatches—like From instead of from—cause the hash to differ, leading to failure.
  • DKIM signs headers in the exact order they appear in the message as delivered to Amazon SES. Reordering headers during processing—common with email builders or SDKs—breaks the hash. The order must match exactly how SES receives the email.
  • Mailer tools like Mailchimp, SendGrid, or custom scripts sometimes normalize or reorder headers before sending via SES. If your DKIM signing step occurs before this, your header list may no longer reflect the actual delivery order. Let SES handle the final ordering to avoid mismatches.

Why This Matters for Amazon SES

Amazon SES requires exact alignment between the DKIM h= list and the delivered message headers. The AWS SES documentation emphasizes that even small discrepancies lead to signature verification failure, resulting in deliverability loss. This is especially critical when sending to receivers with strict policies, like Gmail or Yahoo Mail, which block unverified or malformed signals.

Many of these issues stem from automated tools that assume header order is flexible or that normalization is safe. But DKIM does not accept flexibility. The signing process must reflect the real delivery state. Testing your DKIM signature with tools that analyze the raw message helps catch these errors early.

Use inbox placement testing to send real messages through SES and validate not just delivery but also how your DKIM signature holds up in live mail environments. You can also use the real-time verification API to test headers during development, ensuring your final message aligns with your DKIM configuration.

How to Test DKIM Signature Validity Before Sending

You can prevent DKIM h= tag uncanonicalized header list issues with Amazon SES by validating your DKIM signatures before sending. Use MailTester’s real-time verification API or send a test message to their inbox tester to inspect the full email path, including header canonicalization and DKIM alignment. Catch issues early, before scaling outbound mailings.

Test DKIM alignment and header processing with real-world data

  • Use MailTester’s real-time verification API to validate the entire delivery path, including SPF, DKIM, and DMARC alignment, before sending to a large list.
  • Send a test message to MailTester’s inbox placement tester to receive a full header dump and analyze how Amazon SES's DKIM signing process handles header canonicalization, especially the h= tag.
  • Verify that all headers included in the h= tag are listed in the correct order and formatted without unnecessary whitespace—RFC 6376 requires strict header canonicalization for verification.
  • Check for inconsistent or missing headers (like From, To, Subject) in the h= field compared to the actual headers in the message—mismatched or extraneous headers break DKIM validation.
  • Use the returned signature analysis to confirm that the h= tag lists only valid, standard headers in the correct order and that no custom or non-standard headers are included unless explicitly required.

Validate before you scale

Running a full DKIM check on your outbound emails is not a luxury—it’s a necessity. Misconfigured DKIM headers cause delivery failures or lead to your email being flagged as suspicious, especially with aggressive services like Amazon SES.

Let’s say your mailing tool adds a custom header like X-Message-ID to every email. If that header is in the h= list but not in the email body, DKIM validation will fail. MailTester's inbox tester surfaces this issue visibly.

Best Practices for Maintaining DKIM Integrity with Amazon SES

Amazon SES signs your emails with DKIM by default, and you should never override that unless you have a very specific, rare need. If you manually sign messages, the h= tag in the DKIM signature may list headers in an uncanonicalized order—like including custom headers without proper normalization. This breaks DKIM validation, causing your emails to fail authentication. Always let Amazon SES handle the signing, and ensure all headers your app adds are explicitly listed in the h= tag, using lowercase names with no spaces.

Keep DKIM Headers Canonical and Complete

  • Never sign messages manually when using Amazon SES—let the service handle DKIM signing. Manual signing often leads to uncanonicalized header lists in the h= tag, which violates RFC 6376.
  • Ensure every header your application adds (e.g., X-Campaign-ID, X-Mailer, custom tracking fields) is included in the h= tag, listed in lowercase and separated by “.” (e.g., h=from:to:subject:date:content-type).
  • Use only lowercase for header field names. Uppercase or mixed-case headers are treated as different, leading to signature mismatches.
  • Avoid spaces in header field names. Use hyphens or underscores (e.g., x-campaign-id) to maintain consistency with the canonical form.

Test Before You Send

Even small misconfigurations in header alignment can cause DKIM failures. Always test your email templates with real-world deliverability tools before sending to large lists.

  • Use MailTester’s inbox placement test to verify that your DKIM signature passes validation in different inboxes—including Gmail, Outlook, and Yahoo.
  • Run a full bulk verification on your list before sending, especially if you’re using dynamic headers in templates.
  • Check if any of your headers are being stripped or altered by third-party services or email clients during delivery.
  • Monitor your sender reputation—DKIM failures contribute to lower deliverability, which can eventually trigger blocklists.

DKIM is only effective if the signed headers match exactly what’s in the message. Amazon SES enforces canonicalization automatically when you let it sign, but only if you don’t interfere. Let the platform do its job. A properly signed message with complete, correctly formatted headers passes authentication consistently. For a deeper look at email authentication standards, refer to RFC 6376, which defines the DKIM signature process.

Why Manual DKIM Signing on Amazon SES Is Risky

Amazon SES expects DKIM to be handled automatically by the service; manually signing messages increases the risk of misaligned headers, especially when the h= tag lists headers in an uncanonicalized order. Even a small deviation in header normalization—like extra whitespace or incorrect ordering—breaks the DKIM signature, leading to rejection or spam filtering, regardless of the key's validity. Let’s unpack why this happens and why it’s harder than it seems.

DKIM Normalization Is Strict and Automatic

DKIM signing relies on a strict, standardized way of normalizing headers before hashing. Amazon SES handles this normalization internally, ensuring that all headers are processed in a predictable, RFC-compliant way. When you sign manually, you must duplicate that normalization exactly—order, spacing, line breaks, and case. One misstep, like placing a header in the wrong sequence, creates an uncanonicalized list that fails validation.

Even if your cryptographic key is correct, the h= tag can reference headers in a sequence that doesn’t match what SES expects. For example, if your message includes From: and To: in that order, but your h= tag lists To:From: with improper spacing, the signature fails. This kind of error is hard to debug without direct access to SES’s internal processing logs.

Manual Signing Overloads Your Infrastructure

When you handle DKIM signing manually, you’re also responsible for key rotation, header order management, and ensuring the same logic applies across every message. Any change in how you format or transmit headers—say, from a new email template or a third-party integration—can silently break alignment.

Industry standards like RFC 6376 (which defines DKIM) specify that the h= tag must list headers in the same order they appear after normalization. If you’re doing this by hand, you’ve essentially re-implemented a critical part of the email infrastructure. Tools like MailTester’s email checker can verify whether the underlying email structure is clean and free of formatting flaws before sending, helping catch issues early.

Even when your logic is correct, subtle differences in how different SMTP libraries or email clients handle headers can cause mismatches. This is why many organizations using Amazon SES see intermittent DKIM failures when they try to implement manual signing. It’s not a bug in your code—it’s a mismatch between your header list and the server’s expected canonical form.

To avoid these issues, stick with Amazon SES’s built-in DKIM support unless you have a specific need for custom headers or signing control. When you do need advanced checks, use tools like inbox placement testing to validate deliverability before full-scale campaigns.

How MailTester Helps Prevent DKIM Header Issues

You can prevent DKIM h= tag uncanonicalized header issues with Amazon SES by validating your email headers before sending. MailTester’s inbox-placement testing simulates actual delivery, checking for proper DKIM header ordering and structure, and flags uncanonicalized or missing headers before they cause rejection. This stops problems before they hit the inbox.

DKIM Header Validation During Simulated Delivery

When you run an inbox-placement test with MailTester, the system simulates real-world delivery through major inboxes like Gmail and Outlook. Part of that simulation includes verifying how your DKIM signature’s h= tag aligns with the canonicalized header list. Misordered or missing headers in that list lead to DKIM signature failures, often resulting in rejection or spam filtering.

MailTester checks the entire header structure, including the order and inclusion of required fields like From, To, Date, and Subject. If a header is missing or out of sequence, it’s flagged in the report. This gives you a clear, actionable view of what’s breaking DKIM, even before you send a single email.

Real-Time API & Bulk Verification Catch Issues Early

Let’s say you’re integrating email sending into a workflow. The MailTester real-time verification API checks the full header structure and DKIM compatibility for each address as it’s added. It doesn’t just verify syntax—it checks whether headers in your email meet standards for canonicalization, which is essential when using Amazon SES or any strict email provider.

Bulk list verification via MailTester’s email list verify helps you clean out invalid or risky addresses before sending. It identifies problematic addresses that could trigger DMARC failures, greylisting, or bounce loops—common side effects of misconfigured DKIM headers. By removing these outliers early, you reduce the overall risk to your sender reputation.

DKIM and SPF alignment, properly configured header order, and valid DNS records are all part of a reliable email delivery chain. As outlined in RFC 6376, the DKIM specification requires strict header canonicalization. MailTester’s tools help enforce that standard automatically, so you don’t need to debug delivery issues after the fact.

The Bottom Line on DKIM h= Tag Alignment

DKIM h= tags must list the exact headers included in the signature, in the precise order they appear. Any variation — missing headers, extra headers, or reordered elements — breaks alignment.

Amazon SES enforces strict canonicalization. Even minor deviations in header order or labeling result in DKIM signature failure, leading to delivery issues or rejection.

Preventing these problems requires proactive testing. Tools like MailTester validate DKIM configurations in real-world conditions, catching alignment issues before they impact your sender reputation or inbox placement.

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 'DKIM h= tag uncanonicalized header list' mean?

It means the headers listed in the DKIM h= tag don’t match the standardized, cleaned version of headers in the message, causing signature validation to fail.

Can I manually sign emails with DKIM when using Amazon SES?

No—Amazon SES is designed to handle DKIM signing automatically. Manual signing increases alignment risk and can block deliverability.

Does the order of headers in the h= tag matter?

Yes—the order must exactly match the order of headers in the canonicalized message body, as processed by the mail server.

How can I check if my DKIM headers are properly normalized?

Use a tool like MailTester to send a test message and inspect the raw headers and DKIM signature alignment.

What happens when DKIM fails due to uncanonicalized headers?

The email may be rejected by receiving servers, especially under strict DMARC policies, leading to poor inbox placement.

Can MailTester detect DKIM header issues?

Yes—MailTester’s inbox-placement tests include DKIM validation and header alignment checks during delivery simulation.

Why does Amazon SES require header canonicalization?

To ensure consistent signature validation across all recipients, regardless of how headers are formatted in the client.

Is there a default set of headers AWS uses for DKIM?

AWS uses all visible headers in the message, processed with lowercase, whitespace trimming, and MIME folding resolution.

How often should I test DKIM alignment?

Test every new template and every major update to your sending workflow, especially before sending to large lists.

Can outdated email templates cause DKIM errors?

Yes—templates may contain stale headers not listed in the h= tag or may add headers that weren’t included in the original signature.