Reading message attributes


C: FETCH 4 6-7 FLAGS SIZE
S: * FETCH 4 FLAGS=SEEN,REPLIED SIZE=8341
S: * FETCH 6 FLAGS= SIZE=13862
S: * FETCH 7 FLAGS=SEEN SIZE=11802
S: +OK Ok

FETCH is a versatile command that retrieves message contents or attributes. FETCH is followed by whitespace-delimited words that enumerate message numbers whose attributes or contents the server should retrieve. The list of message numbers if followed by the list of attributes (or specific message content) to retrieve. When requesting more than one attribute, and/or attributes from more than one message, the server's response may list the messages and attributes in any order. The server may also list all requested attributes for each message in one * FETCH reply, or use a separate * FETCH reply for each attribute. The following response is also a valid reply in the previous example:


C: FETCH 4 6-7 FLAGS SIZE
S: * FETCH 7 SIZE=11802
S: * FETCH 6 SIZE=13862
S: * FETCH 4 SIZE=8341
S: * FETCH 4 FLAGS=SEEN,REPLIED
S: * FETCH 6 FLAGS=
S: * FETCH 7 FLAGS=SEEN
S: +OK Ok

The first word in each * FETCH single line reply is the message number, the remaining whitespace-delimited words specify the requested attributes. Each requested attribute is returned as a single, whitespace-delimited word in the * FETCH reply. For future expansion, both servers and clients should ignore attributes they do not recognize.

The following attributes are defined at this time:

UID

Request the message's unique identifier. The server assigns a unique identifier word to each message in a folder. The client should not attempt to interpret the unique identifier in any way, and treat it as an opaque text string. The only known property of the unique identifier is that no two messages in the same folder will ever have the same unique identifier. Example:


C: FETCH 9-10 UID
S: * FETCH 9 UID=1043320248/3456
S: * FETCH 10 UID=1043320248/3461
S: +OK FETCH completed

FLAGS

Each message has one or more message state flags. The following flags are currently defined:

DELETED

This message is marked for deletion.

REPLIED

This message has been replied to.

SEEN

The message's contents were previous read by FETCH CONTENTS at least once. The server automatically sets this flag after processing a FETCH CONTENTS command, but it can also be set or cleared manually by the STORE command.

DRAFT

This is a draft message.

MARKED

This messge is marked. MARKED is a generic flag that applications may use for their own purposes. The SEARCH command also uses this flag.

The server responds to a * FETCH by returning FLAGS=list, where list is a comma-separated list of flags that are set for this message. A message without any flags set results in an empty list, or the absence of the FLAGS=list response altogether.

KEYWORDS

The KEYWORDS attribute is available when KEYWORDS is listed as an SMAP1 capability (see SMAP connection negotiation). Each message may have one or more arbitrary tags associated with it. The SMAP1 server associates no special meaning to any keyword, except to note that it's there. The SMAP1 client is free to name keywords in any useful manner. The name of each keyword may contain any UTF-8 character except for a comma, or a control character.

Note

Certain punctuation characters should be avoided if interoperability with IMAP is desired. IMAP prohibits certain characters from appearing in keywords, namely: spaces, parenthesis, quotes, and the following characters: {, %, *, \, ]. Do not use these characters if IMAP interoperability is desired.

SIZE

The server's * FETCH reply contains SIZE=bytecount, where bytecount gives the estimated size of the message. This may not necessarily be an exact byte count. SMAP servers are permitted to provide a ballpark estimate of the message's size, if an exact byte count is unavailable.

INTERNALDATE

The server's * FETCH reply contains INTERNALDATE=rfcdate, where rfcdate gives the date and time the message was added to the folder. Note that this is not necessarily the contents of the message's Date: header. rfcdate uses the same RFC 2822 date/time format as the Date: header. Example:


C: FETCH 4 INTERNALDATE
S: * FETCH 4 "INTERNALDATE=Tue, 21 Jan 2003 20:57:48 -0500"
S: +OK Ok