Message formats and rendering
Rendering multipart/alternative in webmail: pitfalls
Webmail usually prefers the HTML part of multipart/alternative—validate both parts, avoid contradictory content, and preview safely before trusting links.
A webmail client rendering multipart/alternative will typically show the richest safe part—usually HTML—while still storing the plain-text alternative. Your job as a sender or debugger is to keep both parts truthful, watch for clients that prefer text, and never assume every recipient saw the same buttons. Mailby’s Quick Inbox safe preview is a useful receive-side check for messages you expect users to get.
This article builds minimal fixtures (valid and intentionally broken), notes boundaries, and lists security/accessibility implications.
Webmail context and boundaries
MIME (multipart/alternative) lets a sender include mutually alternative body representations. Per RFC 2046, clients should choose the last alternative they are capable of displaying—commonly HTML last.
Boundaries:
- We discuss received message behavior, not how to spam.
- Mailby preview sanitizes dangerous HTML; it is not identical to Gmail/Outlook rendering.
- Receive-only: you cannot “resend corrected MIME” from Mailby.
- Developer parsing APIs at /developers help automated tests assert on parts.
Fixtures and observed behavior
Fixture A — healthy alternative
Content-Type: multipart/alternative; boundary=b1
--b1
Content-Type: text/plain; charset=utf-8
Your code is 482193
--b1
Content-Type: text/html; charset=utf-8
<html><body><p>Your code is <strong>482193</strong></p></body></html>
--b1--
Working path: Webmail shows HTML with bold code; text part remains for accessibility and non-HTML clients. Mailby preview extracts the code from either part.
Fixture B — contradictory parts (failure)
text/plain: Your code is 111111
text/html: Your code is 222222
Failure: Users on HTML clients enter 222222; a text-only client or asymmetric security scanner may see 111111. Support tickets multiply. Limitation: some gateways “fix” HTML and accidentally desync parts.
Fixture C — HTML-only advertised as alternative
Missing text part hurts accessibility and some filters. Prefer always including a coherent text body.
Mechanism and pitfalls
- Part order matters. Place plain text first, HTML last, unless you know your audience’s clients.
- Inline CSS / remote images. Webmail may block images until user consent—CTAs must work without images.
- Scripting. Modern webmail strips scripts; do not rely on JS.
- Link wrapping. Security rewriters change URLs; text and HTML should still name the same destination intent.
- OTP extraction. Automations should search text first, then sanitized HTML. See Playwright isolation.
Safe rendering practices on receive-side products (including Mailby) emphasize sandboxing and CSP-like constraints—see security.
Part table
| Raw part | Declared type | Observed rendering | Accessibility/security implication |
|---|---|---|---|
| Body A | text/plain | Shown if HTML blocked/unavailable | Screen readers / CLI clients |
| Body B | text/html | Default in most webmail | XSS risk if unsanitized |
| Body C | text/html with remote img | Images proxied or blocked | Tracking pixels; layout shift |
| Mismatch A vs B | both | Divergent UX | Wrong OTP / legal text |
| Attachments outside alternative | multipart/mixed wrapper | Shown as files | Malware scanning needed |
Worked example: debugging “button missing”
- User on corporate webmail sees no Verify button.
- You inspect raw MIME: HTML button present; text part only has a raw URL.
- Corporate client forces text mode.
- Fix: put the full HTTPS URL in the text part on its own line; keep HTML button in sync.
- Verify with Mailby preview + one major webmail.
Alternatives and durable mail
- Send plain-text only for highly constrained environments.
- multipart/mixed + alternative when attachments are required—keep OTPs out of attachment-only paths.
- Durable mailboxes matter for long-term legal archives of what was “said” in each part; disposable inboxes are for short QA. Retention: data retention.
When not to use temp mail: storing production MIME samples that contain real user PII beyond the test window.
Short answers
What causes multipart/alternative confusion in webmail?
Clients pick one alternative; senders ship mismatched parts; security gateways mutate HTML.
What should I do first?
Dump raw MIME, compare text vs HTML strings for OTPs/URLs, fix the generator template.
When is a permanent address safer?
Archival and compliance review of sent mail. For QA of templates, disposable receive is fine.
What evidence changes the recommendation?
Client population mostly text-only; or legal requires identical content hashes across parts.
Sources, test date, and limitations
Test date: 2026-09-24.
External sources:
Limitations: Exact sanitization rules differ by webmail. Mailby preview ≠ Gmail pixel-perfect. No fake UI screenshots included.
Generator checklist for engineers
When you build templates:
- Render text and HTML from the same data model.
- Unit-test that OTPs and URLs match across parts.
- Put absolute HTTPS URLs in text parts.
- Avoid essential information only in images.
- Keep HTML simple enough for aggressive sanitizers.
QA matrix (minimum)
| Client | Mode | What to check |
|---|---|---|
| Gmail web | HTML | Buttons, fonts |
| Outlook | HTML | Link rewriting |
| Apple Mail | HTML | Dark mode contrast |
| Text-only | text | URL present |
| Mailby preview | sanitized HTML | OTP extract |
Intentionally broken tests
Ship a staging template that deliberately mismatches parts once—to prove your monitors catch it—then fix. Do not leave it in production.
Accessibility
Plain text is not optional garnish. It is the accessible representation for many users and tools. Align wording, not just links.
How this differs from a message-format hub
Hub pages catalog MIME. This article is the webmail rendering lens on multipart/alternative, with fixtures and a receive-side preview path via Mailby.
Security sanitizer mismatches
Your QA browser shows a perfect button. A secured enterprise webmail strips the <a> leaving bare text—or drops the HTML part entirely. Always include the URL in text. If legal copy differs between parts, you may create contractual ambiguity; keep them aligned.
Internationalization
Encoded-word headers and UTF-8 bodies interact badly with legacy gateways. Test non-ASCII OTPs carefully; prefer digit OTPs.
AMP / interactive email
Exotic formats are not universal. Prefer progressive enhancement: core action works in text and basic HTML.
Receive-side engineering at Mailby
Safe preview exists so you can inspect untrusted HTML without giving it your full browser session. Use it when validating templates you receive; still run major webmail checks before shipping as a sender.
Debugging checklist when “HTML looks empty”
- Wrong
Content-Transfer-Encoding - Boundary typos truncating parts
- HTML in quoted-printable soft line breaks breaking tags
- Client blocking the message as bulk and showing a snippet only
Raw source is truth; UI is interpretation.
End-to-end worked example (OTP email)
- App renders model
{code: "482193", url: "https://app.example/verify"}. - Text part:
Your code is 482193\n\nOr open https://app.example/verify - HTML part: paragraph + button pointing to the same URL + same code visible as text (not image-only).
- QA receives in Mailby; extractors find 482193 in text.
- Gmail shows button; Outlook rewrites URL but landing page still works.
- Text-only user copies URL; succeeds.
Break step 3 by putting a different code in HTML—watch support volume rise. Automated tests from the Playwright article should catch that before release.
Legal and marketing footers
Footers must match across parts if they contain offers or unsubscribe URLs. Regulators care about the recipient experience, not your MIME aesthetics.
When webmail shows “this message has no content”
Often the HTML part is empty or blocked and the text part was omitted. Fix the generator; do not blame the client first.
Client preference nuances
While RFC guidance suggests choosing the last capable alternative, real clients add heuristics: block remote images, rewrite links, prefer text for accessibility modes, or show “plain text version” toggles. Design so either path completes the user goal.
Image-only CTAs
Buttons implemented as images without text equivalents fail when images are blocked. Use HTML text/buttons plus a text-part URL.
Quoted-printable footguns
Long lines soft-wrapped in the middle of a URL break clicks in some clients. Keep URLs intact; use proper encoding.
Testing with Mailby + one desktop client + one mobile client
Three receive checks catch most generator bugs before production. Automation adds the fourth (Playwright isolation).
Archive and eDiscovery note
If you must prove what a user could have seen, retain both parts. Divergent parts create ambiguity in disputes—another reason to keep them synchronized at send time.
Minimal MIME skeleton (copy/adapt)
Use your language’s MIME library rather than hand-concatenating when possible. Libraries handle boundaries and encodings. Hand-built MIME is a common source of “empty message” bugs.
Regression tests worth automating
- Identical OTP in text and HTML
- Identical primary CTA URL
- Text part nonempty
- HTML contains no
javascript:URLs - Unsubscribe URL present in both parts for marketing mail
Wire these into CI beside Playwright flows.
Reader tip for received mail
If a webmail HTML view looks wrong, switch to “show original” / raw and read the text part. That skill debugs sender mistakes quickly—whether you use Gmail or inspect via Mailby preview.
Extended pitfalls list
- HTML part references CID images that were never attached → broken layout.
- Text part includes tracking URLs longer than 998 octets without proper folding → corruption.
- Different unsubscribe URLs in text vs HTML → compliance risk.
- OTP only in an image → extraction and accessibility fail.
multipart/alternativenested incorrectly undermultipart/mixed→ some clients show a blank body beside attachments.
Each pitfall has the same remediation pattern: generate from one model, test multiple clients, assert equality on critical strings.
Receive-side tip
When something looks blank in webmail, download raw source. If text is present, the bug is rendering or sanitization. If both parts are empty, the sender pipeline failed before SMTP DATA completed meaningfully.
Why marketers ship mismatched parts
HTML gets lovingly designed; text is an afterthought generated by a lossy converter that drops URLs or mangles codes. Budget time for text. It is a first-class client, not a trash tier.
Accessibility law and ethics
Regardless of jurisdiction, users who need text deserve the same OTP and the same destination. Matching parts is the minimum bar.
Mailby role
Use Quick Inbox to see sanitized HTML quickly, then confirm in at least one major webmail. Developers can assert parts via /developers. Neither replaces reading RFC 2046 when building a new composer.
Last mile
If text and HTML disagree, users do not experience “MIME”—they experience a broken product. Synchronize the parts before you ship.
Prefer boring, synchronized MIME over clever HTML that only one client understands.
Conclusion
multipart/alternative is a negotiation. Keep alternatives consistent, order them thoughtfully, and verify with real clients—including a safe receive preview. Contradictory parts are a self-inflicted outage.
Preview inbound MIME with Quick Inbox or automate part assertions via /developers.
Try it on Mailby
Open a receive-only disposable inbox when a short-lived address fits the job — session-bound, with timed purge.