Message formats and rendering
Rendering multipart/alternative in a desktop email client
Desktop clients pick one part from multipart/alternative—usually the richest safe type. Broken boundaries and mismatched content create blank or misleading views.
What you need to know
A multipart/alternative message offers the same content in multiple formats—typically text/plain and text/html—and a desktop email client chooses one part to show. Most modern clients prefer HTML when it is present and considered safe; accessibility modes and “view plain text” switches force the text part instead.
If HTML and plain text disagree, users can see a different offer than the one you intended. Temporary inboxes matter here only when you are previewing inbound mail you control: Mailby’s Quick Inbox safe preview is one rendering surface; desktop clients are another. Test both when fidelity matters.
Desktop client context
“Desktop email client” includes Thunderbird, Apple Mail, Outlook desktop, and similar. They parse MIME trees defined across RFCs—start with RFC 2046 (rel="nofollow noopener") for media types and multipart semantics, and RFC 2045 (rel="nofollow noopener") for framing.
Boundaries:
- This is about rendering received mail, not about Mailby sending.
- Safe preview ≠ bit-identical to Outlook.
- Intentionally broken fixtures belong in lab accounts you own.
- Security: HTML parts can carry tracking and script-like patterns; clients sanitize differently.
Fixture walkthrough
Test date: 2026-09-24. Method: construct a minimal valid multipart/alternative and observe client choice; then break one boundary deliberately.
Minimal valid structure (conceptual)
Content-Type: multipart/alternative; boundary="BOUND"
--BOUND
Content-Type: text/plain; charset=utf-8
Order total: $42
Confirm: https://example.com/c/plain
--BOUND
Content-Type: text/html; charset=utf-8
<html><body><p>Order total: $42</p>
<p><a href="https://example.com/c/html">Confirm</a></p>
</body></html>
--BOUND--
Working path: Thunderbird-class client shows HTML confirm link. Switching to plain text shows the plain URL. Both amounts match.
Failure / limitation: HTML says $42 while plain text says $420 (divergent alternatives). Users on plain-text mode accept the wrong total. Multipart/alternative requires editorial discipline: parts must be true alternatives, not different documents.
Second failure: corrupted boundary string → client shows raw MIME or blank body. Users forward “broken emails” that are transport-valid but unreadable.
Mechanism and pitfalls
Clients generally:
- Parse the MIME tree.
- Collect
multipart/alternativesiblings. - Rank by preference (HTML > plain, unless restricted).
- Render through a sanitized engine (desktop WebView / Word HTML / custom).
Pitfalls:
- Order of parts: conventions place plain first, HTML last; do not rely on order alone—declare types correctly.
- Nested multiparts:
multipart/relatedfor CID images wrapping alternative—easy to mis-nest. - Charset mismatches: mojibake in one part only.
- Security vs fidelity: blocked remote images change layout; Mailby preview is intentionally cautious (security).
- Accessibility: screen-reader users may prefer plain; keep it complete.
| Raw part | Declared type | Observed rendering | Accessibility / security implication |
|---|---|---|---|
| Plain body complete | text/plain | Shown in text mode | Good fallback; must include full info |
| HTML with remote pixel | text/html | HTML view; pixel may load on desktop | Tracking / privacy |
| HTML only, empty plain | text/plain empty | Some clients look blank in text mode | A11y failure |
| Divergent totals | both | Depends on mode | Trust failure |
| Broken boundary | n/a | Raw source / empty | Support burden |
| script-like HTML | text/html | Stripped or blocked | Safer clients differ |
Worked example
Dev team ships receipts with beautiful HTML and a plain part that only says “Your receipt is ready.” Finance users on a locked-down desktop client force plain text. They cannot see line items. Support load spikes. Fix: generate plain text from the same template data as HTML—not a stub.
When validating inbound rendering for your product mail, send to:
- A desktop client you run daily
- A webmail
- A Quick Inbox preview for a quick sanitized look
Document differences; do not assume one equals all.
Alternatives and durable mailboxes
- Generate both parts from one model in code.
- Integration tests that parse MIME and assert text equality of critical fields.
- Mailby developer tooling for automated inbound capture—/developers.
- Durable mailboxes for long-term sample libraries; temporary for one-off fixtures (data retention).
Related: how it works, features.
Short answers
What causes multipart/alternative confusion on desktop?
Client picks one part; divergent or broken parts produce wrong or empty views.
What should I do first?
Validate plain and HTML contain the same critical facts; open both modes.
When is a permanent address safer?
Archiving production samples for months of regression—temporary retention will purge them.
What evidence changes the recommendation?
Your audience is known to force plain text (government, accessibility policies).
Sources, limitations
- RFC 2045 / 2046 (nofollow).
- Editorial fixtures 2026-09-24; client versions differ.
- Mailby preview is not a substitute for Outlook-specific HTML quirks.
Intentionally broken fixtures worth keeping
Keep a private corpus (durable mailbox or git, not a one-hour inbox):
- Valid alternative with matching facts.
- Divergent dollar amounts.
- HTML-only with empty plain.
- Truncated boundary.
- Wrong charset on HTML only.
- Nested related+alternative with missing CID image.
Open each in your target desktop clients quarterly. Product marketing HTML drifts; regressions return.
Safe rendering practices for receivers
- Prefer clients that block remote images by default until you trust the sender.
- Be suspicious when plain and HTML disagree on URLs or amounts.
- Use Mailby preview for a sanitized first look on messages sent to disposable addresses (inbox).
- Do not disable security features to “make the newsletter pretty.”
Sender-side checklist
- Generate plain from the same data model as HTML.
- Put absolute HTTPS URLs in both parts.
- Test with images blocked.
- Validate MIME with an automated parser in CI.
- Avoid depending on
<script>or exotic CSS in email HTML.
How this differs from a message-format hub
Hubs explain MIME categories. This article constructs multipart/alternative fixtures against desktop rendering, with a divergence failure and a part/type/rendering table.
Outlook desktop quirks (practical notes)
Outlook’s Word-based HTML engine historically mishandles margins, background images, and some CSS. Plain-text parts become the lifeline when HTML collapses into an unreadable brick. Ensure phone numbers, order IDs, and CTAs exist in plain text—not only as image-based HTML buttons.
Apple Mail and Thunderbird differences
Apple Mail may load remote images more aggressively depending on settings; Thunderbird is often stricter by default. Your “tracking-free” HTML may still phone home for one audience. Document expected settings for your users when privacy matters.
Round-tripping through forwards
Forwarding a multipart message can flatten alternatives into a single part or attach the original as message/rfc822. Desktop clients then show surprising interiors. If your support team forwards receipts internally, test that path too.
Building a minimal generator in tests
In automated tests, build MIME with a library rather than hand-concatenating boundaries. Hand-built fixtures drift and create false failures around whitespace. Keep one hand-built broken fixture on purpose; generate the valid corpus.
Accessibility, localization, and legal text in both parts
Legal footers, unsubscribe instructions, and total amounts must appear in the plain-text alternative—not only in HTML. Regulators and corporate accessibility policies may force plain-text viewing. If your unsubscribe URL exists only as a styled HTML button, plain-text users cannot opt out cleanly.
Localized mail should keep language consistent across parts. A common bug ships HTML in French and plain in English after a partial template translation. Desktop clients that prefer plain then look “untranslated,” generating support tickets that appear to be client bugs.
For right-to-left languages, verify both parts. Plain text directionality markers and HTML dir attributes solve different surfaces; test in the desktop clients your audience actually uses.
When using Mailby to preview inbound samples, remember sanitization may remove some HTML flourishes. Treat differences as expected. Validate legal-critical strings in the plain part via automated MIME parse in CI so you are not relying on any single preview surface.
Archive golden MIME files in git LFS or artifact storage with durable retention. Temporary inboxes will purge the very samples you need for quarterly client regression days—see data retention.
If you inherit a legacy template with only HTML, generate plain text with a deterministic converter in the mail builder and fail CI when plain is empty. Empty plain is a defect, not a style choice.
Security note on HTML parts in desktop clients
HTML alternatives historically hosted tracking pixels, remote CSS, and occasionally script-like constructs. Desktop clients sanitize differently. When you receive unexpected multipart mail in a temporary inbox, prefer plain-text view or Mailby’s safe preview before enabling remote content in Outlook or Apple Mail. Divergence between parts can also be a phishing technique—HTML looks like your bank; plain text shows a different host. Train yourself to toggle views on high-value messages. Durable vs temporary address does not change that habit; it only changes how long the sample remains available for study (data retention).
How Mailby preview fits the desktop story
Mailby Quick Inbox preview is optimized for safe reading of short-lived messages—OTP extraction, cautious HTML, tracker resistance. Desktop clients optimize for long-lived personal mail with different tradeoffs. When your question is “what did we actually send?” use MIME unit tests plus at least one desktop client. When your question is “can a disposable recipient read the code?”, use /inbox. Do not expect pixel-identical rendering across those jobs. The pitfall is assuming one surface certifies all surfaces. Document which surface is authoritative for each QA gate in your release checklist.
Checklist before shipping any customer email template
- Plain and HTML amounts/URLs match
- Plain is non-empty in every locale
- Desktop Outlook/Apple/Thunderbird spot-checked
- Images-blocked view still comprehensible
- MIME parsed in CI
- Golden files stored durably
- Disposable preview used only as secondary check via /inbox
Fail the release if critical boxes are unchecked. Templates are product surface area equal to UI screens—treat them accordingly. Multipart/alternative mistakes are silent: users do not always report “my plain text was wrong”; they just mistrust the brand.
Closing guidance for senders and receivers
Senders: generate matched alternatives, test desktop modes, archive golden MIME durably. Receivers: toggle plain/HTML on important messages, treat divergence as suspicious, use safe previews for disposable traffic. Multipart/alternative is simple until teams treat the HTML part as the only real message. Restore the contract—same meaning, multiple formats—and desktop clients stop surprising you. Use /inbox when a sanitized disposable preview helps, and keep long-term corpora off purge clocks per /data-retention.
Conclusion
Treat multipart/alternative as a contract: same meaning, multiple formats. Test desktop plain and HTML modes explicitly. Use Quick Inbox when a sanitized preview helps, and keep long-lived sample corpora in durable storage—not on a purge clock.
Try it on Mailby
Open a receive-only disposable inbox when a short-lived address fits the job — session-bound, with timed purge.