Why Does DKIM Header Canonicalization Fail with Non-Standard Line Endings?

You’re sending a perfectly valid email, but it’s getting rejected or marked as spam. You’ve checked the SPF, DKIM, and DMARC records. Everything looks correct. Then you find it: a single misaligned line break in a header field. That’s all it took.

DKIM relies on strict header canonicalization—headers must be normalized in a precise way before hashing. If the line endings aren’t in standard CRLF format, or if a carriage return appears in the middle of a header line, the signature breaks. Even one incorrect byte can invalidate the entire DKIM check.

Here’s what happens: the signing server and receiving server must see the same header content, byte-for-byte. Non-standard line endings introduce discrepancies. The receiving server recalculates the hash, finds a mismatch, and rejects the message.

Key takeaways

  • DKIM canonicalization requires consistent CRLF line endings in all header fields.
  • Even a single CR character inside a header value, not at the end of a line, breaks canonicalization.
  • Mail servers reject messages with DKIM signature mismatches caused by malformed header line endings.

How DKIM Header Canonicalization Works (and Where It Breaks)

DKIM signature validation fails when headers use non-standard line endings—like LF-only or CR-only—because RFC 6376 requires all line breaks to be normalized to CRLF. Relaxed canonicalization treats whitespace and line breaks predictably, but only if the sender’s email software follows these rules. If it doesn't, the verifier sees a different header sequence than expected, and the signature is rejected.

What DKIM Canonicalization Actually Does

DKIM defines two canonicalization methods: 'simple' and 'relaxed'. In practice, 'relaxed' is used almost exclusively. It normalizes header values by preserving only the first space in a line, collapsing multiple spaces into one, and requiring line endings to be CRLF (carriage return + line feed).

That final step—CRLF normalization—is where many email systems fail. If your mail server, app, or third-party email service sends headers with LF (line feed only) or CR (carriage return only), the receiving server sees a different sequence during verification. Even one mismatched line ending breaks the signature check, and the message fails DKIM validation.

Why This Breaks in the Real World

Many email tools, especially those built on lightweight frameworks or custom SMTP clients, don't enforce CRLF strictly. Some systems default to LF for compatibility with Unix-like systems or because they were never tested with real-world DKIM verifiers. The result? A signature that looks valid on paper but fails in practice.

For example, a header like From: [email protected] sent with LF-only breaks the canonicalization chain. The receiving server expects CRLF and finds LF instead. This mismatch is detected immediately, and the DKIM signature is marked invalid—no matter how correctly the rest of the signature was computed.

According to RFC 6376, section 3.4, "the canonicalization process normalizes line endings to CRLF." This isn't optional. It's required. You must ensure your sending system produces CRLF consistently. If you're seeing DKIM failures and your key, domain, and body signature are correct, this is likely your issue.

Testing for this issue manually is difficult. Real-world DKIM verifiers don’t report back which line ending caused the failure—only that it failed. You can simulate this using a full inbox placement test that checks all aspects of delivery, including authentication. MailTester’s inbox placement test checks DKIM validity as part of a broader deliverability evaluation, helping you identify issues like malformed line endings before they impact your sender reputation.

Common Sources of Non-Standard Line Endings in Email Headers

Non-standard line endings in email headers usually stem from legacy systems, poorly configured MTAs, or custom code that doesn't normalize line breaks to the RFC 5322 standard (CRLF). These issues often occur when Unix-style LF endings are used in environments expecting CRLF, especially in outbound email flows. The mismatch breaks DKIM signature verification because canonicalization processes rely on consistent, predictable line endings across the entire header.

Limited MTA Configuration and OS-Dependent Behavior

Many older mail transfer agents (MTAs) were built with OS-specific assumptions about line endings. A Unix-based MTA might output headers with LF-only line breaks, while a Windows-based system expects CRLF. If the MTA doesn’t normalize the output during message assembly, the resulting header diverges from the standard. This divergence breaks DKIM because the signature is computed based on a specific canonicalized form, and any deviation invalidates it.

Even modern MTAs can slip on this if misconfigured. For example, if a relay or gateway passes raw messages through without enforcing proper CRLF conversion, the header ends up with inconsistent line breaks. This is especially common in transitional setups, or when using older open-source mail software like Exim or Sendmail with default settings that don’t account for RFC compliance.

Custom SMTP Clients and Script-Based Senders

When you write your own SMTP client or use a scripting language (like Python, PHP, or Node.js) to send email, line-ending normalization must be handled explicitly. Most languages default to OS-native line endings, so your script may emit LF on Linux or CRLF on Windows without you realizing it. If the code doesn’t explicitly enforce CRLF in headers, DKIM signature verification fails.

Let’s be clear: sending without canonicalization isn’t just a minor incompatibility—it’s a direct cause of signature failure. Even small deviations like a single LF in a header field can ruin the cryptographic check. RFC 5322 mandates CRLF for line endings in headers, and DKIM relies precisely on this.

Many email builders or template engines in CMS platforms or SaaS tools don’t enforce RFC compliance either. They generate HTML or text content without normalizing line breaks in the underlying headers. When these are stitched into an email, the resulting message inherits that inconsistency. It’s a silent issue—it won’t trigger immediate errors during delivery, but it will fail signature checks and hurt sender reputation.

If you’re unsure whether your email system handles line endings correctly, test it. Use our inbox placement tester to send a real message and inspect how it’s processed across major inboxes. It shows you delivery, spam score, and whether DKIM passes—before you send to real users.

How to Diagnose a DKIM Canonicalization Mismatch

You can diagnose a DKIM canonicalization mismatch by inspecting the raw email source for misaligned DKIM-Signature headers, validating header line endings (especially CRLF vs LF), and using tools like MxToolbox or MailTester’s inbox placement test to simulate delivery and catch explicit rejection messages like 'dkim: bad signature' or 'canonicalization mismatch'.

Check the DKIM-Signature Header in Raw Email

  • Open the raw email source of a failed delivery — you can find this in your email logs or through a delivery test.
  • Locate the DKIM-Signature header and verify the h= field lists all headers used in the signature, including the order and presence of all header fields.
  • Ensure that line endings in the header are CRLF (that's \r\n), not just LF — this is a common cause of mismatch.
  • Compare the header field values in the signature with those in the actual message. Even a single space, missing hyphen, or incorrect line ending breaks the match.

Test with Deliverability Tools and Watch for Errors

  • Run an inbox placement test using MailTester’s inbox placement tool — it simulates real-world delivery and returns detailed rejection reasons.
  • Check for specific error codes like dkim: bad signature or canonicalization mismatch in the test results.
  • Use public tools like MxToolbox to send a test message from a known domain and examine the DMARC/DKIM validation log for warnings on line ending or field alignment.
  • Pay attention to headers that don’t match exactly — even a case difference in field names or extra whitespace in a value can trigger a failure.
  • Review the full RFC 6376 (DKIM specification) if you're unsure how header fields or body content are to be canonicalized during signing.
Canonicalization is not just about signing — it’s about ensuring the sending and receiving ends interpret the same fields in the same way. A single misaligned line ending breaks the entire verification chain.

If your tool returns a rejection but not enough detail, test the same address with MailTester’s email checker to confirm it’s properly formatted and free of temporary issues like role accounts or disposable domains. Fixing canonicalization mismatches requires precision: check every field, every line ending, and every whitespace. No exception.

Step-by-Step: Fixing Line Ending Issues in Your Email System

DKIM header canonicalization mismatches often stem from incorrect line endings in email headers. Ensure your MTA or email library uses CRLF (Carriage Return + Line Feed) at the end of every header line. This is required by RFC 5322, the standard governing email format, and any deviation breaks DKIM signature validation. Even missing a single CRLF can cause your emails to be rejected or marked as spam.

Check Your Email Sending System Configuration

  1. Review your MTA or SMTP library settings. Make sure it’s configured to output headers with CRLF line endings. Some systems default to LF (Line Feed only) or automatically normalize line endings in ways that break DKIM canonicalization. This is especially common in custom senders or scripts using low-level socket connections.
  2. Enforce CRLF explicitly in code. If you're building your own email sender, never assume the stack will handle this correctly. Force CRLF at the end of every header line, including the last one before the body. Even a missing newline after the header block can trigger a canonicalization mismatch during DKIM verification.
  3. Normalize line breaks in templates and content tools. Email templates, renderers, and content generators often pull text from various sources (e.g., user input, CMS exports) that may use different line endings. Validate and normalize all content to CRLF before building the final headers. This includes any dynamic fields used in headers like From, To, or Subject.
  4. Test output with real tools. Use a raw email generator to manually construct a message with expected line endings and check if the DKIM signature remains valid. Alternatively, use MailTester’s real-time verification API to inspect header formatting in a real-world delivery context before sending to a live list.

Verification and Validation

Always test emails after making changes. Email systems vary in their tolerance for misformatted headers. What works in one setup might fail in another. A single malformed header can cause your entire message to fail DKIM validation—even if the content is correct.

For consistent results across email providers, follow the rules defined in RFC 5322 Section 2.2, which specifies CRLF as the required line ending for all header fields. This standard is applied universally by major email providers, including Gmail, Outlook, and Yahoo.

Use tools like inbox placement testing to simulate delivery and analyze whether header issues impact inbox routing. These tests catch issues before they affect sender reputation or trigger spam filters.

How MailTester’s Inbox Placement Test Detects DKIM Issues

You can catch DKIM header canonicalization mismatches caused by non-standard line endings by testing your email through real inboxes at Gmail, Outlook, and Yahoo. MailTester simulates your actual sending stack and validates the full flow—headers, authentication, and delivery—flagging exactly which header field failed due to line-ending issues and why the DKIM signature was rejected.

Testing the Real Email Flow

Unlike simple syntax checks, MailTester sends actual test emails using your configured sending setup. This means SPF, DKIM, and DMARC are tested in context—exactly how your recipients will see them.

MailTester checks every header field during the DKIM signature validation process, including those often overlooked, like From, To, or Subject. It applies the canonicalization rules defined in RFC 6376, which require line endings to be converted to CRLF (carriage return + line feed) before signing.

If your email server or library uses LF-only line endings (common in Unix systems), the canonicalized header won’t match the one signed by the sender. This mismatch breaks DKIM validation, often silently, leading to rejected messages or spam filtering.

Clear, Actionable Results

When a DKIM validation fails due to line-ending discrepancies, MailTester doesn’t just say “failed.” It identifies the specific header field and explains the root cause—e.g., “Subject field had LF-only line endings, violating RFC 6376 canonicalization rules.”

This precision helps you debug whether the issue lies in your email library, your mail transfer agent, or your content generation process. You're not left guessing—just fixing.

For more context on how DKIM works, refer to the official specification at IETF RFC 6376. The canonicalization process is defined there, including the importance of consistent line endings across all header fields.

If you're testing multiple domains, or need to verify bulk lists before sending, you can run inbox placement tests at scale. MailTester’s real-time delivery tests are available via the inbox placement tool, which covers major providers and includes full header inspection.

Preventing Future Mismatches: Best Practices for Header Standardization

Normalize line endings to CRLF before signing DKIM, use trusted email libraries, validate headers with a parser, and test inbox placement regularly with tools like MailTester. These steps prevent canonicalization errors and maintain sender reputation.

Core Fixes to Implement Now

  • Always convert line endings to CRLF (\r\n) before signing a DKIM header—this is required by RFC 6376 and prevents signature mismatches.
  • Use well-tested email libraries like Nodemailer or SendGrid’s SMTP client, which handle RFC-compliant formatting correctly and reduce implementation errors.
  • Do not sign headers directly from template engines—parse and validate them with a standards-compliant parser to ensure consistency and correctness.
  • Run inbox placement tests using MailTester’s API before any campaign send to catch delivery issues like DKIM mismatch or spam filtering early.

Layer in Proactive Validation

Even if your code looks correct, email headers from templates can introduce subtle issues. A malformed newline in a header field—like a single LF instead of CRLF—can break DKIM validation. Always normalize the entire header block before signing.

Consider using RFC 6376 as a reference for the canonicalization process, especially the relaxed and simple methods. You can review the standard at RFC 6376, Section 3.4 to understand how line endings affect signature calculation.

Let’s be clear: raw output from templating engines (especially in web frameworks) often doesn’t respect email header formatting rules. If you’re building headers manually, it’s easy to miss edge cases—like a trailing space or inconsistent line breaks. A parser catches these before signing.

Regular testing with MailTester’s inbox placement tool—available at inbox placement tester—helps you simulate real-world delivery conditions, including how your DKIM signature holds up across providers.

Once you’ve validated your headers, you can use the email verification API to catch invalid or risky addresses during list cleansing, reducing bounce rates and protecting sender reputation.

These steps aren’t optional. They’re the difference between a clean inbox and a blocked message. Keep your process automated, your libraries trusted, and your verification active.

Why Manual Verification Isn’t Enough for DKIM Header Issues

You can't catch a DKIM header canonicalization mismatch with non-standard line endings just by opening an email in Gmail or Outlook. These clients normalize line endings silently, hiding the exact formatting errors that break signature validation. Only the receiving server or a precise testing tool sees the raw header differences that cause DKIM to fail, meaning human review and basic spam checks miss the root problem completely.

Raw Headers Are the Only Real Test

DKIM validation happens entirely on the server side, using the exact header sequence sent over the wire. If your email client or mail server inserts or alters line endings (like CRLF vs LF or mixed line endings), the signature won’t match—unless you examine the raw source. Most email tools don’t expose this level of detail, so the error remains invisible.

Even if your email looks fine in a reader, a single misplaced line ending after a header field (like From:, To:, or Date:) can invalidate the entire DKIM signature. The receiving server will reject the message with a dkim=permerror or auth-failed result, but you won’t know why unless you inspect the raw header.

How to Actually Fix It

Luckily, you don’t need to manually parse every message. Tools that simulate real receiving servers can test your raw email headers for canonicalization issues. These include proper handling of whitespace, field ordering, and line endings, matching the RFC 6376 specification. This is the only reliable way to catch issues that slip through standard client inspection.

Using a service like MailTester’s real-time verification API lets you test email content—including headers and DKIM alignment—before sending at scale. It checks for known formatting pitfalls like incorrect line endings and ensures your messages pass DKIM validation in practice, not just in appearance.

Standard spam checks or inbox previews won’t detect this. They don’t parse the raw header flow or validate signature algorithms. Relying solely on those tools means sending emails that appear clean but fail authentication silently. This kills deliverability and harms sender reputation over time.

For teams using automation or bulk email, a pre-send validation step with real header parsing is essential. As RFC 6376 states, canonicalization must be consistent—any deviation breaks the signature. Tools that test this at scale, like MailTester’s bulk verification, are the only way to ensure your emails actually pass DKIM validation on real servers.

The takeaway: if you’re not testing raw headers with a tool that simulates server-side validation, you’re flying blind. Line endings might seem trivial—but they’re a common cause of failed delivery, and only automated testing catches them.

Using MailTester to Test and Fix DKIM Configuration

You can diagnose and fix a DKIM header canonicalization mismatch with non-standard line endings by testing your email’s full authentication stack in real time. Use MailTester’s inbox placement test to send a sample message through actual mail servers and receive the raw headers and rejection reasons — including DKIM validation failures caused by inconsistent line endings in the email header. This reveals exactly where your authentication chain breaks.

Test Your Domain’s Authentication Stack

Run a real-time verification on any email address from your sending domain using MailTester’s email checker. It doesn’t just confirm whether the address is valid — it checks the full chain of DNS records, including SPF, DKIM, and DMARC. If your DKIM signature fails, the test will surface that immediately, even when the failure stems from subtle issues like CRLF vs LF line endings in the header, a known cause of canonicalization mismatches.

MailTester simulates real delivery by routing test messages through known mail providers and returns the raw headers as they were received. This lets you compare your outgoing headers against the server’s interpretation. A mismatch in line ending handling — for example, mixing CR+LF with just LF — can break DKIM validation even if your signature is mathematically correct. The RFC 5322 specification mandates CRLF for line endings in email headers, and most servers enforce this strictly.

Diagnose Errors with the In-App AI Assistant

If you’re working with raw logs, use MailTester’s in-app AI assistant to parse and explain the feedback. Paste the rejected DKIM validation message, and the assistant will identify the root cause — often a misaligned canonicalization due to line ending inconsistencies. It can also flag common configuration issues like incorrect DKIM selector placement or malformed public key records.

For larger campaigns, use the bulk verification tool to check every address in your list for valid authentication setup. This finds problem domains before you send, reducing bounces and protecting sender reputation. A single misconfigured header can hurt deliverability for an entire list.

By combining live testing with AI-driven diagnostics, you isolate and fix subtle issues like improper canonicalization. This ensures your emails pass scrutiny at every stage — from DNS to inbox. For teams using email platforms like SendGrid, HubSpot, or Klaviyo, MailTester’s integrations provide real-time feedback that keeps your sending system clean and compliant with standards like those defined in RFC 5322.

Final Checks Before Your Next Email Send

Before sending, confirm all email headers use CRLF line endings (carriage return + line feed). Any deviation—like LF-only or inconsistent endings—can break DKIM signature validation.

Verify DKIM-Signature Header Compliance

Recheck the DKIM-Signature header against RFC 6376. Ensure all values are properly formatted, line breaks are normalized, and no non-standard characters or padding interfere with canonicalization.

  • Test your email workflow end-to-end using MailTester’s bulk verification and inbox placement tools.
  • Include the raw email in your test to catch header-level issues before delivery.
  • Save logs from each test run—use them to verify fixes, monitor improvements, and reference during audits.

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 causes a DKIM canonicalization mismatch in email headers?

A mismatch occurs when header line endings (like LF or CR-only) deviate from the required CRLF standard before DKIM signing, causing the signature to fail validation.

Can line endings affect email delivery even if the message appears fine in clients?

Yes. Clients display email content correctly, but receiving servers validate DKIM using raw headers. Misaligned line endings break signature verification and lead to delivery failure.

How do I know if my DKIM setup has a canonicalization issue?

Check logs from receiving servers for 'dkim: bad signature' or 'canonicalization mismatch'. MailTester’s inbox placement test can also identify the exact header field causing the failure.

Do all email frameworks enforce CRLF line endings by default?

No. Many frameworks and libraries default to OS-specific line endings (LF on Unix, CRLF on Windows), requiring manual enforcement for compliance with RFC 6376.

Is DKIM affected only by line endings, or are other header formatting issues a risk?

Other issues—like extra spaces, reordered headers, or unescaped characters—can also break canonicalization. Full header formatting must be standardized.

Can MailTester fix DKIM issues automatically?

MailTester does not fix configurations but detects them. It provides clear feedback to help you identify and correct the root cause in your sending setup.

What is the difference between simple and relaxed DKIM canonicalization?

Simple canonicalization preserves all whitespace and line breaks exactly as sent. Relaxed mode normalizes line endings to CRLF, collapses multiple spaces, and ignores trailing whitespace.

How often should I test my DKIM configuration?

Test after any change to your sending stack, email templates, or authentication setup. Use MailTester’s API to run regular checks as part of your deployment pipeline.

Are line-ending issues common in modern email systems?

Yes, especially in custom SMTP senders, legacy systems, or poorly configured applications that don’t normalize CRLF before signing email headers.

Can a catch-all email address hide a DKIM canonicalization issue?

No. Catch-all addresses accept all emails but still validate authentication. A DKIM failure due to line endings will be rejected regardless of address type.

How can I test my email headers without sending to real users?

Use MailTester’s inbox placement test to send sample emails to real providers and receive full header analysis and delivery status without risking your list.

What happens if DKIM validation fails due to line-ending issues?

Receiving servers typically reject the email or mark it as low trust. This harms sender reputation and can lead to inbox filtering or permanent blocking.