multipart/alternative vs multipart/mixed: The Difference

MIME multipart is the wrapper email uses to fit more than one thing into a single message. The names look interchangeable — alternative, mixed, related — and they are not. Each one tells the receiving client to do a different thing with the parts inside, and picking the wrong one is why the same message shows as plain text in one inbox and as a wall of unrendered HTML in the next.

This guide draws the line between the two you meet most often — multipart/alternative and multipart/mixed — with a worked structure tree for each and a note on where multipart/related sits between them. If you take one thing from it: alternative gives the client a choice, mixed gives the client a stack, and related bundles an HTML part with the images it points at.

The verdict up front#

multipart/alternative (RFC 2046 §5.1.4) carries the same message in more than one format — a plain-text version and an HTML version — and the client picks the format it prefers to render. Only one shows up.

multipart/mixed (RFC 2046 §5.1.3) carries different content in each part — a body plus one or more attachments — and the client renders all of them. Nothing is a choice; everything is included.

multipart/related (RFC 2387) carries an HTML body plus the resources the HTML references using cid: URLs, most often inline images. It is not a competitor to the other two; it usually sits inside a multipart/alternative next to the plain-text version.

The commonest email you send today is a nested combination of all three: a mixed container for the message body plus attachments, an alternative inside it for the two body formats, and a related inside the HTML side for the inline images. When people argue about "which multipart type to use," the honest answer is usually all three, in that order.

The three multipart types at a glance#

Here is the whole contrast on one screen. The rows that decide behavior are the client-behavior and typical-use rows — everything else follows from those two.

Where multipart/alternative wins#

multipart/alternative is the wrapper you reach for when the sender wants the same message delivered as text, HTML, or both, and the client to pick which one to show. Two facts about it decide almost everything else.

• Order matters. RFC 2046 §5.1.4 says the client should pick and display the last format it can render, so parts run simplest to richest — text/plain first, text/html last. Reverse that order and HTML clients may still fall back to plain, because they take the first option their parser tolerates.
• Only one part is shown. The reader never sees both versions in the same window. That is the point of alternative: two renderings of one message, one delivered.
• The parts have to say the same thing. If your plain-text version reads "Meeting Thursday" and your HTML version reads "Meeting Friday," some readers will see the wrong day and there is no way to know which. Equivalence is the contract of multipart/alternative, and breaking it is a class of bug that filters cannot catch.
• Text-only readers, screen readers and modern HTML clients all read from one wrapper. You do not maintain a separate plain-text mailing.

Where multipart/mixed wins#

multipart/mixed is the wrapper you reach for when every part has to be delivered, in order, each rendered on its own terms — the shape of a body plus attachments, and of every message with a file the reader is meant to keep.

• Every part is shown. A multipart/mixed with a message body and a PDF gives the reader both — a body they can read and a file they can save.
• Order is preserved. Clients present the parts in the order they appear in the message. The first part is usually the body; attachments trail it.
• Content-Disposition (RFC 2183) is what turns a part into an attachment. A part with Content-Disposition: attachment renders as a downloadable file with a filename; a part with disposition inline (or none) tries to render in the message flow.
• It almost always wraps something else. The outer multipart/mixed of a real email usually contains a multipart/alternative for the body — not a bare text/plain — so text-only and HTML readers each get a proper body next to the attachments. Bare mixed with a lone text/plain body is legal but rare in modern mail.

A worked structure tree for each#

Three trees, in the order you meet them in practice — first each type on its own, then the nested combination modern email actually sends.

No attachment, no inline image — just the message, in two renderings. Every well-behaved email has this structure somewhere inside it, even when it also has other things.

Note the nesting: the mixed part is the outer wrapper, and the body is not a bare text part — it is a multipart/alternative, so the recipient's client still gets to choose between the plain and HTML renderings.

The tree modern email actually sends#

Put the three together and you get the standard shape a well-formed email takes when it has both an inline image and an attachment. It looks deep on the page, and it is, but every layer is doing a job the layer above cannot do.

Why the same message renders differently across clients#

Two well-behaved clients can read the same multipart/alternative and show different things. Some of that is standards-compliant; some of it is not.

The standards-compliant version, from RFC 2046 §5.1.4: the client walks the parts and picks the last one it can display. If your message has text/plain then text/html, an HTML client shows the HTML; a terminal client that cannot render HTML shows the plain. That is the contract, and modern webmail clients honor it.

The non-compliant version: some clients pick the first part they recognize instead of the last, some let the reader force plain-text rendering for every message, and some silently fall back to the plain-text part when the HTML fails to parse. If a message is stored somewhere along the way by a system that flattens or reorders parts (older gateways, some archiving systems), the client only sees what survived.

So the answer to "why does my email show plain text instead of HTML" is almost always one of four things: the HTML part is missing, the HTML part comes before the plain-text part inside the alternative, the client's user preference is set to plain, or the HTML is malformed enough that the client bailed. Check the raw source before blaming the recipient — the send-side mistakes are more common than the render-side ones.

Cost, and where the tooling lives#

MIME multipart is a set of open, free-to-use standards: RFC 2046 for alternative and mixed, RFC 2387 for related, RFC 2392 for the cid: URL scheme, RFC 2183 for Content-Disposition. Nobody sells you a subtype. What is packaged and sold is the tooling that emits the right tree without you having to hand-write MIME.

The shapes below are a map, not a price list — verify current terms on each vendor's own page before you commit. This is an area where limits and tiers change often (checked August 2026).

• Mail clients that emit multipart correctly for every send are usually priced per mailbox or per user, sometimes bundled with mailbox hosting, sometimes a trial that converts to a monthly plan, sometimes a lightweight free tier plus paid tiers.
• Test-mail and dev-inbox services (Mailtrap, Litmus, and their peers) are metered on emails per month, so you can inspect the raw MIME your app actually sends before it reaches a customer.
• ESPs and transactional-mail APIs (SendGrid, Postmark, Mailgun and similar) are usage-metered on messages, with feature and deliverability tiers layered on top.
• AI Emaily runs on a 7-day free trial with a card required and no charge if you cancel before day seven. There is no permanent free tier; plan shapes are on aiemaily.com/pricing.

Who each multipart type is genuinely for#

Match the wrapper to the job. The choice is almost always obvious once you know what has to reach the reader.

• Use multipart/alternative whenever your message has both a plain-text and an HTML rendering — which should be always for a normal email. The plain fallback is what makes the message readable in text-only clients, in preview panes that render plain, and to accessibility tools that walk the plain part.
• Use multipart/mixed whenever there is anything the reader keeps as a file — a PDF, an image sent as a downloadable, a spreadsheet, a signed document. The rule of thumb: attachments live in multipart/mixed; bodies live in multipart/alternative inside it.
• Use multipart/related only when your HTML references resources the client will not fetch from the web — most often inline images with cid: URLs. If your HTML just links to remote images with an https:// src, you do not need multipart/related at all.
• Do not pick a multipart type at all if you are writing a bare plain-text message. A single text/plain body needs no wrapper.

A third option, honestly: multipart/related and inline images#

multipart/related is the least understood of the three, and the one people reach for when they want an image to sit inside the message body rather than come down as an attachment — the company logo at the top of a marketing email, a diagram in a support reply, a signature graphic.

The mechanism, in one paragraph: the HTML part uses an img src that starts with cid:, where the value after the prefix matches the Content-ID assigned to another part in the same multipart/related. RFC 2392 defines the cid: URL scheme; the client resolves it against the parts it already has, rather than fetching anything from the web. Because the image travels with the message, the recipient sees it offline and sees it even when their client blocks remote content by default — which is why the answer to "why does my inline image not render" is usually to switch from a remote src to a cid: reference inside a multipart/related.

There are trade-offs, and they are worth stating plainly before you build around it.

• The message is larger. Inline parts are base64-encoded, which adds roughly 33% to the size of the raw bytes on the wire.
• Some webmail clients strip inline images and re-render them as regular attachments, which is why a logo that should sit at the top of a message sometimes lands as "logo.png" attached to the message instead.
• Content-ID has to be unique per part and match the cid: URL exactly, angle-bracketed in the header and unbracketed in the URL. A typo silently breaks the image.
• If you have both inline images and a real attachment, the tree gets deep: multipart/mixed wraps multipart/alternative, which wraps a text/plain and a multipart/related, which wraps text/html and image/png, next to the application/pdf that lives at the mixed layer.

Where a mail client's composer fits#

This post has been about which multipart type you would choose if you were writing MIME by hand. In practice, almost nobody does, and the reason is that a working mail client's composer emits the tree for you: mixed for attachments, alternative for plain and HTML renderings, related for the inline images the HTML references, all wired up so the receiving client behaves the way this guide describes.

That is the layer we work on. AI Emaily is an AI-native mail client, and its composer emits the standard multipart/mixed → multipart/alternative → multipart/related nesting for every draft: the plain-text fallback is generated from the HTML so both are present, any inline image the agent embeds is referenced from a multipart/related rather than left as a broken remote src, and attachments live at the mixed layer where RFC 2046 §5.1.3 puts them. We build AI Emaily; more on the drafting side at aiemaily.com and on the plans at aiemaily.com/pricing.

To be clear about the limits, because this post is not the place to sell you an adjacent thing as the answer: AI Emaily is not a MIME diagnostic tool, and it is not an ESP or a mail-merge service. If you want to inspect the raw multipart tree of a message your service already sent, use a test-mail service that shows you the source. If you want to send templated mail in bulk, an ESP or a mail-merge platform is the right tool for that. What AI Emaily does is compose, triage and reply to the mail in a working inbox — a job that happens to require getting the multipart nesting right, which is why the composer is built around the tree above. It runs on a 7-day free trial with a card required and no charge if you cancel before day seven; there is no permanent free tier.