Gmail API MIME types


I’ve found Gmail’s API surprisingly confusing, mostly because email was so clearly built in a time before JSON. The message payload is broken into parts, depending on the structure (attachments, images) of the email, each labeled with a different, poorly documented mimeType.

After an hour of clicking around1, I came to this understanding of the various MIME types.

MIME Types

text/plain

Most messages composed by people have a plaintext version, for email readers that do not support HTML.

text/html

Most rich emails are actually HTML. This one tends to be the most canonical.

multipart/related

This type is for message bodies with an embedded image. The ‘parts’ of this component should be the message contents (sometimes, this is just text/plain if this is a plain email or it can be multipart/alternative)

multipart/mixed

When messages have an attachment (that could be an image). The parts of this component are usually either multipart/related (if there is an embedded image) or text/html. If there is an attachment, this will likely be at the top level.

multipart/alternative

When there are plaintext and html versions of this message. Most emails will have this at the top level, unless there is an attachment.

MIME example hierachies

Plain Email

  • text/plain

HTML Email2

  • multipart/alternative
    • text/plain
    • text/html

HTML Email with embedded image

  • multipart/related
    • multipart/alternative
      • text/plain
      • text/html
    • image/png (embedded image)

HTML Email with embedded image and attachment

  • multipart/mixed
    • multipart/related
      • multipart/alternative
        • text/plain
        • text/html
      • image/png (embedded image)
    • image/png (attached image)

HTML Email with attachment

  • multiplart/mixed
    • multipart/alternative
      • text/plain
      • text/html
    • image/png (attached image)
  1. MIME Types

  2. Usually HTML emails will come with a plaintext alternative, but it’s pretty to imagine the structure of a html-only email. 😁