<<< Previous | Simple Mail Access Protocol, Version 1 | Next >>>

# 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

<<< Previous | Home | Next >>>
Using Folders | Up | Reading message contents