Gmail API MIME types

December 25th, 2016

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 around¹, 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 Email²

• 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)