How does DKIM work, and why does it care about header order?

You sent a perfectly formatted email. The signature checks out. And yet, it fails DKIM validation every time.

Not because of a typo or a misconfigured domain. Because of invisible line breaks—header field folding—that break canonicalization.

DKIM doesn’t sign raw email text. It signs a normalized version of the headers, where line breaks, whitespace, and field order are standardized. Any deviation between signing and verification means the signature fails.

Header field folding—where long header values are split across lines using whitespace—seems harmless. But if not handled correctly, it introduces variance in the canonicalized output. That’s the core problem: DKIM canonicalization assumes consistent formatting.

Key takeaways

  • DKIM canonicalization standardizes line breaks, whitespace, and header order to ensure consistent signing and verification
  • Header field folding that adds or removes whitespace between folded lines breaks canonicalization if not preserved or normalized
  • Even minor, unnoticeable line break changes in headers can cause DKIM verification to fail, even when the content is identical

What is header field folding, and why does it exist?

Header field folding is a rule built into email protocols (SMTP, HTTP) that limits each line to 998 characters. When a header value exceeds that, it must be split across multiple lines using a space or tab at the start of each continuation line. This isn't optional—it’s required by RFC 5322 and RFC 6854 to ensure systems can reliably parse and process headers, no matter how long they are.

Why the 998-character limit exists

The limit dates back to early internet standards where line-based systems were fragile with long text. A maximum of 998 characters per line ensures compatibility across older or simpler systems that might reject or misread excessively long lines.

Each time a header line gets too long, the protocol forces you to “fold” it. This means inserting a newline and then adding a space or tab at the beginning of the next line, so the receiver knows it’s part of the same header. For example, a long Received or DKIM-Signature header might break into multiple lines this way.

How folding impacts DKIM and canonicalization

DKIM relies on a consistent, predictable format of headers—called canonicalization—to verify signatures. The signer and verifier must compute the same hash of the header fields. But folding changes how headers are represented.

If the header is folded differently during signing versus verification (e.g., one system uses space, another uses tab, or the line breaks are in slightly different places), the hash will differ. That’s why even a single space or tab variation in folding can break DKIM validation, even if the content is identical.

This is why tools that build mail headers—especially in bulk email systems—must be careful to follow strict folding rules. The SMTP specification and RFC 6854 define these rules precisely, and compliance is non-negotiable for deliverability.

Let’s be clear: folding isn’t a bug. It’s how the system was designed to work. But when it’s applied inconsistently, it breaks cryptographic integrity—especially in DKIM, where small deviations invalidate the signature.

If you’re building or validating email systems, especially with automated tools or APIs, always test how your software handles header folding. Tools like MailTester’s email checker can help validate not just addresses, but how headers are formatted—before they go out.

Why does header field folding break DKIM canonicalization?

DKIM canonicalization normalizes header formatting to ensure consistent hashing, but it requires exact reconstruction of folded header lines—especially whitespace and line breaks. If the verification process fails to reassemble a wrapped header line identically (e.g., collapsing or altering spaces), the canonicalized header differs, causing DKIM verification to fail—even when the message content is unchanged. This mismatch often stems from improper handling of whitespace and line continuation during canonicalization.

The problem: folding vs. reconstruction

Header field folding occurs when a long header value is split across multiple lines using a soft line break (CRLF followed by a single SP or HTAB). While the mail client or MUA may display this as a single line, the raw message retains the artificial line break. DKIM requires that this folding be reversed exactly during canonicalization—every space and line break must be preserved as they were in the original message.

Let’s say a header like Subject: Meeting scheduled for Thursday is folded into: Subject: Meeting scheduled for Thursday That’s not the same as Subject: Meeting scheduled for Thursday. If the verifier doesn’t reconstruct the original spacing and line breaks precisely, the hash changes, and DKIM validation fails.

Where things go wrong

Most DKIM failures due to folding come from incorrect whitespace normalization. Some systems collapse multiple spaces into one or misinterpret soft line breaks as hard ones. Others strip trailing whitespace or convert line breaks inconsistently. These small deviations, while invisible to humans, break the cryptographic integrity of DKIM.

According to RFC 6376 (the DKIM standard), canonicalization must preserve the logical structure of headers while normalizing formatting. Specifically, it mandates that "line breaks in the header must be preserved as CRLF," and folded lines must be recombined with a single SP or HTAB, not a newline or multiple spaces. This is a narrow but critical detail.

Even if your message body is correct and your SPF/DKIM records are properly configured, a single misinterpreted line break can break authentication. This usually happens in mailing systems that don't apply strict canonicalization rules during signing or verification.

For example, some email platforms or libraries silently normalize whitespace in headers before applying DKIM signatures. This works fine if both signers and verifiers use the same logic—but if the verifier expects exact folding reconstruction and receives a normalized version, the signature fails.

You can catch this kind of issue early with inbox placement testing. Use MailTester’s inbox placement tool to simulate real-world delivery—and see if DKIM fails due to subtle header formatting changes before sending to real users.

What’s the difference between relaxed and simple DKIM canonicalization?

Relaxed DKIM canonicalization normalizes whitespace and treats folded header lines as a single logical line, making it tolerant of formatting changes during transit. Simple canonicalization preserves the exact formatting, including line breaks and folding — it’s stricter and more brittle. Most email systems use relaxed canonicalization, but it only works if the folding is processed correctly during signing and verification. If not, DKIM fails, even when the message is valid.

How relaxed and simple differ in practice

Let’s walk through the key differences. Relaxed canonicalization applies normalization rules to both headers and body content, standardizing whitespace and ignoring line folding. It treats a message where a long header is split across multiple lines (like a Subject: with wrapped content) as a single logical line. This is why relaxed is used by Gmail, Outlook, and most modern email providers — it’s resilient.

Simple canonicalization, on the other hand, does not normalize. It treats each line break exactly as it appears. So if a header line is folded into multiple physical lines with newlines, the verifier must match that exact structure. This is rarely used in practice because it breaks easily when mail servers or intermediaries reformat headers.

Why folding matters: a real-world consequence

When a DKIM signature is generated with relaxed canonicalization, but the message is canonicalized using simple rules during verification, the signature fails — even if the content is identical. This is why malformed folding or incorrect canonicalization during sign/verify is a common reason DKIM checks fail across systems like Gmail or Yahoo. It’s not always the sender’s fault — many third-party tools handle folding incorrectly.

Feature Relaxed Canonicalization Simple Canonicalization
Whitespace handling Normalizes multiple spaces or line breaks into single spaces. Treats all whitespace as equivalent. Preserves exact whitespace. Newlines and spaces are significant.
Line folding Treats folded lines as single content units. Ignores line breaks within header values. Preserves every line break exactly. A folded line counts as separate.
Common use Used by 90%+ of modern email providers (Gmail, Outlook, Apple Mail). Used only in niche or legacy systems. Not practical for production use.
Robustness High. Works across mail servers that reformat headers. Low. Fails easily if any intermediary reformats messages.
Standard reference RFC 6376, Section 3.4 defines relaxed canonicalization as the default for all but legacy systems. RFC 6376, Section 3.5 covers simple canonicalization as an optional, rarely used alternative.

When building or debugging DKIM, always ensure your signing software uses relaxed canonicalization and handles folding correctly. Tools that don’t, such as some poorly implemented email clients or third-party mailing scripts, can break signatures silently.

Verify your DKIM setup with a real inbox placement test. Test actual delivery to multiple inboxes, including Gmail, Outlook, and Yahoo, to catch hidden issues like incorrect canonicalization before they impact your deliverability.

How to fix DKIM failure caused by header field folding

DKIM fails when header field folding isn’t handled consistently during canonicalization. Use relaxed canonicalization on both signing and verifying systems, ensure all components reassemble folded lines before processing, normalize whitespace, and validate with real delivery tests. Debugging mismatches requires logging canonicalized output at both ends.

Fix DKIM alignment at the protocol level

  • Set Canonicalization=relaxed/relaxed for both signing and verifying systems. This allows minor line folding and whitespace changes without breaking the signature.
  • Ensure every component in your email pipeline—MTAs, ESPs, gateways—reconstructs folded lines before applying canonicalization. Never skip whitespace normalization; it’s required by RFC 6376.
  • Test your DKIM signatures in a real delivery environment. Tools like Spamhaus or MxToolbox can validate how your message is received and processed.

Diagnose and lock down configuration mismatches

  • Enable logging of canonicalized headers during signing and verification. Compare outputs side-by-side. Even small differences—extra spaces, line breaks—can break DKIM.
  • Don’t assume your email provider handles folding correctly. Check your ESP’s documentation on DKIM behavior. Some systems apply strict canonicalization by default, which conflicts with relaxed folding.
  • Use inbox placement testing to verify that your emails reach the inbox with valid DKIM. Tools like MailTester’s inbox placement tester simulate real-world delivery and surface alignment failures early.
  • Run verification on every email address before sending. Prevent send errors by catching invalid or malformed addresses—something MailTester’s email checker handles reliably at scale.

What tools can verify DKIM and header folding alignment?

You need a delivery test tool that simulates real inbox behavior and exposes the raw email structure after transit—specifically, one that shows if header field folding altered the canonicalized content, causing DKIM signature mismatches. ESPs like SendGrid or Mailgun may report DKIM failure but won’t detail whether canonicalization drift from folding is the root cause. Tools that only test syntax or basic delivery won’t catch this subtle but critical issue.

Why ESP-native tools fall short

Most ESPs validate DKIM signatures on their own servers but don’t show the final, transit-processed version of your email. They may flag "DKIM verification failed" and stop there. But if the header fields were folded during transit (a common SMTP behavior), the canonicalization process used to generate the DKIM signature differs from the one applied by the receiving server. This mismatch breaks alignment, but the ESP doesn’t expose the raw differences.

Let’s be clear: folding itself isn’t the problem. But how folding affects canonicalization is. RFC 5322 and RFC 6376 define how header fields should be normalized—line breaks, whitespaces, and folding must be consistently handled. If an ESP doesn’t simulate this end-to-end, you’re left guessing.

How MailTester reveals folding issues

MailTester’s inbox-placement testing goes beyond basic syntax checks. It sends your email through real mail server paths, captures the raw message after transit, and shows the exact headers and body content as delivered. If fold points shift during transport—say, a 78-character line is split differently in the wire format—you can see the divergence in the canonicalized structure.

This lets you confirm whether DKIM failure stems from folding-induced canonicalization drift. For example, if your tool shows a DKIM signature that doesn’t match the received headers, MailTester’s inbox tester shows you the actual raw headers the recipient sees, helping you trace whether misaligned line breaks broke the alignment.

Unlike other tools that may not differentiate between missing DKIM keys and folded-content issues, MailTester surfaces this detail. It’s not a guess—it’s visibility into the actual delivered message. You can verify if your email’s headers are folding at points that alter the canonicalization, and adjust your sending setup accordingly.

If you’re debugging DKIM issues and suspect folding, run a test via MailTester’s inbox placement tester. It shows you the final delivered message, including the actual header structure, so you can confirm whether folding broke canonicalization—or if the real problem lies elsewhere.

How to verify your DKIM setup is immune to folding issues

DKIM signing can fail silently if headers are folded in ways that disrupt relaxed canonicalization. Even minor inconsistencies in line breaks—especially in headers like From, Subject, or Content-Type—can cause a valid signature to be rejected.

Test your setup with real-world signals

Send test emails using MailTester’s inbox-placement API. Examine the raw email structure in the delivery report to spot irregular line breaks or unexpected folding patterns in critical headers.

Align your systems on canonicalization

Ensure both your signing and verification systems apply the relaxed canonicalization algorithm the same way. Differences in how whitespace and line breaks are normalized will cause signature mismatches, even with correct keys.

Use the in-app AI assistant in MailTester to analyze a DKIM failure report. It identifies misalignments in header handling and recommends precise fixes to maintain signature validity across all email clients and systems.

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 exactly is DKIM canonicalization?

It’s the process that normalizes email headers and body content so that DKIM signatures can be verified consistently, regardless of formatting. It handles line breaks, spacing, and order.

Does every folded header line break DKIM?

Not necessarily—but if the canonicalization step doesn’t reassemble folded lines identically, the signature will fail during verification.

Can using relaxed canonicalization fix folding issues?

Yes, when implemented correctly. Relaxed canonicalization treats multiple lines with whitespace as a single logical field—provided both signing and verifying systems do it the same way.

Why do some tools miss DKIM failures caused by folding?

Most tools only report DKIM signature failure without showing canonicalization differences. Only full email transit testing reveals the real cause.

Through inbox-placement testing, MailTester captures the raw email after transport and checks DKIM using the actual recipient's receiving system, identifying canonicalization drift.

Is header folding a common cause of DKIM failure?

Yes—especially when systems use different canonicalization rules or fail to reassemble folded header lines properly.

Can email clients detect header folding issues?

Clients don’t enforce DKIM correctness. They only render content. The failure only appears during email verification or inbox filtering.

Do all DKIM implementations handle relaxed canonicalization the same?

No—implementation differences, especially in how whitespace and line continuation are processed, lead to verification mismatches.

Should I avoid header folding altogether?

No—folding is required by SMTP standards. Instead, ensure your signing system correctly enforces relaxed canonicalization across all components.

How do I test if my email system handles folding correctly?

Use a real delivery test with MailTester’s inbox placement feature, and check the raw header output. Compare it to expected formatting using RFC-compliant validation.

Can disposable emails or role addresses trigger DKIM failures?

No—these affect delivery or reputation, not DKIM. Folding-related issues are a technical signing misalignment, not a recipient-side issue.

What’s the most reliable way to prevent DKIM errors from folding?

Use consistent relaxed canonicalization across signers and verifiers, and validate the full email structure using a tool that simulates real inbox receipt.