Why Does DKIM Canonicalization Matter for Multipart/signed Emails?

You’re sending a legally binding document as a multipart/signed email—PDF attachment, signed form, encrypted payload—only for the receiver to reject it. Not due to a broken key or spoofed sender. Because of a single trailing space in a header field. That’s what happens when DKIM canonicalization rules aren’t followed.

Even slight deviations in how the email body or headers are formatted—line endings, whitespace, header order—can break a DKIM signature, despite everything else being correct. Multipart/signed messages are especially sensitive, because each part is treated as a distinct section during canonicalization. A misstep here invalidates the entire signature.

Understanding the exact rules for canonicalization in multipart/signed content is not optional. It’s required to keep signed emails trusted and deliverable. This guide explains the real mechanics behind DKIM canonicalization for multipart/signed emails—what to do, what can go wrong, and how to avoid failure.

Key takeaways

  • DKIM canonicalization for multipart/signed emails requires consistent treatment of each part’s header and body, including line ending normalization (LF only) and header ordering.
  • Even minor changes—adding a trailing space, using CRLF vs LF, or reordering headers—can invalidate a DKIM signature despite the sender and domain being legitimate.
  • Receivers that strictly enforce RFC 6376 canonicalization rules will reject signed emails with inconsistent formatting, even if the content is correct.

What Are the Canonicalization Rules in DKIM for Multipart/Signed Content?

DKIM canonicalization normalizes headers and body content before signing to ensure consistency across different email implementations. For multipart/signed content, both header and body canonicalization must be applied uniformly across all parts, as defined in RFC 6376. This prevents signature mismatches when intermediaries rearrange or modify whitespace.

Header and Body Canonicalization Work Together

DKIM uses two separate canonicalization methods: one for headers (h) and one for the body (b). In multipart/signed messages, each part must be processed using the same rules. This means the same canonicalization algorithm must be applied consistently across every part, otherwise the signature will fail verification.

Let’s say you're sending an email with both text/plain and text/html parts. The DKIM signature covers both parts, so the signing agent must apply the same header and body rules to each. If one part uses relaxed canonicalization and another uses simple, the verifier will reject the signature—not because the content is wrong, but because the canonicalization didn’t match.

How Canonicalization Normalizes Data

Header canonicalization strips out extra whitespace and normalizes line breaks: all whitespace (spaces, tabs, newlines) in header lines is reduced to a single space. This means Subject: Test Email becomes Subject: Test Email. RFC 6376 specifies this behavior in detail.

Body canonicalization is stricter. It removes trailing whitespace from every line and collapses line breaks into a single space, effectively turning the entire body into a single continuous string. This ensures that minor formatting differences—like extra line breaks added by a mailer or forwarder—don’t break the signature.

For multipart/signed content, this means both the headers and the body of each part are processed identically. If one part has an extra newline, it must be removed during canonicalization in the same way as the others.

These rules are critical because email systems often modify content in transit—adding line breaks, reformatting, or reordering headers. Without consistent canonicalization, a valid signature could appear invalid after delivery. For example, adding a trailing space in a body line may not change how the message looks to a user, but it will invalidate the DKIM signature unless properly normalized.

As the original DKIM specification states, canonicalization ensures that signatures remain valid regardless of minor structural changes in the delivery path. Learn more about how email authentication works in practice from the IETF’s RFC 6376. If you're verifying DKIM signatures or sending high-value emails, consider using tools that validate canonicalization compliance before sending—like our inbox placement tester or bulk verification system to identify delivery risks early.

How Do Multipart/signed Emails Trigger Canonicalization Challenges?

When a multipart/signed email contains multiple parts—like HTML and plain-text versions—each part can have its own headers and body content. This creates inconsistencies in line endings, encoding, or header ordering. Since the DKIM signature applies to the entire message, every part must be canonicalized identically. If any part deviates due to inconsistent formatting, the signature fails during verification.

Why Consistency Matters Across Parts

DKIM requires that the exact same canonicalization rules be applied to every part of a signed message. Let’s say you send an email with both an HTML and plain-text body. The HTML part might use Unix line endings (LF), while the plain-text version uses Windows style (CRLF). If one part is normalized to LF but the other isn’t, the resulting digest will differ—causing the signature to fail, even if the content is otherwise correct.

This is governed by the DKIM specification in RFC 6376, which defines the canonicalization process as a strict, deterministic transformation applied to the entire message. You can't apply different rules to different parts; the outcome must be reproducible across all recipients and systems. Even minor variations—like case differences in header names or extra whitespace—can break the signature.

Even with proper alignment, some email clients or gateways apply their own canonicalization tweaks during transit, which can cause otherwise valid signatures to fail. This is especially common with older or poorly configured mail servers. The Spamhaus Domain List and similar filtering systems often reject messages with mismatched or invalid DKIM signatures, regardless of content quality.

How to Prevent Signature Failures in Multipart Messages

Let’s keep it simple: ensure all parts of your multipart message follow the same formatting standards from the start. Use consistent line endings (preferably CRLF for compatibility), normalize header names to lowercase, and strip trailing whitespace. Use the same character encoding (usually UTF-8) across all parts.

For developers, testing DKIM signatures with tools like inbox placement testing helps verify that your signed messages pass validation across real-world receiving environments. You're not just validating syntax—you're testing whether your message lands in the inbox, not the spam folder.

DKIM Canonicalization: Header vs Body in Practice

DKIM canonicalization standardizes how headers and body content are processed before signing: headers are normalized (whitespace stripped, lines folded, duplicates collapsed), while the body is stripped of trailing whitespace, collapses internal spaces, and preserves line breaks — all across the full multipart/signed message body in sequence. This exact process is defined in RFC 6376 and enforced by mail servers during signature verification.

Header vs Body Processing: The Rules

When a message is signed with DKIM, the canonicalization rules differ sharply between headers and body. Headers must be normalized to ensure consistency across implementations, while the body applies stricter whitespace handling to preserve the integrity of content. For multipart/signed messages, the canonicalized form includes all parts concatenated in the correct order, as defined in the message structure.

Canonicalization Type Header Processing Body Processing
Whitespace Strips leading and trailing spaces; reduces multiple spaces to one. Removes all trailing whitespace; collapses multiple internal spaces to one.
Line Folding Normalizes line breaks to CR LF (CRLF); applies folding if needed. Preserves line breaks in content; no line folding applied to the signed body.
Duplicate Headers Keeps only the first occurrence of any header. N/A (applies to headers only).
Body Context N/A. Applies to the full message body of all parts in order, with no alteration of structure or MIME boundaries.

These rules ensure that the signature is reproducible across different implementations. The DKIM Specification (RFC 6376) defines both header and body algorithms, and email servers apply them during verification. Any deviation in canonicalization leads to signature validation failure.

For multipart/signed messages, the body canonicalization applies to the entire content stream — including all parts joined in order — as a single, coherent unit. This means that even if one part is reformatted, the entire body's signature must account for it. This is why tools like bulk email verification or real-time API checks should be validated using a full message simulation to catch canonicalization mismatches early.

How to Verify That Your Multipart/signed Email Is Properly Canonicalized

You must validate DKIM signature alignment for multipart/signed emails by testing raw output for line break consistency, header duplication, and whitespace encoding, using tools that simulate delivery and check signature validity across multiple parts. This is critical because improper canonicalization breaks signatures even with correct keys and can prevent deliverability.

Validate Signature Alignment With Real-World Testing

  • Use an inbox-placement service like MailTester’s inbox tester that validates both the DKIM signature and canonicalization compliance in a live-like environment, not just in isolation.
  • Test your email using real SMTP delivery simulation—don’t rely solely on header-only checkers, as they can miss edge cases in the body or MIME structure.
  • Check for inconsistent line breaks (CRLF vs LF) in both headers and body; DKIM canonicalization requires strict adherence to RFC 6376, which defines line-ending normalization.
  • Ensure no header fields are duplicated or altered during signing—each header entry must appear only once in the canonicalized form, per the signed headers list.

Inspect Raw Email Output for Hidden Issues

  • Download the raw email (from a debug tool or mailbox) and verify that all content lines are properly folded using CRLF and that no unencoded whitespace breaks the canonicalization rules.
  • Confirm that any encoded whitespace (such as soft line breaks in a quoted-printable body) is retained in the canonicalized body and not stripped.
  • Use a tool like RFC 6376 to cross-check your canonicalization logic against official rules for both header and body.
  • Check multipart messages with multiple signed parts for consistent alignment—each part must be processed independently, and the canonicalization must not merge or distort boundary delimiters.
  • Use the email checker on individual addresses to catch issues early, especially when testing high-volume sends.
Even slight deviations in line ending or whitespace handling during canonicalization can invalidate a DKIM signature, regardless of key correctness—proof that alignment matters as much as key strength.

Integrate Verification Into Your Workflow

  • Run bulk list verification via the bulk verification tool before sending, to clean invalid or malformed addresses before signing.
  • Integrate the verification API into your sending pipeline to automatically validate addresses and signature readiness at scale.
  • Review canonicalization logs from your MTA or ESP for any warnings related to DKIM signature failure—these often point to formatting issues in body or header normalization.
  • Verify that all signed headers are correctly listed in the h= tag and that no unintended headers (like Received or Authentication-Results) are included.

Step-by-Step: Debugging DKIM Signature Failures in Mult-part Emails

You’re missing an email delivery step? Let’s debug: pull the raw source, apply RFC 6376 canonicalization exactly to headers and body, extract the DKIM-Signature, verify using the DNS public key, and compare the hashed values. If they don’t match, your canonicalization was inconsistent—check for whitespace, line endings, or malformed MIME parts. Use real tools to check your sender setup without guesswork.

  1. Retrieve the raw email source from your mail server logs or the sender’s server. The original, unaltered MIME structure is your only reliable reference. Even minor changes during transit or storage can break the signature.
  2. Apply the exact canonicalization rules from RFC 6376, Section 3.4 to both the headers and body. For multipart/signed content, this means normalizing line endings to CRLF and folding long header lines with soft line breaks—not hard ones.
  3. Extract the DKIM-Signature header field. Pay attention to all fields: h=, b=, d=, s=, and a=. These define how the signature was created and what key to use.
  4. Fetch the public key from DNS using the domain and selector in the signature. Validate the signature using standard cryptographic libraries or tools like DKIMCore—don’t rely on ad-hoc scripts.
  5. Compare the computed body hash with the one in the b= field. If they disagree, the failure lies in canonicalization—either in headers or body. Double-check for extra spaces, inconsistent line endings, or missing newlines before closing boundary markers.

Check Each Part for Proper MIME Formatting

Multipart emails often fail silently due to malformed MIME. Look for:

  • Extra spaces or tabs before or after line breaks in body parts.
  • Lines that aren’t properly folded or split at 78 characters.
  • Missing or incorrect Content-Type headers in each part.
  • Incorrect boundary markers—ensure they match and aren’t reused.

Validate Your Setup in Real Time

Even if your email sends, it may not pass inbox filtering. Use inbox placement testing to see how your messages land in real mail clients. This shows the end result of all your signing and formatting work—not just internal checks.

Common Causes of DKIM Failure in Multipart/signed Messages

You can't sign a multipart/signed email reliably if the body or headers aren’t canonicalized consistently. DKIM depends on a fixed, reproducible message format. Even small changes—like switching from LF to CRLF line endings, adding extra whitespace, or using non-standard MIME encoders—break the signature because the hash no longer matches the original. This leads to failures during validation, even if the email content is otherwise correct. The key is ensuring that every part of the message, especially in multipart/signed content, follows the same processing rules from start to finish.

Line Endings and Whitespace Break Signatures

DKIM canonicalization uses strict rules for line endings: only CRLF (carriage return + line feed) is acceptable in the body. If your message processor or library converts LF to CRLF during transport, or vice versa, the hash will differ from the original. Even a single missing or extra space in the body or header fields breaks the signature. It’s not about readability—it’s about bit-for-bit consistency. You can test this by using a raw message analyzer like those from RFC 6376 to verify your signing process aligns with expectations.

MIME Encoder Behavior and Inconsistent Processing

Not all MIME encoders treat multipart/signed messages the same. Some libraries preserve whitespace or encoding details in ways that aren’t compatible with DKIM’s canonicalization model. For instance, if one part of the message uses quoted-printable encoding and another uses base64, but they’re processed with different rules mid-flight, the final structure diverges from the signed version. This inconsistency is a frequent cause of failure. The safest route is to use well-documented, widely adopted libraries—like Python’s email module or Node.js’s nodemailer—and test signing output against known good reference messages.

Digital signatures require predictability. Even a single character change—like a whitespace tweak or improper line ending—invalidates a DKIM signature. Tools like MailTester's email checker can verify whether the underlying address or domain has strong sending practices, including correct DNS and header alignment. While not a DKIM signature tester per se, it helps catch foundational issues early. For deeper validation of message structure, ensure your signing process follows RFC 6376’s canonicalization rules strictly and test with a known good message body before sending at scale.

How MailTester Helps Validate DKIM and Canonicalization in Practice

You can test how DKIM signatures hold up in real delivery conditions by simulating inbox placement with MailTester. Its inbox-testing feature sends your email through actual mail servers, validating DKIM signatures and checking whether canonicalization rules are applied correctly across all parts of multipart/signed messages. This includes spotting mismatches in header formatting, body hashing, or signature alignment that break signature verification.

Testing Real-World DKIM Behavior

DKIM isn't just about signing — it's about matching the exact content as it's received. MailTester’s inbox-placement testing mimics how real email providers like Gmail or Outlook process messages. This includes running DKIM checks on each part of a multipart/signed message, ensuring that body and header canonicalization are applied consistently, even when multiple parts are involved.

For example, if your email contains both HTML and plain-text content, MailTester verifies that the canonicalization rules applied during signing match what the receiving server expects. Misaligned body canonicalization — where the body is reformatting in transit — will cause DKIM to fail. You don’t need to guess; the test shows exactly where the signature breaks.

API and Bulk Verification Catch Subtle Issues

Use MailTester’s real-time verification API or bulk verification to catch malformed DKIM headers, incorrect header order, or body formatting problems before sending. These tools analyze not just whether a signature exists, but whether the canonicalization process can succeed during delivery. They flag anomalies like missing or mismatched h= fields, improperly normalized line breaks, or signature mismatches between expected and actual body hashes.

Proper DKIM canonicalization is defined in RFC 6376 (see RFC 6376) and requires strict handling of whitespace, line endings, and header ordering. MailTester enforces these rules by validating each part of a multipart message, especially when signed with multipart/signed. This prevents silent failures when your email reaches a recipient’s inbox but gets rejected due to a broken signature.

Let’s say you send a campaign with embedded images or PDFs. MailTester checks if the signature aligns with the canonicalized version of each part — not just the whole message. If you're using tools like the real-time API or bulk verification, this layer of validation happens at scale without any extra work.

Best Practices to Ensure DKIM Canonicalization Success

Use RFC 6376-compliant libraries, never build email bodies by hand, test multipart/signed content in staging, and ensure header and line ending consistency. These steps prevent canonicalization failures that break DKIM signatures and lead to rejected or flagged emails. Let’s walk through what works in practice.

Build with Trusted Libraries

  • Use established email libraries like Python’s email.mime or Java’s MimeMessage — they implement RFC 6376’s canonicalization rules correctly.
  • Manual construction of raw email bodies often introduces line ending inconsistencies or malformed headers, which trigger DKIM signature rejection during verification.
  • Always validate that your chosen library processes both multipart/signed content and headers according to the standard’s "relaxed" and "simple" canonicalization methods.

Test Rigorously Before Deployment

  • Test all multipart/signed emails in a staging environment using real email verification tools — never assume correctness based on code alone.
  • Confirm DKIM signatures are intact after transport by validating the full email trace with tools like RFC 6376 or trusted email inspectors.
  • Use MailTester’s email checker to verify that the recipient address and related metadata (including DKIM-signature alignment) are clean before sending to production.

Duplicate testing across systems is non-negotiable. Even small inconsistencies in whitespace, header ordering, or CRLF handling can cause DKIM failures. Ensure all email templates — especially those used in bulk campaigns — follow strict formatting rules.

Line endings must be consistent: always CRLF (Carriage Return + Line Feed), never just LF or CR. Header formatting should also be uniform: each header starts on a new line, and values must not have trailing spaces or extra newlines.

Finally, consider your delivery pipeline. If multiple systems process the same email (e.g. a template engine, a transactional service, a bulk sender), ensure each step preserves the canonical form. Even a minor transformation — like text wrapping or encoding change — can break the signature verification.

When in doubt, use a tool like MailTester’s inbox tester to simulate real-world delivery and check how your DKIM-signed message performs in actual inboxes across providers.

Conclusion: Canonicalization Is Not Optional for DKIM Validity

Even with correctly configured SPF and DMARC, a single flaw in DKIM canonicalization can invalidate a signature and result in delivery rejection.

Multipart/signed messages demand strict handling of line endings, whitespace, and header normalization—deviations break the cryptographic chain.

Verification tools that only check syntax miss real-world failures. Only those simulating actual mail server processing can reveal issues that harm sender reputation.

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 canonicalization is inconsistent in a multipart/signed email?

The DKIM signature will fail verification, leading to rejection or classification as spam, even if the email content is legitimate.

Can a multipart/signed email have multiple DKIM signatures?

Yes, but each signature must be correctly canonicalized on its own. Multiple signatures do not override the need for proper canonicalization.

Which RFC defines DKIM canonicalization rules?

RFC 6376, Section 3.5, defines the header and body canonicalization processes for DKIM signatures.

Do all email clients validate DKIM signatures?

Most major providers like Gmail, Outlook, and Yahoo validate DKIM signatures during delivery, but only if the canonicalization matches.

How can I test DKIM canonicalization without sending emails?

Use tools like MailTester’s inbox-placement test or raw email simulators to analyze the canonicalization step without sending.

Is body canonicalization applied to all parts of a multipart email?

Yes—body canonicalization applies to the entire email body, including all parts in a multipart message, as a single continuous stream.

What’s the difference between Header and Body canonicalization in DKIM?

Header canonicalization normalizes whitespace and duplicate headers; body canonicalization removes trailing whitespace and collapses multi-space sequences.

Does using a mailer service like SendGrid affect DKIM canonicalization?

Yes—some services apply their own formatting during delivery. Use tools that verify the final message post-transport.

Can mail merge tools break DKIM canonicalization?

Yes—some merge engines insert inconsistent line endings or alter whitespace. Test final output before sending to ensure consistency.

Is 98.9% accuracy in email verification linked to DKIM validation?

MailTester’s 98.9% accuracy includes detecting invalid mail servers, catch-all domains, and malformed headers, but not DKIM alignment itself.

Can you fix a failed DKIM signature after sending?

No—DKIM signatures are validated at delivery. Failed signatures cannot be corrected after the fact; they must be fixed before sending.

What is the role of the 'b=' tag in DKIM signatures?

The 'b=' tag contains the base64-encoded hash of the body content after canonicalization. It must match the computed hash of the actual body.