What causes a DKIM canonicalization error from line folding?

You send a message, the DKIM signature fails. The error log says "canonicalization error from line folding." You check the headers. They look fine. But behind the scenes, a single line-break in a long header field is breaking the signature.

DKIM doesn’t sign raw text. It canonicalizes the message first—normalizing whitespace, line breaks, and formatting exactly as the standard specifies. If line folding (splitting a long line across multiple physical lines) isn’t preserved correctly during SMTP transmission, the canonicalization process misreads the structure. The signature checks out, but the verifier sees a different content stream. That’s a canonicalization error.

This happens most often in email systems that don’t enforce strict line-length limits (78 characters) during outbound delivery. When a large header like a long Received or Content-Transfer-Encoding gets folded incorrectly—or not at all—the resulting parsed message diverges from the signed one. The signature becomes invalid, even if the content is correct.

Key takeaways

  • DKIM canonicalization assumes strict line folding rules; deviations break signature validation.
  • Line folding issues commonly appear in mail systems that allow or ignore 78-character line lengths during SMTP transmission.
  • Even a single improperly folded header line can trigger a DKIM canonicalization error, leading to failed authentication and possible delivery issues.

How does line folding break DKIM canonicalization?

Line folding — inserting newlines in headers or body content to meet 78-character limits — can break DKIM canonicalization if it introduces extra whitespace. DKIM requires strict line-by-line processing: header canonicalization collapses all whitespace to a single space, but if your email’s line fold adds more than one newline where only one was expected, the resulting signed digest no longer matches the receiver’s recalculated version. When that happens, DKIM fails, and your message may be rejected or marked as spam.

DKIM’s canonicalization rules are strict about whitespace

DKIM defines two canonicalization modes: header (h) and body (b). In header canonicalization, all whitespace — including spaces, tabs, and newlines — must be reduced to a single space. This means no matter how many newlines or spaces you use in a header field, they’re treated as one. But if your email client or mailing system inserts line folding that adds a second newline where only one should exist, the canonicalized output changes. The receiving server applies the same rule, recalculating the signature based on the folded, collapsed form — and if it doesn’t match your original signature, DKIM fails.

For example, imagine a From: header written as: From: John Doe <[email protected]>
If your mailer inserts a line break after John Doe, the resulting header might become: From: John Doe     <[email protected]>
This creates two spaces between “Doe” and “<john…” in the canonicalized form — one from the newline collapse, one from the indentation — which wasn’t in the original. The digest changes. That’s why some DKIM failures are caused not by signing errors but by how the email was formatted during transmission.

What to check when DKIM fails

When you see a DKIM failure, don’t assume the signature is wrong. Check the original email’s header and body for non-standard line breaks. Some tools or email platforms auto-indent or auto-fold headers without preserving the canonicalization rules. This is common in legacy systems or when using certain automation workflows.

According to the DKIM specification (RFC 6376), header canonicalization explicitly mandates that leading and trailing spaces are dropped and internal runs of whitespace are reduced to a single space. If line folding violates this, even slightly, the check fails. Use a tool that simulates real-world receiving servers to spot these issues early.

You can test how your email headers and body will be canonicalized before sending by running an inbox placement test with MailTester’s inbox placement checker. It doesn’t just validate syntax — it mimics actual recipient processing, including DKIM header canonicalization. Catching folding errors this way saves time and avoids delivery issues.

Which email systems commonly introduce line folding issues?

Older email gateways, poorly configured SMTP servers, and certain content management or API-driven email platforms often introduce line folding—breaking long headers into multiple lines—without respecting canonicalization rules. This disrupts DKIM signing, causing validation failures. You can’t always control this behavior, but you can test and verify it before sending.

Legacy email gateways and misconfigured SMTP servers

Some older email gateways or poorly configured SMTP servers insert line breaks arbitrarily, often after 78 characters as defined in RFC 2822. This is meant to ensure readability in text-only environments, but it breaks DKIM’s strict requirement for header content to remain unaltered from the time of signing.

If your outbound email passes through such systems, even a correctly signed DKIM header can fail verification. The canonicalization process expects headers to be in one continuous line (or folded exactly as signed), not fragmented by a third-party server. This is frequently seen in corporate email systems still using legacy infrastructure.

Automated platforms and API senders

Some email delivery platforms or content management systems apply automatic line wrapping to headers or body content before signing. Since DKIM signs the headers in a specific, exact format, any modification—even whitespace changes—invalidates the signature.

API-based senders using default formatting libraries (like certain Python or Node.js mailers) may also introduce folding if no line-length limit is explicitly set. These tools assume text should be wrapped, but they don’t account for canonicalization requirements. The result? A valid signature that fails during verification.

Let’s say you’re using a service that pre-processes your email. If it wraps headers after 78 characters during processing, but you signed them without that wrapping, the server that validates DKIM will see a different structure—and reject it.

Testing for this issue is possible. You can verify if the final delivered header matches your signed version using tools like inbox placement testing—a process that simulates real delivery while auditing header integrity.

How to test for DKIM canonicalization errors in real-time

You can detect DKIM canonicalization errors in real-time by sending test messages through a verification API that analyzes headers and validates DKIM signatures during delivery. These tools simulate how real mail servers process your emails, including how they fold long lines and canonicalize headers—exactly where line folding can break DKIM checks. The best way to catch these issues early is to test with a system that validates signatures in actual inbox conditions, not just in theory. RFC 6376 defines the canonicalization process, and missteps in line folding or header normalization are a common source of failure.

Use a real-time email verification API with DKIM analysis

  • Use an API that inspects both header structure and DKIM signature validity during message processing.
  • Send test emails with known header formats, especially those containing long, folded lines or multiple newlines.
  • Check the API output for mismatches between the signed header body and the one received by the receiving server.
  • Look for explicit warnings like “canonicalization mismatch” or “signature failure due to header folding” in the validation logs.
  • Enable full header logging to compare how your outbound message was formatted versus how it was interpreted on the receiving end.

Validate DKIM in actual inbox conditions with inbox-placement testing

  • Use inbox-placement testing to send emails through real-world mail servers and observe how DKIM validation succeeds or fails in practice.
  • MailTester’s inbox placement tests include full DKIM signature validation, showing whether canonicalization errors are causing rejections or flagging in real inboxes.
  • Compare results across multiple providers—Gmail, Outlook, Yahoo—to identify if the issue is specific to certain mail servers.
  • Check if the signing domain’s DNS records (DKIM records, SPF, DMARC) are correctly set to avoid additional validation failures.
  • Fix the message format—especially header folding—based on real test results, not theoretical assumptions.

Let’s be clear: DKIM canonicalization isn’t just a technical formality. A single line folding error can cause delivery failures even if all other authentication checks pass. The only way to verify this in practice is through real-time testing with systems that simulate actual delivery. Spamhaus confirms that authentication failures due to formatting issues are among the top reasons for email rejection. If you’re not testing with a tool that checks DKIM as it’s processed by live mail servers, you’re relying on guesswork.

Canonicalization is not optional. It’s how DKIM ensures that a message hasn’t been altered—line folding is where it breaks.

Step-by-step debugging process for DKIM signatures with line folding

When a DKIM signature fails due to canonicalization errors from line folding, the root issue is usually improper handling of header field wrapping during signature generation. You’ll find the error when the verified signature doesn’t match the one in the received email—let’s walk through how to isolate and fix it step by step.

  1. Extract the raw email from your sending system, including all headers and message body. This ensures you're working with the exact content that was sent, not a sanitized version. Many delivery tools strip or alter data during logging—use your SMTP logs or raw message dumps directly from the sender.
  2. Check for soft line breaks in header fields like From, To, or Subject. Headers that exceed 78 characters must be folded with a CR/LF followed by a space or tab. If your system adds line breaks mid-field without a proper delimiter, DKIM canonicalization will process it wrongly. The RFC 5322 standard specifies this limit clearly (RFC 5322, Section 2.1.1).
  3. Normalize all whitespace within header fields. Replace any sequence of spaces, tabs, or line feeds with a single space. DKIM requires this normalization during canonicalization to ensure consistent signature computation. If your system preserves multiple spaces or mixed line endings, the resulting signature will differ from what the receiving server expects.
  4. Rebuild the canonicalized header per the DKIM specification. Use the none or simple canonicalization method (typically simple for headers), which trims trailing whitespace, normalizes line breaks to CRLF, and removes leading spaces. Any extraneous CR/LF sequences left in the header will break the digest.
  5. Recompute the DKIM signature using the canonicalized header. Apply the same hashing algorithm (e.g., SHA-256) to the reassembled header and body. Compare the resulting signature with the one in the received email. A mismatch confirms a canonicalization error—usually due to improper line folding handling.

Common Fixes for Line Folding Issues

Most cases stem from email clients or libraries automatically wrapping long header lines without respecting the RFC’s requirement that folding must begin with a space or tab after the CRLF. If your sending system does this, reconfigure it to either avoid folding altogether or ensure the fold point is properly indented. Libraries like Python’s smtplib or PHP’s mail() function can introduce this flaw silently.

Validating Your Fix

After correcting the header format, resend a test email and repeat the process. Use tools like MxToolbox’s DKIM validator or DKIM Analyzer to test the signature. If the signature matches now, the issue was canonicalization due to broken line folding.

For teams building or managing email systems, verifying email addresses before sending—even for internal testing—helps catch delivery issues early. You can test single addresses with MailTester’s email checker to validate deliverability and format correctness down to the header level.

Best practices to prevent DKIM canonicalization errors from line folding

DKIM canonicalization errors from line folding happen when headers are split across lines before signing, breaking the expected single-line structure. To prevent this, never let line folding occur on headers before signing. Use tools that give you full control over header formatting, and validate your signed messages against the canonicalized output using a parser that enforces the rules. Let’s break down the key steps.

Header formatting before signing

  • Never apply line folding to email headers before DKIM signing. The entire header field must remain as a single logical line.
  • Ensure your email generation pipeline preserves the raw, uninterrupted header format during the signing phase.
  • Check that your MTA or email service doesn’t automatically wrap headers based on line length—this breaks canonicalization.

Validation and tool selection

  • Use outbound tools that allow explicit control over header formatting, particularly during SMTP transmission.
  • Avoid third-party email libraries that auto-wrap long header fields unless they explicitly respect RFC 6376's canonicalization rules.
  • Always validate signed messages with a parser that checks the DKIM signature against the exact canonicalized version of the headers and body.
  • Test your signed messages with a tool like MailTester’s inbox placement tester to verify how your emails are processed by real recipient servers.

If you’re managing large volumes, consider validating your DKIM logic in a staging environment before production use. Tools such as MailTester’s real-time verification API can help detect alignment issues early, especially in bulk sending pipelines.

Even a single folded header can invalidate a DKIM signature—canonicalization is strict and must match exactly.

Why you shouldn't rely on SPF/DKIM validators from public domains

Public tools like MxToolbox or DKIM Validator tell you if your signature matches a raw header format, but they don’t simulate how real email servers process your message. A DKIM signature can pass their check yet fail in delivery due to line folding or canonicalization discrepancies. Only inbox placement testing—like MailTester’s real-world deliverability checks—can confirm your signature survives actual recipient server processing.

What public tools miss: real-world server behavior

These tools validate syntax against a standard, but they don’t account for how real email providers handle whitespace, line length, or canonicalization during processing. For example, RFC 6376 (which defines DKIM) specifies strict rules for header line folding and canonicalization—rules that not all tools test against in practice.

Let’s say your DKIM header uses soft line breaks or embedded spaces during signing. A public validator may still pass it because it checks for correct signature alignment on the raw input. But real inbox servers—like Gmail or Outlook—may reformat the headers during receipt, altering the canonical form. If your signature’s canonicalized version doesn’t match, the email fails verification and may be rejected or quarantined.

Testing must mirror the actual delivery path

Validation tools that only check header syntax can’t confirm your message survives end-to-end processing across multiple inbox environments. Your email might hit a spam filter or fail inbox placement not because the signature is broken, but because of how canonicalization was applied during transit.

MailTester’s inbox placement testing sends real messages to actual inboxes across providers and evaluates whether the DKIM signature remains valid post-receipt. This is the only way to know if your signature will hold up when it matters. Unlike public validators, this approach includes full chain-of-delivery simulation, including how servers handle line folding, header normalization, and MIME parsing.

Public tools are useful for quick syntax checks—but they don’t replace real-world delivery verification. A signature that passes on MxToolbox can still cause delivery issues in practice. The only reliable way to catch these issues is by testing with tools that simulate end-user inbox behavior using real email infrastructure.

How MailTester helps identify and fix DKIM canonicalization issues

You can catch DKIM canonicalization errors caused by line folding before they break deliverability. MailTester’s real-time API and inbox-placement tests analyze your message as it’s sent, validating DKIM signatures against the actual header structure—including how lines are folded during transmission. It flags mismatches between the expected and received signature, often due to improper header normalization, so you fix the root cause before sending to real users.

How MailTester detects line folding issues in DKIM

  • MailTester's real-time verification API parses the full email message, including headers and body, exactly as it would be processed by recipient servers during transit.
  • It checks DKIM signatures in context—not just the raw signature, but how the headers were canonicalized during signing versus how they were received.
  • Line folding (where long header lines are split across multiple lines) can alter the header’s canonical representation. MailTester detects mismatches between the signed and received header structure, signaling a canonicalization error.
  • When line folding causes the canonicalized header to differ from the signed one, the DKIM verification fails—MailTester flags this explicitly, often showing you the exact line or field where the issue occurs.
  • It simulates real-world processing by major providers like Google (Gmail), Yahoo, and Microsoft (Outlook), which apply strict header normalization rules—ensuring your DKIM checks hold under actual delivery conditions.

Use MailTester to catch errors at scale before delivery

  • Test an entire mailing list with bulk verification to find all messages with DKIM signature failures related to canonicalization.
  • Apply the inbox-placement test to simulate how your message lands in real inboxes, including header normalization behavior across multiple providers.
  • Use the same test to validate campaign templates or automated email flows before sending to 100 or 10,000 subscribers—catching issues that would otherwise cause hard bounces or inbox filtering.
  • MailTester doesn’t just report a failure—it shows you why, down to the specific header field or line break that caused the issue, so you can adjust your signing process.
  • Unlike tools that only validate the signature format, MailTester’s approach respects the actual message structure, including how headers are folded in transit—matching the behavior defined in RFC 6376.

What to do when a DKIM signature fails but the domain looks correct

If your DKIM signature fails despite a correct domain and selector, the most common culprit is improper line folding in headers before signing — specifically, line breaks inserted in header fields like From or Subject that disrupt the canonicalization process. RFC 6376 mandates strict formatting: headers must be folded exactly as per standard rules, with each continuation line starting with a single space. Even a single missing space or an extra newline can break the signature. Use a tool that validates against the RFC to confirm your signing process preserves this structure.

Verify your signing process using RFC-compliant tools

  • Check the raw message before signing: search for any unintended line breaks in header fields such as From:, To:, or Subject:. Even a single line break where a space should be breaks the canonicalization.
  • Use a tool that respects RFC 6376 line folding rules — such as the DKIM Validator by MxToolbox or RFC 6376 itself — to simulate what the signing agent sees.
  • Test the message through a real email flow: the email must be signed exactly as it will be sent. If you're using a library or service, ensure it doesn’t auto-wrap long lines during transport.
  • Use MailTester’s inbox placement testing to check if headers are preserved end-to-end and if receiving servers see the signature as valid.
  • Ensure no automated system (like a routing engine, BCC processor, or email gateway) alters headers after signing. Even small changes — such as adding a X-Header: or reformating whitespace — can invalidate the signature.

Validate structure with real-world inspection

Let’s walk through a real example: you signed an email with From: [email protected] but the raw message contains a line break before the domain. The signing process sees From: [email protected] as two lines, which changes the canonicalized body and breaks the signature. Tools that don’t parse headers per RFC 6376 may not catch this. That’s why it’s critical to test with a validator that enforces strict folding rules.

The key issue isn’t the domain: it’s how the message was formed *before* signing. Double-check every header field for incorrect line breaks — especially when the header value is longer than 78 characters. Many email systems default to breaking lines at 78 chars, but only if they add a space after the break (as required by the standard). A missing space turns a valid line fold into an error.

Real-world example: A high bounce rate caused by DKIM failing due to line folding

One marketing team saw a 3.8% hard bounce rate on a 100,000-email send to Gmail — a red flag. Upon investigation, their DKIM signature was failing validation. The root cause? The From header was 84 characters, triggering automatic line folding during SMTP transmission. The DKIM signature was computed after folding, but the canonicalized header (used for verification) expected the original, unfolded form. This mismatch caused the signature to fail, leading to email rejection. After switching to a system that signs headers before line folding occurs, bounce rate dropped to 0.1%.

Why line folding breaks DKIM

DKIM relies on precise, consistent header canonicalization. When a header like From exceeds 78 characters, mail servers fold it onto the next line with a soft break. This folding is invisible to the sender but changes the raw header structure. If the DKIM signature is generated after this folding, the signing process operates on a different text than what the receiving server expects during validation — a canonicalization mismatch.

According to RFC 5322, line length in email headers should not exceed 78 characters, but many systems still send long headers. This is common in marketing emails with lengthy From addresses, especially when using campaign-specific naming or personalization. When DKIM signs the header after folding, the digest no longer matches the expected content, invalidating the signature.

Fix: Sign before folding, verify the flow

Preventing this requires signing headers before any line folding takes place. The signing process must operate on the original, unwrapped header. This is standard in well-implemented mail services and required by the DKIM specification.

Let’s say you’re sending to Gmail, which enforces strict DKIM checks. A poorly implemented sender might sign after the header is folded due to an incorrect message build pipeline. The fix isn’t in the signature itself — it’s in the timing. You must canonicalize and sign the header in its original, unfolded state before transmission begins.

Proactively testing your email flow—especially your DKIM and SPF configurations—can catch issues like this before they hit thousands of inboxes. Tools like inbox placement testing help verify deliverability in real-world conditions, including how major providers handle your headers and signatures.

For teams managing large lists, automated verification also matters. If you’re using a third-party sender, make sure it doesn’t fold headers before signing. The best way to avoid this problem is to test your setup with real emails using systems that simulate real-world deliverability. You can validate your header consistency and DKIM signing behavior with tools designed for this purpose.

In summary: Fix DKIM errors by controlling header formatting

DKIM signature validation fails when headers undergo line folding before signing, because canonicalization relies on exact header formatting. Even small differences in line breaks or whitespace can invalidate the signature.

Test in real-world conditions

Public DKIM validators often miss edge cases. Only inbox-level testing simulates how receiving servers interpret your signed headers and apply canonicalization.

Prevent issues with proactive verification

Use real-time verification and inbox-placement testing to detect and correct issues like line folding before they impact deliverability. MailTester’s 98.9% accuracy and API integration help identify and fix problems at scale, including DKIM canonicalization errors caused by header formatting.

Sources

Keep reading

Ready to put this into practice? MailTester verifies emails with 98.9% accuracy — start with 100 free verifications.

Frequently asked questions

Can line folding in email bodies cause DKIM canonicalization errors?

No. Only header canonicalization is affected by line folding in headers. Body canonicalization uses a different rule set and is not sensitive to line breaks.

Does Gmail enforce line-length limits on headers?

Gmail allows long headers but may normalize whitespace and line breaks during processing. This makes consistent line folding before signing essential.

How do I know if my DKIM signature is being miscanonicalized?

Compare the DKIM-Signature header with the expected digest after canonicalization. Use a tool that validates both the structure and the signature outcome.

Can DKIM still work if line folding happens after signing?

Yes, but only if the canonicalization process at the receiving end matches your original header structure. It's safer to avoid folding before signing.

Is there a standard line length for email headers?

Historically, 78 characters. Modern systems allow longer, but strict preservation of the original format is required for DKIM to pass.

How can I test DKIM signatures without sending emails?

Use MailTester’s real-time API with raw email data to simulate delivery and test DKIM validation without sending to users.

Do all email providers handle DKIM canonicalization the same way?

Most follow RFC 6376, but differences in whitespace normalization can cause mismatches. Testing in actual inboxes is the only definitive check.

Can a catch-all email address cause DKIM validation to fail?

No. Catch-all addresses receive mail, but DKIM validation is tied to the signature and header content—not whether the address is valid.

Why does my email pass DKIM in tests but not in production?

The test environment may not enforce the same header formatting or canonicalization rules as actual receiving servers. Use inbox-placement testing to replicate real conditions.

Can I fix DKIM canonicalization errors after the message is sent?

No. Corrections must happen before signing. Once sent, the signature is fixed and cannot be altered without invalidating it.

What’s the role of the AI assistant in MailTester for delivery issues?

It analyzes verification and deliverability results to recommend actionable fixes, including identifying header formatting issues tied to DKIM failures.

Can disposable domains affect DKIM signature validation?

They don’t directly affect DKIM validation. But if they’re used in sending, they may lead to high bounce rates or low sender reputation, indirectly affecting deliverability.