RFC 1730
Internet Message Access Protocol - Version 4
6.4. Client Commands - Selected State In selected state, commands that manipulate messages in a mailbox are permitted. In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT), and the authenticated state commands (SELECT, EXAMINE, CREATE, DELETE, RENAME, SUBSCRIBE, UNSUBSCRIBE, LIST, LSUB, FIND ALL.MAILBOXES, FIND MAILBOXES, and APPEND), the following commands are valid in the selected state: CHECK, CLOSE, EXPUNGE, SEARCH, FETCH, PARTIAL, STORE, COPY, and UID.
6.4.1. CHECK Command Arguments: none Data: no specific data for this command Result: OK - check completed BAD - command unknown or arguments invalid The CHECK command requests a checkpoint of the currently selected mailbox. A checkpoint refers to any implementation-dependent housekeeping associated with the mailbox (e.g. resolving the server's in-memory state of the mailbox with the state on its disk) that is not normally executed as part of each command. A checkpoint may take a non-instantaneous amount of real time to complete. If a server implementation has no such housekeeping considerations, CHECK is equivalent to NOOP. There is no guarantee that an EXISTS untagged response will happen as a result of CHECK. NOOP, not CHECK, should be used for new mail polling. Example: C: FXXZ CHECK S: FXXZ OK CHECK Completed 6.4.2. CLOSE Command Arguments: none Data: no specific data for this command Result: OK - close completed, now in authenticated state NO - close failure: no mailbox selected BAD - command unknown or arguments invalid The CLOSE command permanently removes from the currently selected mailbox all messages that have the \Deleted flag set, and returns to authenticated state from selected state. No untagged EXPUNGE responses are sent. No messages are removed, and no error is given, if the mailbox is selected by an EXAMINE command or is otherwise selected read-only. Even when a mailbox is selected, it is not required to send a CLOSE command before a SELECT, EXAMINE, or LOGOUT command. The SELECT, EXAMINE, and LOGOUT commands implicitly close the currently selected mailbox without doing an expunge. However,
when many messages are deleted, a CLOSE-LOGOUT or CLOSE-SELECT
sequence is considerably faster than an EXPUNGE-LOGOUT or
EXPUNGE-SELECT because no untagged EXPUNGE responses (which the
client would probably ignore) are sent.
Example: C: A341 CLOSE
S: A341 OK CLOSE completed
6.4.3. EXPUNGE Command
Arguments: none
Data: untagged responses: EXPUNGE
Result: OK - expunge completed
NO - expunge failure: can't expunge (e.g. permission
denied)
BAD - command unknown or arguments invalid
The EXPUNGE command permanently removes from the currently
selected mailbox all messages that have the \Deleted flag set.
Before returning an OK to the client, an untagged EXPUNGE response
is sent for each message that is removed.
Example: C: A202 EXPUNGE
S: * 3 EXPUNGE
S: * 3 EXPUNGE
S: * 5 EXPUNGE
S: * 8 EXPUNGE
S: A202 OK EXPUNGE completed
Note: in this example, messages 3, 4, 7, and 11 had the
\Deleted flag set. See the description of the EXPUNGE
response for further explanation.
6.4.4. SEARCH Command Arguments: optional character set specification searching criteria (one or more) Data: mandatory untagged response: SEARCH Result: OK - search completed NO - search error: can't search that character set or criteria BAD - command unknown or arguments invalid The SEARCH command searches the mailbox for messages that match the given searching criteria. Searching criteria consist of one or more search keys. The untagged SEARCH response from the server contains a listing of message sequence numbers corresponding to those messages that match the searching criteria. When multiple keys are specified, the result is the intersection (AND function) of all the messages that match those keys. For example, the criteria DELETED FROM "SMITH" SINCE 1-Feb-1994 refers to all deleted messages from Smith that were placed in the mailbox since February 1, 1994. A search key may also be a parenthesized list of one or more search keys (e.g. for use with the OR and NOT keys). Server implementations MAY exclude [MIME-1] body parts with terminal content types other than TEXT and MESSAGE from consideration in SEARCH matching. The optional character set specification consists of the word "CHARSET" followed by a registered MIME character set. It indicates the character set of the strings that appear in the search criteria. [MIME-2] strings that appear in RFC 822/MIME message headers, and [MIME-1] content transfer encodings, MUST be decoded before matching. Except for US-ASCII, it is not required that any particular character set be supported. If the server does not support the specified character set, it MUST return a tagged NO response (not a BAD). In all search keys that use strings, a message matches the key if the string is a substring of the field. The matching is case-insensitive.
The defined search keys are as follows. Refer to the Formal
Syntax section for the precise syntactic definitions of the
arguments.
<message set> Messages with message sequence numbers
corresponding to the specified message sequence
number set
ALL All messages in the mailbox; the default initial
key for ANDing.
ANSWERED Messages with the \Answered flag set.
BCC <string> Messages that contain the specified string in the
envelope structure's BCC field.
BEFORE <date> Messages whose internal date is earlier than the
specified date.
BODY <string> Messages that contain the specified string in the
body of the message.
CC <string> Messages that contain the specified string in the
envelope structure's CC field.
DELETED Messages with the \Deleted flag set.
DRAFT Messages with the \Draft flag set.
FLAGGED Messages with the \Flagged flag set.
FROM <string> Messages that contain the specified string in the
envelope structure's FROM field.
HEADER <field-name> <string>
Messages that have a header with the specified
field-name (as defined in [RFC-822]) and that
contains the specified string in the [RFC-822]
field-body.
KEYWORD <flag> Messages with the specified keyword set.
LARGER <n> Messages with an RFC822.SIZE larger than the
specified number of octets.
NEW Messages that have the \Recent flag set but not the
\Seen flag. This is functionally equivalent to
"(RECENT UNSEEN)".
NOT <search-key>
Messages that do not match the specified search
key.
OLD Messages that do not have the \Recent flag set.
This is functionally equivalent to "NOT RECENT" (as
opposed to "NOT NEW").
ON <date> Messages whose internal date is within the
specified date.
OR <search-key1> <search-key2>
Messages that match either search key.
RECENT Messages that have the \Recent flag set.
SEEN Messages that have the \Seen flag set.
SENTBEFORE <date>
Messages whose [RFC-822] Date: header is earlier
than the specified date.
SENTON <date> Messages whose [RFC-822] Date: header is within the
specified date.
SENTSINCE <date>
Messages whose [RFC-822] Date: header is within or
later than the specified date.
SINCE <date> Messages whose internal date is within or later
than the specified date.
SMALLER <n> Messages with an RFC822.SIZE smaller than the
specified number of octets.
SUBJECT <string>
Messages that contain the specified string in the
envelope structure's SUBJECT field.
TEXT <string> Messages that contain the specified string in the
header or body of the message.
TO <string> Messages that contain the specified string in the
envelope structure's TO field.
UID <message set>
Messages with unique identifiers corresponding to
the specified unique identifier set.
UNANSWERED Messages that do not have the \Answered flag set.
UNDELETED Messages that do not have the \Deleted flag set.
UNDRAFT Messages that do not have the \Draft flag set.
UNFLAGGED Messages that do not have the \Flagged flag set.
UNKEYWORD <flag>
Messages that do not have the specified keyword
set.
UNSEEN Messages that do not have the \Seen flag set.
Example: C: A282 SEARCH FLAGGED SINCE 1-Feb-1994 NOT FROM "Smith"
S: * SEARCH 2 84 882
S: A282 OK SEARCH completed
6.4.5. FETCH Command
Arguments: message set
message data item names
Data: untagged responses: FETCH
Result: OK - fetch completed
NO - fetch error: can't fetch that data
BAD - command unknown or arguments invalid
The FETCH command retrieves data associated with a message in the
mailbox. The data items to be fetched may be either a single atom
or a parenthesized list. The currently defined data items that
can be fetched are:
ALL Macro equivalent to: (FLAGS INTERNALDATE
RFC822.SIZE ENVELOPE)
BODY Non-extensible form of BODYSTRUCTURE.
BODY[<section>]
The text of a particular body section. The section
specification is a set of one or more part numbers
delimited by periods.
Single-part messages only have a part 1.
Multipart messages are assigned consecutive part
numbers, as they occur in the message. If a
particular part is of type message or multipart,
its parts must be indicated by a period followed by
the part number within that nested multipart part.
It is not permitted to fetch a multipart part
itself, only its individual members.
A part of type MESSAGE and subtype RFC822 also has
nested parts. These are the parts of the MESSAGE
part's body. Nested part 0 of a part of type
MESSAGE and subtype RFC822 is the [RFC-822] header
of the message.
Every message has at least one part.
Here is an example of a complex message
with its associated section
specifications:
0 ([RFC-822] header of the message)
MULTIPART/MIXED
1 TEXT/PLAIN
2 APPLICATION/OCTET-STREAM
3 MESSAGE/RFC822
3.0 ([RFC-822] header of the message)
3.1 TEXT/PLAIN
3.2 APPLICATION/OCTET-STREAM
MULTIPART/MIXED
4.1 IMAGE/GIF
4.2 MESSAGE/RFC822
4.2.0 ([RFC-822] header of the message)
4.2.1 TEXT/PLAIN
MULTIPART/ALTERNATIVE
4.2.2.1 TEXT/PLAIN
4.2.2.2 TEXT/RICHTEXT
Note that there is no section
specification for the Multi-part parts
(no section 4 or 4.2.2).
The \Seen flag is implicitly set; if this causes
the flags to change they should be included as part
of the fetch responses.
BODY.PEEK[<section>]
An alternate form of BODY[section] that does not
implicitly set the \Seen flag.
BODYSTRUCTURE The [MIME-1] body structure of the message. This
is computed by the server by parsing the [MIME-1]
header lines.
ENVELOPE The envelope structure of the message. This is
computed by the server by parsing the [RFC-822]
header into the component parts, defaulting various
fields as necessary.
FAST Macro equivalent to: (FLAGS INTERNALDATE
RFC822.SIZE)
FLAGS The flags that are set for this message.
FULL Macro equivalent to: (FLAGS INTERNALDATE
RFC822.SIZE ENVELOPE BODY)
INTERNALDATE The date and time of final delivery of the message
as defined by RFC 821.
RFC822 The message in [RFC-822] format. The \Seen flag is
implicitly set; if this causes the flags to change
they should be included as part of the fetch
responses. This is the concatenation of
RFC822.HEADER and RFC822.TEXT.
RFC822.PEEK An alternate form of RFC822 that does not
implicitly set the \Seen flag.
RFC822.HEADER The [RFC-822] format header of the message as
stored on the server including the delimiting blank
line between the header and the body.
RFC822.HEADER.LINES <header_list>
All header lines (including continuation lines) of
the [RFC-822] format header of the message with a
field-name (as defined in [RFC-822]) that matches
any of the strings in header_list. The matching is
case-insensitive but otherwise exact. The
delimiting blank line between the header and the
body is always included.
RFC822.HEADER.LINES.NOT <header_list>
All header lines (including continuation lines) of
the [RFC-822] format header of the message with a
field-name (as defined in [RFC-822]) that does not
match any of the strings in header_list. The
matching is case-insensitive but otherwise exact.
The delimiting blank line between the header and
the body is always included.
RFC822.SIZE The number of octets in the message, as expressed
in [RFC-822] format.
RFC822.TEXT The text body of the message, omitting the
[RFC-822] header. The \Seen flag is implicitly
set; if this causes the flags to change they should
be included as part of the fetch responses.
RFC822.TEXT.PEEK
An alternate form of RFC822.TEXT that does not
implicitly set the \Seen flag.
UID The unique identifier for the message.
Example: C: A654 FETCH 2:4 (FLAGS RFC822.HEADER.LINES (DATE FROM))
S: * 2 FETCH ....
S: * 3 FETCH ....
S: * 4 FETCH ....
S: A003 OK FETCH completed
6.4.6. PARTIAL Command
Arguments: message sequence number
message data item name
position of first octet
number of octets
Data: untagged responses: FETCH
Result: OK - partial completed
NO - partial error: can't fetch that data
BAD - command unknown or arguments invalid
The PARTIAL command is equivalent to the associated FETCH command,
with the added functionality that only the specified number of
octets, beginning at the specified starting octet, are returned.
Only a single message can be fetched at a time. The first octet
of a message, and hence the minimum for the starting octet, is
octet 1.
The following FETCH items are valid data for PARTIAL: RFC822,
RFC822.HEADER, RFC822.TEXT, BODY[section], as well as any .PEEK
forms of these.
Any partial fetch that attempts to read beyond the end of the text
is truncated as appropriate. If the starting octet is beyond the
end of the text, an empty string is returned.
The data are returned with the FETCH response. There is no
indication of the range of the partial data in this response. It
is not possible to stream multiple PARTIAL commands of the same
data item without processing and synchronizing at each step, since
streamed commands may be executed out of order.
There is no requirement that partial fetches follow any sequence.
For example, if a partial fetch of octets 1 through 10000 breaks
in an awkward place for BASE64 decoding, it is permitted to
continue with a partial fetch of 9987 through 19987, etc.
The handling of the \Seen flag is the same as in the associated
FETCH command.
Example: C: A005 PARTIAL 4 RFC822 1 1024
S: * 1 FETCH (RFC822 {1024}
S: Return-Path: <gray@cac.washington.edu>
S: ...
S: ......... FLAGS (\Seen))
S: A005 OK PARTIAL completed
6.4.7. STORE Command
Arguments: message set
message data item name
value for message data item
Data: untagged responses: FETCH
Result: OK - store completed
NO - store error: can't store that data
BAD - command unknown or arguments invalid
The STORE command alters data associated with a message in the
mailbox. Normally, STORE will return the updated value of the
data with an untagged FETCH response. A suffix of ".SILENT" in
the data item name prevents the untagged FETCH, and the server
should assume that the client has determined the updated value
itself or does not care about the updated value.
The currently defined data items that can be stored are:
FLAGS <flag list>
Replace the flags for the message with the
argument. The new value of the flags are returned
as if a FETCH of those flags was done.
FLAGS.SILENT <flag list>
Equivalent to FLAGS, but without returning a new
value.
+FLAGS <flag list>
Add the argument to the flags for the message. The
new value of the flags are returned as if a FETCH
of those flags was done.
+FLAGS.SILENT <flag list>
Equivalent to +FLAGS, but without returning a new
value.
-FLAGS <flag list>
Remove the argument from the flags for the message.
The new value of the flags are returned as if a
FETCH of those flags was done.
-FLAGS.SILENT <flag list>
Equivalent to -FLAGS, but without returning a new
value.
Example: C: A003 STORE 2:4 +FLAGS (\Deleted)
S: * 2 FETCH FLAGS (\Deleted \Seen)
S: * 3 FETCH FLAGS (\Deleted)
S: * 4 FETCH FLAGS (\Deleted \Flagged \Seen)
S: A003 OK STORE completed
6.4.8. COPY Command Arguments: message set mailbox name Data: no specific data for this command Result: OK - copy completed NO - copy error: can't copy those messages or to that name BAD - command unknown or arguments invalid The COPY command copies the specified message(s) to the specified destination mailbox. The flags and internal date of the message(s) SHOULD be preserved in the copy. If the destination mailbox does not exist, a server SHOULD return an error. It SHOULD NOT automatically create the mailbox. Unless it is certain that the destination mailbox can not be created, the server MUST send the response code "[TRYCREATE]" as the prefix of the text of the tagged NO response. This gives a hint to the client that it can attempt a CREATE command and retry the COPY if the CREATE is successful. If the COPY command is unsuccessful for any reason, server implementations MUST restore the destination mailbox to its state before the COPY attempt. Example: C: A003 COPY 2:4 MEETING S: A003 OK COPY completed 6.4.9. UID Command Arguments: command name command arguments Data: untagged responses: FETCH, SEARCH Result: OK - UID command completed NO - UID command error BAD - command unknown or arguments invalid The UID command has two forms. In the first form, it takes as its arguments a COPY, FETCH, or STORE command with arguments appropriate for the associated command. However, the numbers in the message set argument are unique identifiers instead of message sequence numbers.
In the second form, the UID command takes a SEARCH command with
SEARCH command arguments. The interpretation of the arguments is
the same as with SEARCH; however, the numbers returned in a SEARCH
response for a UID SEARCH command are unique identifiers instead
of message sequence numbers. For example, the command UID SEARCH
1:100 UID 443:557 returns the unique identifiers corresponding to
the intersection of the message sequence number set 1:100 and the
UID set 443:557.
A unique identifier of a message is a number, and is guaranteed
not to refer to any other message in the mailbox. Unique
identifiers are assigned in a strictly ascending fashion for each
message added to the mailbox. Unlike message sequence numbers,
unique identifiers persist across sessions. This permits a client
to resynchronize its state from a previous session with the server
(e.g. disconnected or offline access clients); this is discussed
further in [IMAP-DISC].
Associated with every mailbox is a unique identifier validity
value, which is sent in an UIDVALIDITY response code in an OK
untagged response at message selection time. If unique
identifiers from an earlier session fail to persist to this
session, the unique identifier validity value MUST be greater than
in the earlier session.
Note: An example of a good value to use for the unique
identifier validity value would be a 32-bit
representation of the creation date/time of the mailbox.
It is alright to use a constant such as 1, but only if
it guaranteed that unique identifers will never be
reused, even in the case of a mailbox being deleted and
a new mailbox by the same name created at some future
time.
Message set ranges are permitted; however, there is no guarantee
that unique identifiers be contiguous. A non-existent unique
identifier within a message set range is ignored without any error
message generated.
The number after the "*" in an untagged FETCH response is always a
message sequence number, not a unique identifier, even for a UID
command response. However, server implementations MUST implicitly
include the UID message data item as part of any FETCH response
caused by a UID command, regardless of whether UID was specified
as a message data item to the FETCH.
Example: C: A003 UID FETCH 4827313:4828442 FLAGS
S: * 23 FETCH (FLAGS (\Seen) UID 4827313)
S: * 24 FETCH (FLAGS (\Seen) UID 4827943)
S: * 25 FETCH (FLAGS (\Seen) UID 4828442)
S: A999 UID FETCH completed
6.5. Client Commands - Experimental/Expansion
6.5.1. X<atom> Command
Arguments: implementation defined
Data: implementation defined
Result: OK - command completed
NO - failure
BAD - command unknown or arguments invalid
Any command prefixed with an X is an experimental command.
Commands which are not part of this specification, or a standard
or standards-track revision of this specification, MUST use the X
prefix.
Any added untagged responses issued by an experimental command
MUST also be prefixed with an X. Server implementations MUST NOT
send any such untagged responses, unless the client requested it
by issuing the associated experimental command.
Example: C: a441 CAPABILITY
S: * CAPABILITY IMAP4 XPIG-LATIN
S: a441 OK CAPABILITY completed
C: A442 XPIG-LATIN
S: * XPIG-LATIN ow-nay eaking-spay ig-pay atin-lay
S: A442 OK XPIG-LATIN ompleted-cay
7. Server Responses Server responses are in three forms: status responses, server data, and command continuation request. Server response data, identified by "Data:" in the response descriptions below, are described by function, not by syntax. The precise syntax of server response data is described in the Formal Syntax section. The client MUST be prepared to accept any response at all times. Status responses that are tagged indicate the completion result of a client command, and have a tag matching the command. Some status responses, and all server data, are untagged. An untagged response is indicated by the token "*" instead of a tag. Untagged status responses indicate server greeting, or server status that does not indicate the completion of a command. For historical reasons, untagged server data responses are also called "unsolicited data", although strictly speaking only unilateral server data is truly "unsolicited". Certain server data MUST be recorded by the client when it is received; this is noted in the description of that data. Such data conveys critical information which affects the interpretation of all subsequent commands and responses (e.g. updates reflecting the creation or destruction of messags). Other server data SHOULD be recorded for later reference; if the client does not need to record the data, or if recording the data has no obvious purpose (e.g. a SEARCH response when no SEARCH command is in progress), the data SHOULD be ignored. An example of unilateral untagged responses occurs when the IMAP connection is in selected state. In selected state, the server checks the mailbox for new messages as part of the execution of each command. If new messages are found, the server sends untagged EXISTS and RECENT responses reflecting the new size of the mailbox. Server implementations that offer multiple simultaneous access to the same mailbox should also send appropriate unilateral untagged FETCH and EXPUNGE responses if another agent changes the state of any message flags or expunges any messages. Command continuation request responses use the token "+" instead of a tag. These responses are sent by the server to indicate acceptance of an incomplete client command and readiness for the remainder of the command.
7.1. Server Responses - Status Responses Status responses may include an optional response code. A response code consists of data inside square brackets in the form of an atom, possibly followed by a space and arguments. The response code contains additional information or status codes for client software beyond the OK/NO/BAD condition, and are defined when there is a specific action that a client can take based upon the additional information. The currently defined response codes are: ALERT The human-readable text contains a special alert that MUST be presented to the user in a fashion that calls the user's attention to the message. PARSE The human-readable text represents an error in parsing the [RFC-822] or [MIME-1] headers of a message in the mailbox. PERMANENTFLAGS Followed by a parenthesized list of flags, indicates which of the known flags that the client may change permanently. Any flags that are in the FLAGS untagged response, but not the PERMANENTFLAGS list, can not be set permanently. If the client attempts to STORE a flag that is not in the PERMANENTFLAGS list, the server will either reject it with a NO reply or store the state for the remainder of the current session only. The PERMANENTFLAGS list may also include the special flag \*, which indicates that it is possible to create new keywords by attempting to store those flags in the mailbox. READ-ONLY The mailbox is selected read-only, or its access while selected has changed from read-write to read-only. READ-WRITE The mailbox is selected read-write, or its access while selected has changed from read-only to read-write. TRYCREATE An APPEND or COPY attempt is failing because the target mailbox does not exist (as opposed to some other reason). This is a hint to the client that the operation may succeed if the mailbox is first created by the CREATE command.
UIDVALIDITY Followed by a decimal number, indicates the unique
identifier validity value. See the description of
the UID command for more detail.
UNSEEN Followed by a decimal number, indicates the number
of the first message without the \Seen flag set.
Additional response codes defined by particular client or server
implementations should be prefixed with an "X" until they are
added to a revision of this protocol. Client implementations
should ignore response codes that they do not recognize.
7.1.1. OK Response
Data: optional response code
human-readable text
The OK response indicates an information message from the server.
When tagged, it indicates successful completion of the associated
command. The human-readable text may be presented to the user as
an information message. The untagged form indicates an
information-only message; the nature of the information may be
indicated by a response code.
The untagged form is also used as one of three possible greetings
at session startup. It indicates that the session is not yet
authenticated and that a LOGIN command is needed.
Example: S: * OK IMAP4 server ready
C: A001 LOGIN fred blurdybloop
S: * OK [ALERT] System shutdown in 10 minutes
S: A001 OK LOGIN Completed
7.1.2. NO Response
Data: optional response code
human-readable text
The NO response indicates an operational error message from the
server. When tagged, it indicates unsuccessful completion of the
associated command. The untagged form indicates a warning; the
command may still complete successfully. The human-readable text
describes the condition.
Example: C: A222 COPY 1:2 owatagusiam
S: * NO Disk is 98% full, please delete unnecessary data
S: A222 OK COPY completed
C: A222 COPY 3:200 blurdybloop
S: * NO Disk is 98% full, please delete unnecessary data
S: * NO Disk is 99% full, please delete unnecessary data
S: A222 NO COPY failed: disk is full
7.1.3. BAD Response
Data: optional response code
human-readable text
The BAD response indicates an error message from the server. When
tagged, it reports a protocol-level error in the client's command;
the tag indicates the command that caused the error. The untagged
form indicates a protocol-level error for which the associated
command can not be determined; it may also indicate an internal
server failure. The human-readable text describes the condition.
Example: C: ...very long command line...
S: * BAD Command line too long
C: ...empty line...
S: * BAD Empty command line
C: A443 EXPUNGE
S: * BAD Disk crash, attempting salvage to a new disk!
S: * OK Salvage successful, no data lost
S: A443 OK Expunge completed
7.1.4. PREAUTH Response
Data: optional response code
human-readable text
The PREAUTH response is always untagged, and is one of three
possible greetings at session startup. It indicates that the
session has already been authenticated by external means and thus
no LOGIN command is needed.
Example: S: * PREAUTH IMAP4 server ready and logged in as Smith
7.1.5. BYE Response Data: optional response code human-readable text The BYE response is always untagged, and indicates that the server is about to close the connection. The human-readable text may be displayed to the user in a status report by the client. The BYE response may be sent as part of a normal logout sequence, or as a panic shutdown announcement by the server. It is also used by some server implementations as an announcement of an inactivity autologout. This response is also used as one of three possible greetings at session startup. It indicates that the server is not willing to accept a session from this client. Example: S: * BYE Autologout; idle for too long 7.2. Server Responses - Server and Mailbox Status These responses are always untagged. This is how server data are transmitted from the server to the client, often as a result of a command with the same name. 7.2.1. CAPABILITY Response Data: capability listing The CAPABILITY response occurs as a result of a CAPABILITY command. The capability listing contains a space-separated listing of capability names that the server supports. The first name in the capability listing MUST be the atom "IMAP4". A capability name other than IMAP4 indicates that the server supports an extension, revision, or amendment to the IMAP4 protocol. Server responses MUST conform to this document until the client issues a command that uses the associated capability. Capability names MUST either begin with "X" or be standard or standards-track IMAP4 extensions, revisions, or amendments registered with IANA. A server MUST NOT offer unregistered or non-standard capability names, unless such names are prefixed with an "X".
Client implementations SHOULD NOT require any capability name
other than "IMAP4", and MUST ignore any unknown capability names.
Example: S: * CAPABILITY IMAP4 XPIG-LATIN
7.2.2. LIST Response
Data: name attributes
hierarchy delimiter
name
The LIST response occurs as a result of a LIST command. It
returns a single name that matches the LIST specification. There
may be multiple LIST responses for a single LIST command.
Four name attributes are defined:
\Noinferiors It is not possible for any child levels of
hierarchy to exist under this name; no child levels
exist now and none can be created in the future.
\Noselect It is not possible to use this name as a selectable
mailbox.
\Marked The mailbox has been marked "interesting" by the
server; the mailbox probably contains messages that
have been added since the last time the mailbox was
selected.
\Unmarked The mailbox does not contain any additional
messages since the last time the mailbox was
selected.
If it is not feasible for the server to determine whether the
mailbox is "interesting" or not, or if the name is a \Noselect
name, the server should not send either \Marked or \Unmarked.
The hierarchy delimiter is a character used to delimit levels of
hierarchy in a mailbox name. A client may use it to create child
mailboxes, and to search higher or lower levels of naming
hierarchy. All children of a top-level hierarchy node must use
the same separator character. A NIL hierarchy delimiter means
that no hierarchy exists; the name is a "flat" name.
The name represents an unambiguous left-to-right hierarchy, and
MUST be valid for use as a reference in LIST and LSUB commands.
Unless \Noselect is indicated, the name must also be valid as an
argument for commands, such as SELECT, that accept mailbox names.
Example: S: * LIST (\Noselect) "/" ~/Mail/foo
7.2.3. LSUB Response
Data: name attributes
hierarchy delimiter
name
The LSUB response occurs as a result of an LSUB command. It
returns a single name that matches the LSUB specification. There
may be multiple LSUB responses for a single LSUB command. The
data is identical in format to the LIST response.
Example: S: * LSUB () "." #news.comp.mail.misc
7.2.4. SEARCH Response
Data: zero or more numbers
The SEARCH response occurs as a result of a SEARCH or UID SEARCH
command. The number(s) refer to those messages that match the
search criteria. For SEARCH, these are message sequence numbers;
for UID SEARCH, these are unique identifiers. Each number is
delimited by a space.
Example: S: * SEARCH 2 3 6
7.2.5. FLAGS Response
Data: flag parenthesized list
The FLAGS response occurs as a result of a SELECT or EXAMINE
command. The flag parenthesized list identifies the flags (at a
minimum, the system-defined flags) that are applicable for this
mailbox. Flags other than the system flags may also exist,
depending on server implementation.
The update from the FLAGS response MUST be recorded by the client.
Example: S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
7.3. Server Responses - Message Status These responses are always untagged. This is how message data are transmitted from the server to the client, often as a result of a command with the same name. Immediately following the "*" token is a number that represents either a message sequence number or a message count. 7.3.1. EXISTS Response Data: none The EXISTS response reports the number of messages in the mailbox. This response occurs as a result of a SELECT or EXAMINE command, and if the size of the mailbox changes (e.g. new mail). The update from the EXISTS response MUST be recorded by the client. Example: S: * 23 EXISTS 7.3.2. RECENT Response Data: none The RECENT response reports the number of messages that have arrived since the previous time a SELECT command was done on this mailbox. This response occurs as a result of a SELECT or EXAMINE command, and if the size of the mailbox changes (e.g. new mail). The update from the RECENT response MUST be recorded by the client. Example: S: * 5 RECENT 7.3.3. EXPUNGE Response Data: none The EXPUNGE response reports that the specified message sequence number has been permanently removed from the mailbox. The message sequence number for each successive message in the mailbox is immediately decremented by 1, and this decrement is reflected in message sequence numbers in subsequent responses (including other untagged EXPUNGE responses).
As a result of the immediate decrement rule, message sequence
numbers that appear in a set of successive EXPUNGE responses
depend upon whether the messages are removed starting from lower
numbers to higher numbers, or from higher numbers to lower
numbers. For example, if the last 5 messages in a 9-message
mailbox are expunged; a "lower to higher" server will send five
untagged EXPUNGE responses for message sequence number 5, whereas
a "higher to lower server" will send successive untagged EXPUNGE
responses for message sequence numbers 9, 8, 7, 6, and 5.
An EXPUNGE response MUST NOT be sent when no command is in
progress; nor while responding to a FETCH, STORE, or SEARCH
command. This rule is necessary to prevent a loss of
synchronization of message sequence numbers between client and
server.
The update from the EXPUNGE response MUST be recorded by the
client.
Example: S: * 44 EXPUNGE
7.3.4. FETCH Response
Data: message data
The FETCH response returns data about a message to the client.
The data are pairs of data item names and their values in
parentheses. This response occurs as the result of a FETCH or
STORE command, as well as by unilateral server decision (e.g. flag
updates).
The current data items are:
BODY A form of BODYSTRUCTURE without extension data.
BODY[section] A string expressing the body contents of the
specified section. The string should be
interpreted by the client according to the content
transfer encoding, body type, and subtype.
8-bit textual data is permitted if a character set
identifier is part of the body parameter
parenthesized list for this section.
Non-textual data such as binary data must be
transfer encoded into a textual form such as BASE64
prior to being sent to the client. To derive the
original binary data, the client must decode the
transfer encoded string.
BODYSTRUCTURE A parenthesized list that describes the body
structure of a message. This is computed by the
server by parsing the [RFC-822] header and body
into the component parts, defaulting various fields
as necessary.
Multiple parts are indicated by parenthesis
nesting. Instead of a body type as the first
element of the parenthesized list there is a nested
body. The second element of the parenthesized list
is the multipart subtype (mixed, digest, parallel,
alternative, etc.).
Extension data follows the multipart subtype.
Extension data is never returned with the BODY
fetch, but may be returned with a BODYSTRUCTURE
fetch. Extension data, if present, must be in the
defined order.
The extension data of a multipart body part are in
the following order:
body parameter parenthesized list
A parenthesized list of attribute/value pairs
[e.g. (foo bar baz rag) where "bar" is the value
of "foo" and "rag" is the value of "baz"] as
defined in [MIME-1].
Any following extension data are not yet defined in
this version of the protocol. Such extension data
may consist of zero or more NILs, strings, numbers,
or potentially nested parenthesized lists of such
data. Client implementations that do a
BODYSTRUCTURE fetch MUST be prepared to accept such
extension data. Server implementations MUST NOT
send such extension data until it has been defined
by a revision of this protocol.
The basic fields of a non-multipart body part are
in the following order:
body type
A string giving the content type name as defined
in [MIME-1].
body subtype
A string giving the content subtype name as
defined in [MIME-1].
body parameter parenthesized list
A parenthesized list of attribute/value pairs
[e.g. (foo bar baz rag) where "bar" is the value
of "foo" and "rag" is the value of "baz"] as
defined in [MIME-1].
body id
A string giving the content id as defined in
[MIME-1].
body description
A string giving the content description as
defined in [MIME-1].
body encoding
A string giving the content transfer encoding as
defined in [MIME-1].
body size
A number giving the size of the body in octets.
Note that this size is the size in its transfer
encoding and not the resulting size after any
decoding.
A body type of type MESSAGE and subtype RFC822
contains, immediately after the basic fields, the
envelope structure, body structure, and size in
text lines of the encapsulated message.
A body type of type TEXT contains, immediately
after the basic fields, the size of the body in
text lines. Note that this size is the size in its
transfer encoding and not the resulting size after
any decoding.
Extension data follows the basic fields and the
type-specific fields listed above. Extension data
is never returned with the BODY fetch, but may be
returned with a BODYSTRUCTURE fetch. Extension
data, if present, must be in the defined order.
The extension data of a non-multipart body part are
in the following order:
body MD5
A string giving the content MD5 value as defined
in [MIME-1].
Any following extension data are not yet defined in
this version of the protocol, and would be as
described above under multipart extension data.
ENVELOPE A parenthesized list that describes the envelope
structure of a message. This is computed by the
server by parsing the [RFC-822] header into the
component parts, defaulting various fields as
necessary.
The fields of the envelope structure are in the
following order: date, subject, from, sender,
reply-to, to, cc, bcc, in-reply-to, and message-id.
The date, subject, in-reply-to, and message-id
fields are strings. The from, sender, reply-to,
to, cc, and bcc fields are parenthesized lists of
address structures.
An address structure is a parenthesized list that
describes an electronic mail address. The fields
of an address structure are in the following order:
personal name, [SMTP] at-domain-list (source
route), mailbox name, and host name.
[RFC-822] group syntax is indicated by a special
form of address structure in which the host name
field is NIL. If the mailbox name field is also
NIL, this is an end of group marker (semi-colon in
RFC 822 syntax). If the mailbox name field is
non-NIL, this is a start of group marker, and the
mailbox name field holds the group name phrase.
Any field of an envelope or address structure that
is not applicable is presented as NIL. Note that
the server must default the reply-to and sender
fields from the from field; a client is not
expected to know to do this.
FLAGS A parenthesized list of flags that are set for this
message. This may include keywords as well as the
following system flags:
\Seen Message has been read
\Answered Message has been answered
\Flagged Message is "flagged" for urgent/special
attention
\Deleted Message is "deleted" for removal by
later EXPUNGE
\Draft Message has not completed composition
(marked as a draft).
as well as the following special flag, which may be
fetched but not stored:
\Recent Message has arrived since the previous
time this mailbox was selected.
INTERNALDATE A string containing the date and time of final
delivery of the message as defined by [SMTP].
RFC822 A string expressing the message in [RFC-822]
format. The header portion of the message must be
7-bit. 8-bit characters are permitted only in the
non-header portion of the message only if there are
[MIME-1] data in the message that identify the
character set of the message.
RFC822.HEADER A string expressing the [RFC-822] format header of
the message, including the delimiting blank line
between the header and the body. The entire string
must be 7-bit; 8-bit characters are not permitted
in headers. RFC822.HEADER is used to return data
for the RFC822.HEADER, RFC822.HEADER.LINES, and
RFC822.HEADER.LINES.NOT FETCH data items. Note
that a blank line is always included regardless of
header line restrictions.
RFC822.SIZE A number expressing the number of octets in the
message in [RFC-822] format.
RFC822.TEXT A string expressing the text body of the message,
omitting the [RFC-822] header. 8-bit characters
are permitted only if there are [MIME-1] data in
the message that identify the character set of the
message.
UID A number expressing the unique identifier of the
message.
Example: S: * 23 FETCH (FLAGS (\Seen) RFC822.SIZE 44827)
7.3.5. Obsolete Responses
In addition to the responses listed in here, client implementations
MUST accept and implement the obsolete responses described in
Appendix B.
7.4. Server Responses - Command Continuation Request
The command completion request response is indicated by a "+" token
instead of a tag. This form of response indicates that the server is
ready to accept the continuation of a command from the client. The
remainder of this response is a line of text.
This response is used in the AUTHORIZATION command to transmit server
data to the client, and request additional client data. This
response is also used if an argument to any command is a literal.
The client is not permitted to send the octets of the literal unless
the server indicates that it expects it. This permits the server to
process commands and reject errors on a line-by-line basis. The
remainder of the command, including the CRLF that terminates a
command, follows the octets of the literal. If there are any
additional command arguments the literal octets are followed by a
space and those arguments.
Example: C: A001 LOGIN {11}
S: + Ready for additional command text
C: FRED FOOBAR {7}
S: + Ready for additional command text
C: fat man
S: A001 OK LOGIN completed
C: A044 BLURDYBLOOP {102856}
S: A044 BAD No such command as "BLURDYBLOOP"
(next page on part 3)
