class Net::IMAP::FetchData

Net::IMAP::FetchData represents the contents of a FETCH response.

Net::IMAP#fetch and Net::IMAP#uid_fetch both return an array of FetchData objects.

Fetch attributes¶ ↑

Each key of the attr hash is the data item name for the fetched value. Each data item represents a message attribute, part of one, or an interpretation of one. seqno is not a message attribute. Most message attributes are static and must never change for a given [server, account, mailbox, UIDVALIDITY, UID] tuple. A few message attributes can be dynamically changed, e.g. using the STORE command.

See [IMAP4rev1] §7.4.2 and [IMAP4rev2] §7.5.2 for full description of the standard fetch response data items, and Message envelope and body structure at Net::IMAP for other relevant RFCs.

Static fetch data items¶ ↑

The static data items defined by [IMAP4rev1] are:

"UID"

A number expressing the unique identifier of the message.

"BODY[]", "BODY[]<#{offset}>"

The [RFC5322] expression of the entire message, as a string.

If offset is specified, this returned string is a substring of the entire contents, starting at that origin octet. This means that BODY[]<0> MAY be truncated, but BODY[] is NEVER truncated.

Messages can be parsed using the “mail” gem.

Note

When fetching BODY.PEEK[#{specifier}], the data will be returned in BODY[#{specifier}], without the PEEK. This is true for all of the BODY[...] attribute forms.

"BODY[HEADER]", "BODY[HEADER]<#{offset}>"

The [RFC5322] header of the message.

Message headers can be parsed using the “mail” gem.

"BODY[HEADER.FIELDS (#{fields.join(" ")})]",

"BODY[HEADER.FIELDS (#{fields.join(" ")})]<#{offset}>"

When field names are given, the subset contains only the header fields that matches one of the names in the list. The field names are based on what was requested, not on what was returned.

"BODY[HEADER.FIELDS.NOT (#{fields.join(" ")})]",

"BODY[HEADER.FIELDS.NOT (#{fields.join(" ")})]<#{offset}>"

When the HEADER.FIELDS.NOT is used, the subset is all of the fields that do not match any names in the list.

"BODY[TEXT]", "BODY[TEXT]<#{offset}>"

The text body of the message, omitting the [RFC5322] header.

"BODY[#{part}]", "BODY[#{part}]<#{offset}>"

The text of a particular body section, if it was fetched.

Multiple part specifiers will be joined with ".". Numeric part specifiers refer to the MIME part number, counting up from 1. Messages that don’t use MIME, or MIME messages that are not multipart and don’t hold an encapsulated message, only have a part 1.

8-bit textual data is permitted if a [CHARSET] identifier is part of the body parameter parenthesized list for this section. See BodyTypeBasic.

MESSAGE/RFC822 or MESSAGE/GLOBAL message, or a subset of the header, if it was fetched.

"BODY[#{part}.HEADER]",

"BODY[#{part}.HEADER]<#{offset}>",

"BODY[#{part}.HEADER.FIELDS.NOT (#{fields.join(" ")})]",

"BODY[#{part}.HEADER.FIELDS.NOT (#{fields.join(" ")})]<#{offset}>",

"BODY[#{part}.TEXT]",

"BODY[#{part}.TEXT]<#{offset}>",

"BODY[#{part}.MIME]",

"BODY[#{part}.MIME]<#{offset}>"

HEADER, HEADER.FIELDS, HEADER.FIELDS.NOT, and TEXT can be prefixed by numeric part specifiers, if it refers to a part of type message/rfc822 or message/global.

MIME refers to the [MIME-IMB] header for this part.

"BODY"

A form of BODYSTRUCTURE, without any extension data.

"BODYSTRUCTURE"

Returns a BodyStructure object that describes the [MIME-IMB] body structure of a message, if it was fetched.

"ENVELOPE"

An Envelope object that describes the envelope structure of a message. See the documentation for Envelope for a description of the envelope structure attributes.

"INTERNALDATE"

The internal date and time of the message on the server. This is not the date and time in the [RFC5322] header, but rather a date and time which reflects when the message was received.

"RFC822.SIZE"

A number expressing the [RFC5322] size of the message.

Note

IMAP was originally developed for the older RFC-822 standard, and as a consequence several fetch items in IMAP incorporate “RFC822” in their name. With the exception of RFC822.SIZE, there are more modern replacements; for example, the modern version of RFC822.HEADER is BODY.PEEK[HEADER]. In all cases, “RFC822” should be interpreted as a reference to the updated [RFC5322] standard.

"RFC822"

Semantically equivalent to BODY[].

"RFC822.HEADER"

Semantically equivalent to BODY[HEADER].

"RFC822.TEXT"

Semantically equivalent to BODY[TEXT].

Note:

Additional static fields are defined in IMAP extensions and [IMAP4rev2], but Net::IMAP can’t parse them yet.

Dynamic message attributes¶ ↑

The only dynamic item defined by [IMAP4rev1] is:

"FLAGS"

An array of flags that are set for this message. System flags are symbols that have been capitalized by String#capitalize. Keyword flags are strings and their case is not changed.

IMAP extensions define new dynamic fields, e.g.:

"MODSEQ"

The modification sequence number associated with this IMAP message.

Requires the [CONDSTORE] server capability.

Note:

Additional dynamic fields are defined in IMAP extensions, but Net::IMAP can’t parse them yet.