A message is a MIME tree, not a bag of parts
SMTP acceptance is not a rendering test. A server can accept a message whose MIME parts are perfectly readable on their own but describe the wrong relationships. The recipient's mail client then has to guess which body to show, whether an image belongs inside the HTML, and which files are attachments.
As soon as an email contains more than one representation or resource, its shape carries meaning. The MIME standards define three multipart types that do most of the work in application email:
| Multipart type | What the relationship means | Typical use |
|---|---|---|
multipart/alternative |
Its children are different representations of the same content. The client chooses the best version it can display. | A plain-text body alongside an HTML body |
multipart/related |
Its children form one compound object and only make complete sense together. | An HTML body with images referenced through cid: URLs |
multipart/mixed |
Its children are independent parts bundled in a particular order. | A message body followed by attachments or a forwarded message |
These containers are not interchangeable. A rich message often nests all three: alternatives together, inline resources around those alternatives, and independent attachments at the outside.
What goes wrong when the structure is wrong
Mail clients do not all recover from a misleading MIME tree in the same way. A message may look fine in one client and fail somewhere else. These are common symptoms; the exact cause still has to be confirmed from the raw message.
| What the recipient sees | What the MIME message may be saying instead |
|---|---|
| The plain and HTML bodies appear together, one disappears, or one becomes an attachment. | The representations are not grouped and ordered as alternatives. |
| An inline image is broken or appears in the attachment list. | The image is outside the related body, or its Content-ID does not match the HTML's cid: reference. |
| A paperclip appears even though the sender added no downloadable attachment. | An inline resource or body part has been presented as an independent mixed part. |
| An attachment is missing, displayed inline, or handled as the wrong file type. | Its position, media type, or Content-Disposition does not describe it correctly. |
| Text, filenames, or binary content arrive garbled. | The charset, transfer encoding, or MIME metadata does not match the content that was sent. |
Jakarta Mail provides the parts. Simple Java Mail assembles them.
Jakarta Mail provides the standard MimeMessage, MimeBodyPart, and MimeMultipart building blocks. It serializes
the finished message, writes boundaries and headers, applies encodings, and transports the result. At that level, your application still decides
what every part means and how the parts should be nested.
Simple Java Mail starts from the content you declare: plain text, HTML, embedded resources, calendar data, attachments, or a forwarded message. It then selects the matching MIME structure and fills in the body parts, content IDs, dispositions, and encodings needed by that structure.
Automatic MIME-structure selection is one of Simple Java Mail's core capabilities. It is also what library comparisons often miss: supporting each content type is not the same as combining them correctly.
Other APIs range from direct multipart control to helpers for common message types. The side-by-side comparison shows where each library leaves the work.
See the structure Simple Java Mail chooses
Select the content in your message to see how Simple Java Mail combines alternative, related, and mixed.
The tree is simplified to show the relationship between parts; the generated message also contains the headers and encodings those parts need.