Why is MIME encoding headers in emails invalid and what are the consequences?
Published 20 Apr 2025
Updated 11 Oct 2026
11 min read
Summarize with
Updated on 11 Oct 2026: We clarified MIME header encoding rules, added RFC 2231 filename examples, and corrected the guidance on unsubscribe and DKIM failures.
MIME header encoding is valid for human-readable text where the field grammar allows it. RFC 2047 encoded-words are invalid when they replace machine-readable syntax in structured email headers. A field like List-Unsubscribe is not free text. It contains angle-bracketed URLs, mailto addresses, commas, and folding positions that parsers need to read exactly. Encoded-words such as =?us-ascii?Q?...?= belong only in specific human-readable parts of certain fields, such as Subject text or a display name.
The receiving system parses a structured header according to its grammar before decoding display text. It can ignore an invalid field or fail to recognize one-click unsubscribe; delivery handling also varies across Gmail, Yahoo, Microsoft, and filtering gateways. The defect can originate in the sending platform, its email library, or a relay that rewrites headers.
Short answer
If a platform emits List-Unsubscribe, DKIM-Signature, Content-Type, Message-ID, or address syntax as MIME encoded-words, ask the platform to serialize each field according to its grammar. Tolerant receivers do not make the output valid, and a parser change can turn a warning into a delivery or compliance problem.
Invalid MIME encoding versus valid header folding
The invalid part is not header folding. Folding uses CRLF followed by a space or tab, with breaks only where the field grammar allows them. The invalid part is replacing the structured value with encoded-word chunks. A parser looking for a URL inside angle brackets sees an encoded-word instead of the required structure.
Invalid List-Unsubscribe headertext
List-Unsubscribe: =?us-ascii?Q?=3Chttps=3A=2F=2Fexample=2Eorg=2Funsub=3Fid=3Dabc?= =?us-ascii?Q?=3E=2C_=3Cmailto=3Aunsubscribe=40example=2Eorg=3E?=
The corrected version keeps the syntax visible to a structured header parser. Long lines can still be folded at a permitted boundary, but the field value remains a normal List-Unsubscribe value.
Valid folded List-Unsubscribe headertext
List-Unsubscribe: <https://example.org/unsub?id=abc>, <mailto:unsubscribe@example.org>
The 78-character line recommendation in RFC 5322 is not an instruction to MIME-encode any header that grows longer. Fold at grammar-allowed whitespace, such as between comma-separated List-Unsubscribe URLs, and do not split a URL. Keep every line within the 998-character hard limit, excluding CRLF. An RFC 2047 encoded-word has its own 75-character limit.
- Allowed: Use encoded-words for non-ASCII human text where the field grammar permits them, such as Subject text or a personal display name.
- Invalid: Do not MIME-encode angle brackets, URLs, email addresses, commas, message IDs, DKIM data, MIME boundaries, or other structured tokens.
- Fix: Serialize each header according to its own grammar, then encode only the exact human-readable phrase that is allowed to be encoded.
Why encoded-words do not belong there
MIME (Multipurpose Internet Mail Extensions) lets messages carry non-ASCII text and attachments. RFC 2045 defines the MIME headers used to describe message bodies; RFC 2047 defines encoded-words for header text. Encoded-words are not a general escaping or line-wrapping mechanism.
The important distinction is between human-readable text and protocol syntax. A display name is text. A Subject line is text. A URL inside List-Unsubscribe is syntax. The local part and domain in an address are syntax. A DKIM-Signature header is syntax. Those structured parts must remain visible to the parser.
This is also why RFC 2047 address encoding has to be handled carefully. Encoding the display name in From can be valid. Encoding the address itself as an encoded-word is not.
|
|
|
|---|---|---|
Subject | Encoded text | Malformed word or fold |
From | Display-name phrase | Address syntax |
List-Unsubscribe | Visible URL syntax | Encoded URL |
DKIM-Signature | Raw tag values | Encoded chunks |
Content-Type | Defined parameter syntax, including RFC 2231 | Encoded-word parameter |
Common header encoding outcomes
Flowchart showing when RFC 2047 encoded-words are valid in email headers.
RFC 2047 rules that matter
RFC 2047 limits encoded-words by both location and length. They can carry non-ASCII text in an unstructured field such as Subject and within a phrase or comment where the field grammar permits it. They cannot appear in an addr-spec, a Received field, a quoted string, a MIME Content-Type or Content-Disposition parameter, or another structured field body outside an allowed phrase or comment. See RFC 2047 for the permitted locations.
Each encoded-word, including its delimiters, character set, encoding marker, and encoded text, is limited to 75 printable characters. RFC 2047 also limits each header line containing encoded-words to 76 characters, excluding CRLF. Longer human-readable text can use multiple self-contained encoded-words separated at legal whitespace, without splitting a character or encoded byte sequence. Q-encoding uses a quoted-printable-like format; B-encoding uses base64. Neither permits encoded-words inside structured tokens.
Valid encoded Subject and From display nametext
Subject: =?UTF-8?Q?Caf=C3=A9_updates?= From: =?UTF-8?Q?Jos=C3=A9?= <jose@example.org>
SMTPUTF8 is a separate mechanism. RFC 6531 and RFC 6532 permit direct UTF-8 in supported envelope addresses and header field values when SMTP transport negotiates SMTPUTF8. RFC 6532 replaced the experimental RFC 5335 specification and counts the 998 line-length limit in octets rather than Unicode characters. SMTPUTF8 does not make an RFC 2047 encoded-word legal inside a structured token.
Check the encoding layer
- Header display text: Use RFC 2047 encoded-words only where the field grammar permits text, phrases, or comments.
- Structured field: Keep addresses, URLs, identifiers, signature tags, and MIME parameters in their defined syntax.
- Message body: Set the charset parameter in Content-Type for text body parts and use Content-Transfer-Encoding, such as base64 or quoted-printable, for body content. Header Q-encoding has different rules from body quoted-printable.
- Internationalized address: Use SMTPUTF8 only when the transport path supports it, not as a repair for malformed RFC 2047 output.
How to encode attachment filenames correctly
Content-Disposition filename parameters need their own encoding. Use RFC 2231 extended parameters for non-ASCII attachment names instead of placing RFC 2047 encoded-words inside quoted strings.
Invalid encoded-word and valid RFC 2231 filenametext
Invalid: Content-Disposition: attachment; filename="=?UTF-8?Q?caf=C3=A9.pdf?=" Valid: Content-Disposition: attachment; filename*=UTF-8''caf%C3%A9.pdf
The valid example names the attachment "café.pdf". The asterisk in filename* identifies an extended parameter, UTF-8 declares the charset, and the two apostrophes leave the language value empty. Percent escapes encode the UTF-8 bytes. Long values use numbered continuations such as filename*0* and filename*1*, starting at zero without gaps. This parameter syntax does not apply to List-Unsubscribe URLs or email address syntax.
Consequences for unsubscribe and email deliverability
A practical consequence is that receivers do not recognize the header for its intended purpose. With List-Unsubscribe, an encoded URL can make the mailbox ignore the field. RFC 8058 one-click unsubscribe requires one List-Unsubscribe field containing one HTTPS URI, List-Unsubscribe-Post with the exact value List-Unsubscribe=One-Click, and a valid DKIM signature covering both fields in its h= list. If the URI is hidden inside encoded-words, the setup no longer parses as required. The HTTPS endpoint must also accept the unsubscribe POST without a login, confirmation page, or redirect.
The message can still be delivered, which makes the bug easy to dismiss, but the unsubscribe control can disappear and the sender can miss a provider requirement. Receiver behavior is also inconsistent. One provider can decode and accept the field, another can ignore it, and a gateway can make a different decision.
An invalid List-Unsubscribe header does not directly change SPF's sending-IP and envelope-domain checks. It can coexist with passing DKIM and DMARC results. A malformed DKIM-Signature or From field needs separate authentication investigation; a passing authentication result does not validate every header's grammar.
Tolerant receiver
- Decode first: The receiver decodes encoded-words before it tries to parse the structured value.
- Delivery continues: The receiver accepts the message, so the sender assumes the header is fine. Acceptance does not guarantee inbox placement.
- Risk remains: The behavior is tolerance, not a standards guarantee.
Strict receiver
- Parse first: The receiver expects visible structured syntax in the field value.
- Header ignored: The field fails to match the grammar and loses its intended effect.
- Sender impact: The malformed message becomes an operational delivery or compliance issue.
|
|
|
|---|---|---|
Unsubscribe | Header ignored | Requirement missed |
Filtering | Receiver detects malformed syntax | Handling depends on receiver policy |
DKIM | Invalid List-Unsubscribe can coexist with a DKIM pass | False confidence |
Debugging | UI decodes value | Invalid source hidden |
Possible effects of structured header encoding
How to diagnose invalid MIME headers
Inspect the raw message source rather than relying on a rendered inbox view. Webmail interfaces can display a decoded version that hides the invalid wire format. Compare the received header with the sender's source before submission and, where available, the relay's output to locate the component that changed it.
Read a bounce's diagnostic text before attributing the failure to MIME encoding. A missing From header is a separate message-format error; check the sender template for a valid mailbox and confirm that Date is present. A generic MIME-format notice in a returned message does not establish the rejection cause. A missing inbox unsubscribe button alone also does not prove a malformed header, because Gmail's eligibility checks determine whether the control appears.
A practical test is to send the same campaign or transactional message to a controlled inbox and inspect the raw headers. Suped's email tester supports this workflow by checking a real message's header, authentication, and content signals together.
- Raw source: Capture the full message source before any mailbox UI decodes or rewrites display values.
- Header parse: Inspect the entire field body for encoded-words where visible structured syntax is required, including after a fold.
- Receiver result: Record the exact SMTP rejection code and text, and check whether unsubscribe or delivery behavior changes across providers.
- Vendor ticket: Attach the malformed header, the corrected header, and the business risk in one concise request.
Email tester
Send a real email to this address. Suped shows a results button when the test is ready.
?/43tests passed
Check the sending domain alongside the message sample. Suped's domain health checker helps separate a header-format bug from broader SPF, DKIM, DMARC, DNS, and reputation problems.
Evidence package
- Original source: Include the full raw header block, not a screenshot of a decoded inbox view.
- Correct sample: Show the same List-Unsubscribe value as normal structured ASCII syntax.
- Receiver notes: Record whether the unsubscribe UI, bounce result, or filtering warning changes.
- Priority: Escalate immediately if the bug affects one-click unsubscribe, authentication, or bulk sender compliance.
What to ask the sending platform to change
The fix is usually in the platform's header serializer. The platform should stop running a generic encoded-word function over every header and instead serialize each field according to that field's grammar. This is not a DNS fix, and changing the DMARC policy does not repair it.
For platform owners, field-specific serialization tests catch this defect. A test should fail if List-Unsubscribe contains encoded-word syntax, if List-Unsubscribe-Post differs from its exact RFC 8058 value, if a Message-ID is encoded, if Content-Type or Content-Disposition parameters contain encoded-words, or if the address part of From is encoded. For broader message-format triage, use a repeatable process for RFC compliance errors so fixes do not depend on one mailbox provider's current tolerance.
Serializer requirements for structured headerstext
Do not apply RFC 2047 encoded-words to structured tokens. Preserve URLs, mailto addresses, commas, semicolons, and brackets. Keep List-Unsubscribe-Post as List-Unsubscribe=One-Click. Fold long lines only at grammar-allowed whitespace positions. Use RFC 2231 for non-ASCII MIME parameter values. Encode human-readable text only where the field grammar allows it. Finish serialization before DKIM signing. Run tests against the raw source, not the rendered mailbox view.
- Stop blanket encoding: A universal header-encoding step creates invalid output for structured fields.
- Keep tokens raw: URLs, addresses, message IDs, MIME parameters, and DKIM fields must remain parseable.
- Sign last: Apply DKIM after the final header form is built, then avoid later header rewriting.
- Regression test: Test long unsubscribe URLs, folded headers, display names, non-ASCII subject lines, and RFC 2231 filenames separately.
Using Suped to investigate header and authentication issues
Suped's product supports this investigation with raw-message testing and DMARC reporting. Compare the malformed message with its SPF and DKIM results, then send the evidence to the platform that generates or rewrites the header. The serializer fix belongs in that sending software.
Email tester sample report showing total score, email preview, issue summary, and per-section results
Suped's DMARC monitoring groups aggregate authentication reports by sending source, so a team can check whether the same source has SPF or DKIM failures. Aggregate DMARC reports do not include the full raw MIME header block or prove whether the unsubscribe header parses; keep the message sample with the vendor ticket.
Practical Suped workflow
- Test message: Send the real email and inspect the raw header output.
- Check auth: Confirm SPF, DKIM, and DMARC results around the same send.
- Watch trends: Use DMARC reports and alerts to identify authentication failures by sending source, then compare them with separate delivery logs.
- Escalate cleanly: Give the vendor a reproducible example and a corrected header.
How urgently to fix invalid headers
Schedule a serializer fix even when delivery appears normal. Escalate immediately when the affected field controls authentication, routing, or required unsubscribe behavior. Message volume alone does not determine urgency. The affected fields control automated handling by mailbox providers and filters.
- Minimum action: Collect raw source and ask the platform to stop encoding structured headers.
- Urgent action: Escalate immediately when the affected header controls unsubscribe, authentication, or routing.
- Long-term action: Add raw-message regression tests so the same bug does not return later.
