IMAP BODYSTRUCTURE: formatted examples

The IMAP specification rfc3501 is unclear about the body structure of an email. Below are some examples with explanations. They are all real body structures as returned by IMAP servers in response to FETCH messagenumber BODYSTRUCTURE commands. For each:

The program used for formatting is imapbodystructure. The colors have been added manually to highlight the content parts of the email and the way they are combined: yellow for parts and cyan for their combinations.

single-part email

This is the body structure of a mail made of a single part only.

IMAP server reply:

* 15 FETCH (BODYSTRUCTURE ("TEXT" "PLAIN" ("CHARSET" "iso-8859-1") NIL NIL "QUOTED-PRINTABLE" 1315 42 NIL NIL NIL NIL))

indented:
*
15
FETCH
(
    BODYSTRUCTURE
    ("TEXT" "PLAIN" ("CHARSET" "iso-8859-1") NIL NIL "QUOTED-PRINTABLE" 1315 42 NIL NIL NIL NIL)
)

The whole bodystructure is a single part of type "TEXT/PLAIN".

Such mails are rarely seen nowadays. An even more uncommon form has a single part of type TEXT/HTML. Modern mail clients send mail in the next form (text+html) instead, but a single-part email can still be obtained by: echo -e "Subject: example\n\nabcd" | sendmail name@domain.com.

text + html

Most email client send emails in both text and html. The content is the same, but html also includes formatting.

IMAP server reply

* 1 FETCH (BODYSTRUCTURE (("TEXT" "PLAIN" ("CHARSET" "iso-8859-1") NIL NIL "QUOTED-PRINTABLE" 2234 63 NIL NIL NIL NIL)("TEXT" "HTML" ("CHARSET" "iso-8859-1") NIL NIL "QUOTED-PRINTABLE" 2987 52 NIL NIL NIL NIL) "ALTERNATIVE" ("BOUNDARY" "d3438gr7324") NIL NIL NIL))

indented:
*
1
FETCH
(
    BODYSTRUCTURE
    (
        ("TEXT" "PLAIN" ("CHARSET" "iso-8859-1") NIL NIL "QUOTED-PRINTABLE" 2234 63 NIL NIL NIL NIL)
        ("TEXT" "HTML" ("CHARSET" "iso-8859-1") NIL NIL "QUOTED-PRINTABLE" 2987 52 NIL NIL NIL NIL)
        "ALTERNATIVE"
        ("BOUNDARY" "d3438gr7324")
        NIL
        NIL
        NIL
    )
)

This is an ALTERNATIVE between two parts: a TEXT/PLAIN and a TEXT/HTML. That these two parts are in alternative means that they have the same content, so that the mail client can choose which one to show to the user.

In general, a multi-part alternative message is represented by a list:

(PART1 PART2 PART3 ... "ALTERNATIVE" A B C...)

The parts that are in alternative are PART1, PART2, PART3, etc. The string "ALTERNATIVE" has two roles: it marks the end of the parts and tells that these parts are alternative representations of the same content. The following elements A B C... are attributes of the list, not additional parts.

This form also applies to the other lists: RELATED and MIXED.

mail with images

Mails can be sent with images in them. This is obtained by an html part with an associated set of images.

IMAP server reply:

* 335 FETCH (BODYSTRUCTURE (("TEXT" "HTML" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 119 2 NIL ("INLINE" NIL) NIL)("IMAGE" "JPEG" ("NAME" "4356415.jpg") "<0__=rhksjt>" NIL "BASE64" 143804 NIL ("INLINE" ("FILENAME" "4356415.jpg")) NIL) "RELATED" ("BOUNDARY" "0__=5tgd3d") ("INLINE" NIL) NIL))

indented:
*
335
FETCH
(
    BODYSTRUCTURE
    (
        ("TEXT" "HTML" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 119 2 NIL ("INLINE" NIL) NIL)
        ("IMAGE" "JPEG" ("NAME" "4356415.jpg") "<0__=rhksjt>" NIL "BASE64" 143804 NIL ("INLINE" ("FILENAME" "4356415.jpg")) NIL)
        "RELATED"
        ("BOUNDARY" "0__=5tgd3d")
        ("INLINE" NIL)
        NIL
    )
)

This message contains two parts: a TEXT/HTML and an IMAGE/JPEG image. The intention is that the user is shown the html part with the image embedded into it in the appropriate place. The two parts are to be presented together, not alternatively. As a result, they are combined as RELATED, not as alternatives.

text + html with images

Most mail with images still contain an alternative text-only version.

IMAP server reply:

* 202 FETCH (BODYSTRUCTURE (("TEXT" "PLAIN" ("CHARSET" "ISO-8859-1" "FORMAT" "flowed") NIL NIL "QUOTED-PRINTABLE" 2815 73 NIL NIL NIL NIL)(("TEXT" "HTML" ("CHARSET" "ISO-8859-1") NIL NIL "QUOTED-PRINTABLE" 4171 66 NIL NIL NIL NIL)("IMAGE" "JPEG" ("NAME" "image.jpg") "<3245dsf7435>" NIL "BASE64" 189906 NIL NIL NIL NIL)("IMAGE" "GIF" ("NAME" "other.gif") "<32f6324f>" NIL "BASE64" 1090 NIL NIL NIL NIL) "RELATED" ("BOUNDARY" "--=sdgqgt") NIL NIL NIL) "ALTERNATIVE" ("BOUNDARY" "--=u5sfrj") NIL NIL NIL))

indented:
*
202
FETCH
(
    BODYSTRUCTURE
    (
        ("TEXT" "PLAIN" ("CHARSET" "ISO-8859-1" "FORMAT" "flowed") NIL NIL "QUOTED-PRINTABLE" 2815 73 NIL NIL NIL NIL)
        (
            ("TEXT" "HTML" ("CHARSET" "ISO-8859-1") NIL NIL "QUOTED-PRINTABLE" 4171 66 NIL NIL NIL NIL)
            ("IMAGE" "JPEG" ("NAME" "image.jpg") "<3245dsf7435>" NIL "BASE64" 189906 NIL NIL NIL NIL)
            ("IMAGE" "GIF" ("NAME" "other.gif") "<32f6324f>" NIL "BASE64" 1090 NIL NIL NIL NIL)
            "RELATED"
            ("BOUNDARY" "--=sdgqgt")
            NIL
            NIL
            NIL
        )
        "ALTERNATIVE"
        ("BOUNDARY" "--=u5sfrj")
        NIL
        NIL
        NIL
    )
)

At the highest level, this email is an ALTERNATIVE between a TEXT/PLAIN part and a second part that contains an html file and two images.

This second part is a set of three RELATED parts, of type TEXT/HTML, IMAGE/JPEG and IMAGE.GIF. These parts are not alternative views of the same content, but rather they all contribute to what is to be shown to the user.

mail with images

This is a different form of an email containing text and alternatively html and images. Is a common form, but the way images are associated to the text appear incorrect.

IMAP server reply:

* 41 FETCH (BODYSTRUCTURE ((("TEXT" "PLAIN" ("CHARSET" "ISO-8859-1") NIL NIL "QUOTED-PRINTABLE" 471 28 NIL NIL NIL)("TEXT" "HTML" ("CHARSET" "ISO-8859-1") NIL NIL "QUOTED-PRINTABLE" 1417 36 NIL ("INLINE" NIL) NIL) "ALTERNATIVE" ("BOUNDARY" "1__=hqjksdm") NIL NIL)("IMAGE" "GIF" ("NAME" "image.gif") "<1__=cxdf2f>" NIL "BASE64" 50294 NIL ("INLINE" ("FILENAME" "image.gif")) NIL) "RELATED" ("BOUNDARY" "0__=hqjksdm") NIL NIL))

indented:
*
41
FETCH
(
    BODYSTRUCTURE
    (
        (
            ("TEXT" "PLAIN" ("CHARSET" "ISO-8859-1") NIL NIL "QUOTED-PRINTABLE" 471 28 NIL NIL NIL)
            ("TEXT" "HTML" ("CHARSET" "ISO-8859-1") NIL NIL "QUOTED-PRINTABLE" 1417 36 NIL ("INLINE" NIL) NIL)
            "ALTERNATIVE"
            ("BOUNDARY" "1__=hqjksdm")
            NIL
            NIL
        )
        ("IMAGE" "GIF" ("NAME" "image.gif") "<1__=cxdf2f>" NIL "BASE64" 50294 NIL ("INLINE" ("FILENAME" "image.gif")) NIL)
        "RELATED"
        ("BOUNDARY" "0__=hqjksdm")
        NIL
        NIL
    )
)

The image is associated to both the text and the html parts, while it should be associated to the html part only. The intention might have been that the image is shown alongside the text of the email even if the text part is presented instead of html.

mail with attachment

Mails with attachments have this structure. In this particular example, the attachment is a single pdf file, while the text of the mail is in a single html part (no text alternative, in this case).

IMAP server reply:

* 302 FETCH (BODYSTRUCTURE (("TEXT" "HTML" ("CHARSET" "ISO-8859-1") NIL NIL "QUOTED-PRINTABLE" 4692 69 NIL NIL NIL NIL)("APPLICATION" "PDF" ("NAME" "pages.pdf") NIL NIL "BASE64" 38838 NIL ("attachment" ("FILENAME" "pages.pdf")) NIL NIL) "MIXED" ("BOUNDARY" "----=6fgshr") NIL NIL NIL))

indented:
*
302
FETCH
(
    BODYSTRUCTURE
    (
        ("TEXT" "HTML" ("CHARSET" "ISO-8859-1") NIL NIL "QUOTED-PRINTABLE" 4692 69 NIL NIL NIL NIL)
        ("APPLICATION" "PDF" ("NAME" "pages.pdf") NIL NIL "BASE64" 38838 NIL ("attachment" ("FILENAME" "pages.pdf")) NIL NIL)
        "MIXED"
        ("BOUNDARY" "----=6fgshr")
        NIL
        NIL
        NIL
    )
)

This is a MIXED list of two parts: a TEXT/HTML part which is the text of the email and and APPLICATION/PDF part which is the attachment.

MIXED lists differ from the ALTERNATIVE and RELATED lists because the two parts are not in alternative (only the html is shown to the user; the pdf is usually only accessible via a link that can be followed) and are not related (the pdf file is not shown as embedded in the html part). The two parts contain different information and are not supposed to be shown together.

alternative and attachment

A mail may contain an attachment and still offer two alternative representation of its text content.

IMAP server reply:

* 356 FETCH (BODYSTRUCTURE ((("TEXT" "PLAIN" ("CHARSET" "UTF-8") NIL NIL "QUOTED-PRINTABLE" 403 6 NIL NIL NIL NIL)("TEXT" "HTML" ("CHARSET" "UTF-8") NIL NIL "QUOTED-PRINTABLE" 421 6 NIL NIL NIL NIL) "ALTERNATIVE" ("BOUNDARY" "----=fghgf3") NIL NIL NIL)("APPLICATION" "MSWORD" ("NAME" "letter.doc") NIL NIL "BASE64" 110000 NIL ("attachment" ("FILENAME" "letter.doc" "SIZE" "80384")) NIL NIL) "MIXED" ("BOUNDARY" "----=y34fgl") NIL NIL NIL))

indented:
*
356
FETCH
(
    BODYSTRUCTURE
    (
        (
            ("TEXT" "PLAIN" ("CHARSET" "UTF-8") NIL NIL "QUOTED-PRINTABLE" 403 6 NIL NIL NIL NIL)
            ("TEXT" "HTML" ("CHARSET" "UTF-8") NIL NIL "QUOTED-PRINTABLE" 421 6 NIL NIL NIL NIL)
            "ALTERNATIVE"
            ("BOUNDARY" "----=fghgf3")
            NIL
            NIL
            NIL
        )
        ("APPLICATION" "MSWORD" ("NAME" "letter.doc") NIL NIL "BASE64" 110000 NIL ("attachment" ("FILENAME" "letter.doc" "SIZE" "80384")) NIL NIL)
        "MIXED"
        ("BOUNDARY" "----=y34fgl")
        NIL
        NIL
        NIL
    )
)

This is another example of how combinations of parts can nest. Overall, this mail has some text and an attachment APPLICATION/MSWORD, the word file letter.doc. The text is itself an ALTERNATIVE between TEXT/PLAIN and TEXT/HTML.

all together

This email has attachment, and its text is an alternative between text and html with images.

IMAP server reply:

* 1569 FETCH (BODYSTRUCTURE (((("TEXT" "PLAIN" ("CHARSET" "ISO-8859-1") NIL NIL "QUOTED-PRINTABLE" 833 30 NIL NIL NIL)("TEXT" "HTML" ("CHARSET" "ISO-8859-1") NIL NIL "QUOTED-PRINTABLE" 3412 62 NIL ("INLINE" NIL) NIL) "ALTERNATIVE" ("BOUNDARY" "2__=fgrths") NIL NIL)("IMAGE" "GIF" ("NAME" "485039.gif") "<2__=lgkfjr>" NIL "BASE64" 64 NIL ("INLINE" ("FILENAME" "485039.gif")) NIL) "RELATED" ("BOUNDARY" "1__=fgrths") NIL NIL)("APPLICATION" "PDF" ("NAME" "title.pdf") "<1__=lgkfjr>" NIL "BASE64" 333980 NIL ("ATTACHMENT" ("FILENAME" "title.pdf")) NIL) "MIXED" ("BOUNDARY" "0__=fgrths") NIL NIL))

indented:
*
1569
FETCH
(
    BODYSTRUCTURE
    (
        (
            (
                ("TEXT" "PLAIN" ("CHARSET" "ISO-8859-1") NIL NIL "QUOTED-PRINTABLE" 833 30 NIL NIL NIL)
                ("TEXT" "HTML" ("CHARSET" "ISO-8859-1") NIL NIL "QUOTED-PRINTABLE" 3412 62 NIL ("INLINE" NIL) NIL)
                "ALTERNATIVE"
                ("BOUNDARY" "2__=fgrths")
                NIL
                NIL
            )
            ("IMAGE" "GIF" ("NAME" "485039.gif") "<2__=lgkfjr>" NIL "BASE64" 64 NIL ("INLINE" ("FILENAME" "485039.gif")) NIL)
            "RELATED"
            ("BOUNDARY" "1__=fgrths")
            NIL
            NIL
        )
        ("APPLICATION" "PDF" ("NAME" "title.pdf") "<1__=lgkfjr>" NIL "BASE64" 333980 NIL ("ATTACHMENT" ("FILENAME" "title.pdf")) NIL)
        "MIXED"
        ("BOUNDARY" "0__=fgrths")
        NIL
        NIL
    )
)

As before, attachments are included by a MIXED list that contains both the text of the email and the attachments. The text is a RELATED list of text and an image. Text is again an ALTERNATIVE between plain text and html.

single-element lists

A list may contain a single element. The following email has a single TEXT/HTML part enclosed in a MIXED list that only comprises it.

IMAP server reply:

* 2246 FETCH (BODYSTRUCTURE (("TEXT" "HTML" NIL NIL NIL "7BIT" 151 0 NIL NIL NIL) "MIXED" ("BOUNDARY" "----=rfsewr") NIL NIL))

indented:
*
2246
FETCH
(
    BODYSTRUCTURE
    (
        ("TEXT" "HTML" NIL NIL NIL "7BIT" 151 0 NIL NIL NIL)
        "MIXED"
        ("BOUNDARY" "----=rfsewr")
        NIL
        NIL
    )
)

structure and parsing

An email comprises various parts (such as text, html, images and attachments), combined in various ways (alternative, related, mixed). An invididual part is always represented by a list that begins with its content type:

("TEXT" "PLAIN" ("CHARSET" "iso-8859-1") NIL NIL "QUOTED-PRINTABLE" 1315 42 NIL NIL NIL NIL)
("TEXT" "HTML" ("CHARSET" "iso-8859-1") NIL NIL "QUOTED-PRINTABLE" 2987 52 NIL NIL NIL NIL)
("IMAGE" "GIF" ("NAME" "485039.gif") "<2__=lgkfjr>" NIL "BASE64" 64 NIL ("INLINE" ("FILENAME" "485039.gif")) NIL)
("APPLICATION" "PDF" ("NAME" "pages.pdf") NIL NIL "BASE64" 38838 NIL ("attachment" ("FILENAME" "pages.pdf")) NIL NIL)

Some components of these lists may be missing, but not the first two ones, which are always strings:

(TYPE SUBTYPE ...)

A combination is a sequence of parts followed by the type of combination (ALTERNATIVE, RELATED or MIXED) followed by some other data of minor importance:

(PART1 PART2 PART3 ... "ALTERNATIVE" A B C)
(PART1 PART2 PART3 ... "RELATED" A B C)
(PART1 PART2 PART3 ... "MIXED" A B C)

Each among PART1, PART2, PART3 etc. may itself be an individual part (in the form (TYPE SUBTYPE ...)) or another combination (like (SUBPART1 SUBPART2 SUBPART3 ... "MIXED" A B C)).

This allows for a simple way to discriminate combinations from individual parts: (( is always the begin of a combination of some kind (ALTERNATIVE, RELATED or MIXED). The first parenthesis is the first character of the combination list; the second parenthesis is the first character of the first part. This first part may itself be a combination or an individual part, but in both cases begins with an open parenthesis. All lists that are not combinations start with (".

sequence numbers

The elements of a list are numbered 1, 2, 3, etc. If the first element is also a list, its elements 1.1, 1.2, 1.3, etc. These sequences are then used to retrieve a single part of an email.

Calling imapbodystructure with argument -p shows the number sequence of each part of an email; with -c, also the number sequence of combinations is printed. For example, one of the body structures above is printed as:

*
1569
FETCH
(
    BODYSTRUCTURE
    (
        [1] (
            [1.1] (
                [1.1.1] ("TEXT" "PLAIN" ("CHARSET" "ISO-8859-1") NIL NIL "QUOTED-PRINTABLE" 833 30 NIL NIL NIL)
                [1.1.2] ("TEXT" "HTML" ("CHARSET" "ISO-8859-1") NIL NIL "QUOTED-PRINTABLE" 3412 62 NIL ("INLINE" NIL) NIL)
                "ALTERNATIVE"
                ("BOUNDARY" "2__=fgrths")
                NIL
                NIL
            )
            [1.2] ("IMAGE" "GIF" ("NAME" "485039.gif") "<2__=lgkfjr>" NIL "BASE64" 64 NIL ("INLINE" ("FILENAME" "485039.gif")) NIL)
            "RELATED"
            ("BOUNDARY" "1__=fgrths")
            NIL
            NIL
        )
        [2] ("APPLICATION" "PDF" ("NAME" "title.pdf") "<1__=lgkfjr>" NIL "BASE64" 333980 NIL ("ATTACHMENT" ("FILENAME" "title.pdf")) NIL)
        "MIXED"
        ("BOUNDARY" "0__=fgrths")
        NIL
        NIL
    )
)

The parts of this email are retrived by these sequences. For example, the html part of this mail of number 1569 has sequence 1.1.2, so the request for this part is: FETCH 1569 BODY[1.1.2].


Was this page useful? Star it on github!