# MIME for developers: alternative, related and mixed

> Most email bugs with images and attachments are MIME tree bugs. Learn how multipart/alternative, related and mixed nest, with a correct example.

- Published: 2026-09-29
- Author: Koltrix Team
- Category: Guides
- Source: https://koltrix.com/blog/mime-structure-for-developers

When an inline logo shows up as a mysterious attachment, or an invoice PDF disappears in one client but not another, the bug is almost always in the MIME tree. Understanding three multipart types, and how they nest, explains most of these problems.

## MIME in thirty seconds

An email message is headers plus a body. MIME (defined in RFCs 2045 through 2049) lets that body contain multiple parts, each with its own headers and content type. A multipart body is divided by a boundary string declared in the Content-Type header:

```text
Content-Type: multipart/alternative; boundary="alt-7f3a"
```

Each part begins with `--alt-7f3a` on its own line, and the whole multipart ends with `--alt-7f3a--`. Parts can themselves be multiparts, which is how a message becomes a tree.

## The three multipart types that matter

### multipart/alternative: same content, different formats

Each child is a complete representation of the same content. The client picks the best one it can display. Typical children are `text/plain` and `text/html`. RFC 2046 says alternatives go in order of increasing preference, so plain text first, HTML last.

Clients show **one** child, never all of them. If you put an attachment inside `multipart/alternative`, some clients will never show it, because they chose the HTML alternative instead.

### multipart/related: one document with its resources

The first child is the root document, usually HTML. The remaining children are resources it references, such as inline images, each with a `Content-ID` header. The HTML refers to them with `cid:` URLs:

```html
<img src="cid:logo-01@example.com" alt="Example Inc." width="120" height="40">
```

```text
Content-Type: image/png
Content-ID: <logo-01@example.com>
Content-Disposition: inline; filename="logo.png"
```

Resources in `multipart/related` are part of the document, not separate files for the user.

### multipart/mixed: independent parts in sequence

The children are separate things shown or offered one after another. This is where attachments live. The first child is usually the message body (which may itself be a multipart), followed by attachments with `Content-Disposition: attachment`.

## The canonical tree for a rich message

A message with an HTML body, a plain-text alternative, an inline logo and a PDF attachment nests like this:

```text
multipart/mixed
├── multipart/alternative
│   ├── text/plain
│   └── multipart/related
│       ├── text/html
│       └── image/png        (Content-ID: logo-01@example.com, inline)
└── application/pdf          (attachment; filename="invoice-A-10293.pdf")
```

Read it from the outside in:

- **mixed** at the top holds "the message" and "the attachment."
- **alternative** inside offers plain text or the rich version.
- **related** groups the HTML with the image it embeds, so only clients that choose HTML load the image.

Drop any layer you do not need. A message without attachments has no `mixed` layer. A message without inline images has no `related` layer. A plain-text-only message is just `text/plain`.

## A minimal raw example

Here is the structure without attachments or images, which covers most transactional mail:

```text
From: Example <notifications@example.com>
To: sam@example.net
Subject: Your code is 482913
MIME-Version: 1.0
Content-Type: multipart/alternative; boundary="alt-7f3a"

--alt-7f3a
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

Your sign-in code is 482913. It expires in 10 minutes.

--alt-7f3a
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<p>Your sign-in code is <strong>482913</strong>. It expires in 10 minutes.</p>

--alt-7f3a--
```

## The bugs this explains

### "My inline image shows up as an attachment"

The image was placed in `multipart/mixed` instead of `multipart/related`, or it lacks a `Content-ID` that matches the `cid:` reference, or its disposition is `attachment`. Some clients also list inline images as attachments regardless; you cannot fully control that.

### "The PDF is missing in some clients"

The attachment was placed inside `multipart/alternative`. A client that selected the HTML alternative ignores siblings. Move attachments to an outer `multipart/mixed`.

### "Some recipients see only the plain text"

The HTML part came first in the alternative. Clients that follow the "last is best" rule may display the plain-text part as the preferred version. Put HTML last.

### "Both versions show, one after the other"

The parts were put in `multipart/mixed` instead of `multipart/alternative`, so the client treats them as two separate things to display.

### "The body shows as garbled text"

A part has the wrong `Content-Transfer-Encoding` declared, or declares base64 while containing raw text. Make the declared encoding match what you actually wrote.

## Encoding rules worth remembering

| Header | Purpose | Common values |
|---|---|---|
| Content-Type | What the part is | `text/plain; charset="UTF-8"`, `text/html`, `image/png`, `application/pdf` |
| Content-Transfer-Encoding | How bytes are represented for transport | `7bit`, `quoted-printable`, `base64`, `8bit` |
| Content-Disposition | How to present it | `inline`, `attachment; filename="..."` |
| Content-ID | Reference target for `cid:` | `<unique@example.com>` |

Non-ASCII text should be quoted-printable or base64 unless you know every hop supports 8BITMIME. Binary attachments are base64. Lines must stay under 998 characters, which encoding guarantees.

Boundaries must not appear anywhere in the content they delimit. Libraries generate random boundaries for this reason. Never build MIME by hand-concatenating strings in production; use your language's mail library, which handles boundaries, encoding and line endings.

## Inspecting a real message

Most clients offer "Show original" or "View source." Look for the Content-Type lines and indent them mentally by nesting depth. Or parse it:

```python
import email, sys
from email import policy

msg = email.message_from_binary_file(open(sys.argv[1], "rb"), policy=policy.default)

def walk(part, depth=0):
    disp = part.get_content_disposition() or ""
    print("  " * depth + f"{part.get_content_type()} {disp} {part.get_filename() or ''}")
    if part.is_multipart():
        for child in part.iter_parts():
            walk(child, depth + 1)

walk(msg)
```

Run it against a message that misbehaves and the tree usually makes the bug obvious.

## Two more types you will meet

### message/rfc822: a whole email inside an email

When a client forwards a message "as attachment," or a bounce report includes the original message, the embedded message travels as a part with type `message/rfc822`. Its content is a complete email, with its own headers and possibly its own multipart tree. Treat it as a separate message when parsing: do not merge its headers with the outer message, and be careful when displaying it, since its From and Subject were written by someone else.

### multipart/report: delivery notifications

Delivery status notifications, defined in RFC 3464, use `multipart/report`. The first part is a human-readable explanation, the second is a machine-readable `message/delivery-status` part with fields such as the final recipient, the action taken and the status code, and an optional third part contains the original message or its headers. If you process bounces yourself, parse the delivery-status part rather than scraping the human-readable text, which varies wildly between servers.

## Key takeaways

- `alternative` offers the same content in different formats, and clients show only one child.
- `related` binds an HTML document to inline resources referenced by `cid:`.
- `mixed` holds independent parts, which is where attachments belong.
- The standard nesting is mixed, then alternative, then related; omit layers you do not need.
- Put plain text before HTML in alternatives, and keep attachments out of alternatives.
