Why DKIM Body Canonicalization Matters in HTML-Only Emails

You send an HTML-only email. Everything looks perfect in the preview. But the DKIM signature fails. You’re not sure why — no obvious changes to the content. The issue? Body canonicalization.

DKIM signs the body of an email using a specific transformation process. In HTML-only emails, where there’s no plain-text fallback, this process is not optional — it’s critical. Even a single space added or removed, a line break repositioned, or a tag reordered can cause the canonicalized body to differ from the signed version, breaking the signature.

When DKIM validation fails, even subtly, receiving servers treat it as a red flag. That impacts sender reputation. Over time, consistent failures lead to inbox filtering, lower deliverability, and fewer delivered messages.

Key takeaways

  • DKIM body canonicalization in HTML-only emails must preserve the exact byte sequence of the body after applying normalization rules, including whitespace and tag order.
  • Small differences in HTML formatting — like added spaces or reordered attributes — can invalidate DKIM signatures if not managed during canonicalization.
  • Failure to validate canonicalization correctly leads to signature mismatches, harming sender reputation and inbox placement, especially in strictly enforced inbound policies.

What Is DKIM Body Canonicalization? A Technical Reset

DKIM body canonicalization is the process of normalizing an email's body content before signing and verification, ensuring that minor formatting changes don’t invalidate the signature. For HTML-only emails, the entire body—including tags, attributes, and whitespace—must be processed under relaxed rules to maintain consistency across email clients and servers. This normalization is critical for deliverability, as mismatches can cause DKIM failures even with valid keys.

How Relaxed Canonicalization Works in Practice

Relaxed canonicalization (R) is the standard for human-readable content, including HTML emails. It normalizes whitespace: multiple spaces become one, line breaks are replaced with single spaces, and case variations in text are ignored. This means that a tag like <div style="color: red;">Hello becomes equivalent to <div style="COLOR: RED;">HELLO in the signed digest.

Because DKIM signs the body after normalization, any rendering or formatting change during transit—such as whitespace compression by a gateway or email client—must not affect the canonical form. Failure to follow relaxed rules leads to signature mismatches, even if the content is otherwise correct.

Why HTML-Only Emails Demand Extra Care

In HTML-only emails, the body consists entirely of structured markup. Every opening and closing tag, attribute spacing, and line break contributes to the body's final form. If a developer or sender uses inconsistent formatting—such as adding extra spaces between attributes or wrapping tags in unpredictable line breaks—relaxed canonicalization will normalize it. But if that normalization alters part of the content in a way that breaks the digest, DKIM will fail.

For example, an image tag like <img src="https://example.com/logo.png" alt="Company"/> must be normalized so that spaces and casing in attributes don’t affect the signature. This is not just a preference—it’s required by RFC 6376, which defines DKIM’s canonicalization rules [RFC 6376].

Let’s say you’re deploying a transactional email via a sender like SendGrid. If your templates use a mix of spaces, line breaks, and varying case, even subtle differences in how the system parses them pre-signing can invalidate the DKIM check. That’s why validating the output before sending matters.

Use MailTester’s inbox placement tester to simulate how your email is received, including DKIM evaluation, before sending to real users. You can also verify your domain’s DKIM configuration with MailTester’s email checker to ensure it’s properly set up and producing consistent results.

How HTML-Only Payloads Break DKIM Canonicalization in Practice

DKIM signatures in HTML-only emails often fail because even tiny changes—like a space after a closing tag, inconsistent line breaks, or altered indentation—can break canonicalization. Unlike text-based emails, HTML payloads are sensitive to formatting during signing and verification. If your MTA normalizes whitespace differently than the receiving server, the body hash won’t match, and DKIM validation fails.

Small changes, big consequences

Let’s say you sign an email with a closing tag like ``—no space after. But your MTA, or a third-party system, later adds a space: ` `—even a single space. That changes the body's canonical form. The receiving server recalculates the hash based on the received content. If it doesn’t match the one in the DKIM signature, the email fails. This is common in systems that pre-process or minify HTML before sending.

Many email systems pre-process HTML before signing—compressing whitespace, normalizing line breaks, or rewriting tags. But if these changes happen after the signature is created, the body hash diverges. The signed version now differs from the one delivered. DKIM checks the exact body as sent, not the original source. Even tools that claim to support relaxed canonicalization may not apply it consistently across all phases of processing.

Relaxed vs. simple canonicalization matters

DKIM defines two canonicalization methods: relaxed and simple. Relaxed allows minor whitespace adjustments, like turning multiple spaces into one. Simple does not. Most email clients and providers prefer relaxed canonicalization when validating, but it only works if the sender’s server applies the same rules during signing.

When the sender’s MTA applies relaxed rules but the receiver uses simple, mismatches happen. Conversely, if the sender applies simple but the receiver expects relaxed, it also fails. The key is consistency. You can’t assume the receiver will tolerate formatting differences just because it’s “only a space.”

According to the DKIM specification (RFC 6376), canonicalization must be applied identically by both signer and verifier. In practice, inconsistent implementations are common—especially in systems that don’t treat HTML payloads as fragile, format-sensitive content.

Even with valid SPF, DMARC, and a correct DKIM signature, a mismatched body hash from formatting breaks deliverability. If you're seeing inexplicable DKIM failures on HTML-only emails, check how whitespace and structure are handled between signing and delivery.

How to Validate DKIM Body Canonicalization in HTML-Only Payloads

You validate DKIM body canonicalization by extracting the raw email source, applying relaxed body canonicalization (normalizing whitespace, preserving tag order), then using a tool that replays the DKIM verification process to confirm the signed body matches the actual body after normalization. This ensures the signature isn’t broken by minor formatting differences that don’t affect rendering.

  1. Extract the raw email source from your MTA or sending platform. Make sure it includes both full headers and the complete HTML body—no truncation. The raw source must mirror what the mail server actually sent, including all embedded formatting and encoding.
  2. Apply relaxed body canonicalization to the HTML body. This means collapsing multiple spaces into one, normalizing line endings to LF, and preserving tag order without altering content or attributes. This mirrors how DKIM applies canonicalization before signing.
  3. Reconstruct the DKIM verification process using a trusted tool. Use one that replicates header and body canonicalization exactly as specified in RFC 6376. Tools like RFC 6376 define these rules precisely—ensure your validation follows them.
  4. Check the DKIM-Signature header for the b= value. This is the digest of the canonicalized body. Verify it matches the digest computed from the body after applying relaxed canonicalization—mismatches indicate tampering or incorrect rendering.
  5. Automate validation across large sends by integrating a real-time verification API or using inbox placement testing. This catches issues early, especially in dynamic or templated emails where small changes break signing consistency.

Why this matters in practice

Even minor differences in whitespace or tag order can break DKIM validation, even if the email displays correctly. This is common in HTML-only emails where inline styles or automated templating systems add hidden characters. If the signature doesn’t validate, the email may be flagged as spam or rejected outright.

What to watch for

Some platforms pre-process HTML before signing, which changes the body in ways not reflected in the original design. Others may use strict vs. relaxed canonicalization—confirm your sender uses the same method. Tools like MailTester’s real-time verification API can help automate this check across thousands of sends, surfacing errors before they hit the inbox.

Why Manual Testing Isn’t Enough for High-Volume Sends

You can’t reliably validate DKIM body canonicalization across thousands of HTML-only emails by hand. Small differences in line breaks, whitespace, or encoding between devices or ESPs alter the body content, which breaks DKIM signatures—even if the message looks fine to you. Without automated checks, these failures go undetected until you see delivery drops or spam complaints.

Human Review Misses What Matters

Even experienced engineers miss subtle issues when scanning headers or raw email bodies manually. A single misplaced space or inconsistent line ending in an HTML-only payload can trigger a canonicalization mismatch, invalidating the DKIM signature. You might copy-paste a message exactly as sent, but subtle variations in rendering engines or email client normalization routines still change how the body is processed before signing.

Let’s be clear: this isn’t about typos. It’s about how different systems treat whitespace and formatting during the signing process. The same message can pass DKIM on one ESP but fail on another, simply because of how each applies canonicalization rules. You can't catch this by eye.

Undetected Failures Cost You Deliverability

Without automated validation, signature failures remain invisible until you see a spike in bounces, low inbox placement, or sudden increases in spam complaints. Once that happens, you’re already in the red—troubleshooting after the damage is done. According to industry data from the Messaging, Malware, and Mobile Anti-Abuse Working Group (M3AAWG), signature validation failures are a leading cause of email rejection, especially in high-volume environments.

Especially when sending HTML-only emails—where the entire message content is in the body—canonicalization accuracy is non-negotiable. Even minor changes can break the signature. A single failed DKIM check can lead an ESP to treat your whole sending domain as suspicious, especially if it happens repeatedly.

Tools like MailTester’s inbox placement testing expose these issues early by simulating delivery across multiple inboxes. You get real feedback on whether your DKIM-signed HTML content will pass validation and land in the inbox, not the spam folder. This is where automation delivers real outcomes—proactive detection, not reactive cleanup.

Using MailTester’s Inbox Placement & Deliverability Tests to Catch Issues

You can validate DKIM body canonicalization in HTML-only email payloads by sending real test emails through Gmail, Outlook, and Apple Mail via MailTester’s inbox placement tests. These tests check whether the DKIM signature aligns with the server’s public key and confirms proper body canonicalization—critical for HTML-only emails where formatting changes can break validation. The results show exactly where signature mismatches occur, including body content modifications or improper line endings.

How the test works

  • MailTester sends a real email from your domain to real inboxes across major providers like Gmail, Outlook, and Apple Mail.
  • Each inbox performs a full DKIM verification using your domain’s published public key.
  • It checks if the body content, after applying the chosen canonicalization algorithm (relaxed or simple), matches the signed portion of the message.
  • HTML-only emails are especially vulnerable to misalignment because minor changes in line breaks or whitespace can invalidate the signature.
  • Results include a detailed breakdown of the header and body signatures, explicitly showing whether canonicalization was applied correctly.

What you’ll see in the report

  • Clear indicators if body canonicalization deviated from the signed version, such as extra spaces or reordered attributes in HTML.
  • Warnings when DKIM keys have expired or are misconfigured, even if the domain is otherwise valid.
  • Identification of body formatting issues like improper line endings in MIME bodies or encoded content that wasn’t preserved.
  • Real-time feedback on how your email was processed by each inbox, including whether it landed in the primary tab, spam, or trash.
  • Links to the inbox placement tester so you can run your own checks anytime.

Because DKIM validation relies entirely on cryptographic consistency, even a single changed byte in the body can cause a failure. RFC 6376 defines both relaxed and simple canonicalization—understanding which one your mail server uses is key. MailTester’s tests help you confirm that the body content, as delivered, exactly matches what was signed, even in complex HTML-only payloads.

Let’s say you're using a template processor that reorders attributes or compresses whitespace. Without real inbox testing, you won’t know until complaints start arriving. MailTester surfaces these issues before they affect your sender reputation.

Validating Canonicalization: The Real-World Test with a Live Email

Send a real HTML-only email via your ESP, fetch its raw source, then reconstruct the body using relaxed canonicalization—removing extra whitespace, normalizing line breaks, and keeping tags intact. Use a DKIM debugger to replay the signature verification against both the original and reconstructed bodies. If the result differs, your canonicalization logic is inconsistent and must be corrected. This test proves whether your signing process matches the recipient’s verification.

Run the Live Test Step by Step

  1. Send a clean HTML-only email from your ESP (SendGrid, Mailchimp, etc.) to a test address. Ensure no text/plain part exists—only HTML.
  2. Retrieve the raw email source using your ESP’s API or by downloading it from a webmail client (like Gmail). The raw source contains the full DKIM-Signature header, including the q=canonicalization and b= signature value.
  3. Extract the canonicalized body from the DKIM-Signature header’s b= value. Then, extract the actual body from the raw source. Reconstruct it using relaxed canonicalization: strip leading/trailing whitespace, normalize line endings to \n, collapse multiple spaces, but leave all HTML tags and attributes intact.
  4. Use a DKIM debugger to verify the signature. Tools like MxToolbox’s DKIM Checker or MailTester’s inbox placement tester accept raw email input and simulate how a receiving server would validate the signature using the specified canonicalization method.
  5. Compare the expected signature result from the original body with the result from your reconstructed body. If they don’t match, your signing or canonicalization process is inconsistent. This usually stems from mismatched whitespace handling, incorrect line break normalization, or inconsistent tag spacing.

Why This Matters in Practice

Even small deviations in whitespace or tag spacing can cause DKIM failures—even if the email looks identical to a human. This happens because the receiver applies the same canonicalization rules as the sender. If you sign with one rule set but the server uses another, the signature fails.

According to RFC 6376, the body canonicalization method must be applied consistently at both sign and verify time. A mismatch at any point breaks the chain of trust. This is why testing with live email and raw source is more reliable than theoretical models.

Most ESPs handle this transparently, but if you're building your own signing system or migrating to a new one, this test catches hidden bugs early. A signature that passes in one environment can fail in another due to subtle differences in how the body is normalized.

A consistent canonicalization process isn’t optional. It’s a core element of DKIM correctness. If your test fails, revisit the order in which you sanitize the HTML body before signing. Tools like MailTester’s API can help validate full email headers and bodies in real time before you send at scale.

How SPF, DKIM, and DMARC Interact During Validation

SPF checks if the sending IP is authorized, DKIM verifies that the email content hasn’t changed since signing, and DMARC uses both to enforce alignment and enforce policies. If DKIM fails due to incorrect body canonicalization—often from HTML formatting changes—the email fails DMARC alignment, even if SPF passes. This means no single mechanism can fix poor canonicalization: all three must be correctly configured and consistently validated. If DKIM fails frequently, DMARC reports from providers like Gmail or Outlook will show high failure rates, which signal sender reputation issues.

Why DKIM Signature Failures Break DMARC

Let’s say your email passes SPF but fails DKIM. That failure happens because the email body was altered during transit—like how whitespace or HTML tags were normalized—making the DKIM signature invalid. Even though the sender IP is allowed (SPF passes), DMARC requires both SPF and DKIM to align with the domain in the From header. If DKIM fails, DMARC enforcement kicks in, and the email may be rejected or quarantined. This is why a single misstep in body canonicalization can undermine the entire authentication stack.

Body canonicalization defines how the message body gets folded and normalized before signing. The default, “simple” type in DKIM strips whitespace between lines, while “relaxed” allows more flexibility. But if your email client or ESP changes the formatting—adding line breaks, reordering attributes, or encoding characters—the canonicalized body will differ from the signed version. This mismatch causes failure. The RFC 6376 specification covers this process in detail: RFC 6376 outlines how email bodies must be processed during DKIM signing.

DMARC reports from mailbox providers often show a spike in DKIM failures when body canonicalization is inconsistent. These reports don’t just say “DKIM failed”—they show how often. A high failure rate, even if SPF is clean, signals deeper issues in your email infrastructure. It’s not enough to just enable DMARC; you must ensure DKIM signs content exactly as it’s sent—and that includes preserving consistent formatting in HTML-only payloads.

Let’s say you’re sending a newsletter with embedded images and style tags. If your ESP or email service alters <br> tags, adds or removes spaces around <div> elements, or rewrites inline styles, that’s canonicalization drift. The DKIM signature won’t match, and DMARC will enforce a failure. You can test this by sending to a verified inbox placement tester to see how delivery behaves across providers.

When to Use MailTester’s API for Real-Time Verification

You should use MailTester’s real-time verification API during development and pre-send checks to catch DKIM body canonicalization issues before they trigger hard bounces or cause email rejection due to signature mismatches. This stops problems early—especially when sending HTML-only payloads where whitespace and tag ordering affect the canonical body. Let’s walk through exactly when and how.

Integrate API into Your Workflow

  • Use the MailTester API to validate email addresses and their DKIM compliance right before sending, especially in transactional or dynamic campaigns.
  • Test individual addresses or small batches during QA to confirm that the MTA processes your HTML payload the same way your signing tool does—ensuring body canonicalization matches expectations.
  • Run checks against your actual sending environment, including headers and body structure, to detect discrepancies between sender and receiver canonicalization rules.

Test Before You Send

  • Use the inbox placement simulator to emulate delivery and verify that DKIM signatures remain valid after canonicalization—this catches silent failures that bypass basic syntax checks.
  • Validate your canonical body against RFC 6376 (the DKIM standard), which specifies how whitespace and tag order affect the signature hash. Even small changes during delivery can invalidate it.
  • Combine API results with your existing MTA logs to trace where the canonicalization deviates—common issues include auto-wrapping of long lines or stripping of optional attributes in <table> tags.
DKIM relies on exact byte representation: if the body sent differs from what was signed, the signature fails. The only way to catch this pre-send is automated verification.

The best practice? Run the API on every new batch before sending. You’re not just checking validity—you're testing whether the message as delivered will pass cryptographic validation. For example, if your template adds new line breaks in a <div> during parsing, it alters the body. MailTester’s real-time checks reveal this before it hits the inbox.

Consider using MailTester’s single-check tool for quick validation during design or copy edits, and bulk verification for campaign prep. The API gives you precision where your toolchain can’t—specifically, catching the subtle mismatches that break DKIM.

Common Pitfalls in HTML-Only DKIM Setup

You assume your HTML preprocessor preserves canonicalization, but many don’t—especially when transforming or minifying content. You apply inline CSS without testing the final rendered body, leading to mismatches between signed content and delivered content. You rely on ESP tools alone, ignoring raw output discrepancies from custom templates. And you skip post-delivery validation, missing how clients like Gmail rewrite HTML and break signatures. These gaps cause DKIM failures even when everything seems correct.

Why Canonicalization Breaks in Practice

  • HTML preprocessors (like Handlebars, Pug, or templating engines) often alter whitespace, line breaks, or attribute ordering—directly violating DKIM’s canonicalization requirements.
  • Even if your renderer is "safe," embedded styles or inline CSS can shift content structure when a client rewrites the DOM—most notably Gmail, which enforces its own inline styles.
  • Never assume ESPs preserve your intended body structure; they often rewrite or strip content, especially in mobile views or when processing links and images.
  • Testing in a staging environment without validating the final, delivered payload is ineffective. The signed content must match exactly what the recipient sees.

How to Confirm Your Setup Works

  • After generating an email, inspect the raw, unrendered content—before any ESP or client intervention—to confirm it matches the body used in your DKIM signature.
  • Use real inbox placement testing to see if your DKIM checks pass when delivered via Gmail, Outlook, or other clients that apply transformations.
  • Apply inbox placement testing with actual recipient inboxes to verify end-to-end deliverability and signature validation, not just test email infrastructure.
  • Validate the output of any template system—especially when using dynamic or server-side rendering—by comparing signed and delivered bodies in hex or byte-by-byte form.
  • Test your DKIM signature with multiple tools: use email verification to validate the structure of the entire payload, including headers and body, before sending.
DKIM checks fail not because of poor keys, but because the signed body differs from the rendered one. Fix the flow, not the math.

Conclusion: Don’t Assume DKIM Works — Verify It

DKIM body canonicalization isn’t optional. It’s a required step in email authentication that directly impacts deliverability and inbox placement. Skipping verification means trusting that your signature will hold across all receiving systems—where it often does not.

HTML-only emails are especially vulnerable because even minor differences in whitespace, line breaks, or encoding can break the canonicalization process, invalidating your DKIM signature. Without real-world validation, these errors go undetected until messages fail in transit.

Use MailTester’s inbox placement testing and real-time API to validate DKIM body canonicalization across actual email environments. This catches failures before they impact your sender reputation or cause delivery loss.

Sources

Keep reading

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

Frequently asked questions

What happens if DKIM body canonicalization is wrong?

The DKIM signature fails verification, leading to delivery rejection or spam filtering, even if SPF passes. This damages sender reputation.

Can DKIM work with HTML-only emails?

Yes, but only if body canonicalization is applied correctly during signing. HTML-only emails require strict adherence to relaxed canonicalization rules.

How can I test DKIM alignment in my email?

Use tools like MailTester’s inbox placement tests or DKIM checkers that replay signature validation on real payloads and compare signed vs. received body.

Is relaxed body canonicalization mandatory?

Yes, for human-readable content like HTML emails. It’s the default and required by RFC 6376 for DKIM.

Do email clients affect DKIM signature validation?

Yes. Clients like Gmail or Outlook may modify HTML formatting during rendering. This alters the body and causes DKIM validation to fail unless canonicalization is preserved.

How do I fix a DKIM signature mismatch?

Review how your MTA or ESP applies body canonicalization. Use MailTester or a DKIM debugger to compare the signed body with the verified one and align processing logic.

What is the difference between simple and relaxed canonicalization?

Simple preserves all whitespace and formatting. Relaxed normalizes spaces and line breaks. Relaxed is used for readable content like HTML emails and is required for compliant DKIM.

Can I automate DKIM validation in bulk?

Yes. MailTester’s bulk verification API and inbox placement tests allow automated validation across thousands of addresses and emails with real-world delivery simulation.

Does MailTester check DKIM body canonicalization?

Yes. MailTester’s inbox placement tests analyze DKIM signatures and validate body canonicalization using real email delivery environments.

Why does my email pass SPF but fail DKIM?

SPF validates sender IP; DKIM validates content integrity. A DKIM failure — often due to improper body canonicalization — will cause delivery issues even if SPF is valid.