Network Working Group M. Crispin Request for Comments: 1730 University of Washington Category: Standards Track December 1994
IMAP4 includes operations for creating, deleting, and renaming mailboxes; checking for new messages; permanently removing messages; setting and clearing flags; RFC 822 and MIME parsing; searching; and selective fetching of message attributes, texts, and portions thereof. Messages in IMAP4 are accessed by the use of numbers. These numbers are either message sequence numbers (relative position from 1 to the number of messages in the mailbox) or unique identifiers (immutable, strictly ascending values assigned to each message, but which are not necessarily contiguous).
IMAP4 supports a single server. A mechanism for supporting multiple IMAP4 servers is discussed in [IMSP].
IMAP4 does not specify a means of posting mail; this function is handled by a mail transfer protocol such as [SMTP].
IMAP4 is designed to be upwards compatible from the [IMAP2] protocol. Compatibility issues are discussed in [IMAP-COMPAT].
Sections 6, 7, and 9 describe the IMAP commands, responses, and syntax, respectively. The relationships among these are such that it is almost impossible to understand any of them separately. In particular, one should not attempt to deduce command syntax from the command section alone; one should instead refer to the formal syntax section.
All interactions transmitted by client and server are in the form of lines; that is, strings that end with a CRLF. The protocol receiver of an IMAP4 client or server is either reading a line, or is reading a sequence of octets with a known count followed by a line.
There are two cases in which a line from the client does not represent a complete command. In one case, a command argument is quoted with an octet count (see the description of literal in String under Data Formats); in the other case, the command arguments require server feedback (see the AUTHENTICATE command). In either case, the server sends a command continuation request response if it is ready for the octets (if appropriate) and the remainder of the command. This response is prefixed with the token "+".
Note: If, instead, the server detected an error in the command, it sends a BAD completion response with tag matching the command (as described below) to reject the command and prevent the client from sending any more of the command.
It is also possible for the server to send a completion response for some other command (if multiple commands are in progress), or untagged data. In either case, the command continuation request is still pending; the client takes the appropriate action for the response, and reads another response from the server.
The protocol receiver of an IMAP4 server reads a command line from the client, parses the command and its arguments, and transmits server data and a server command completion result response.
Server data may be sent as a result of a client command, or may be sent unilaterally by the server. There is no syntactic difference between server data that resulted from a specific command and server data that were sent unilaterally.
The server completion result response indicates the success or failure of the operation. It is tagged with the same tag as the client command which began the operation. Thus, if more than one
The protocol receiver of an IMAP4 client reads a response line from the server. It then takes action on the response based upon the first token of the response, which may be a tag, a "*", or a "+". As described above.
A client MUST be prepared to accept any server response at all times. This includes server data that it may not have requested. Server data SHOULD be recorded, so that the client can reference its recorded copy rather than sending a command to the server to request the data. In the case of certain server data, recording the data is mandatory.
This topic is discussed in greater detail in the Server Responses section.
+--------------------------------------+
|initial connection and server greeting|
+--------------------------------------+
|| (1) || (2) || (3)
VV || ||
+-----------------+ || ||
|non-authenticated| || ||
+-----------------+ || ||
|| (7) || (4) || ||
|| VV VV ||
|| +----------------+ ||
|| | authenticated |<=++ ||
|| +----------------+ || ||
|| || (7) || (5) || (6) ||
|| || VV || ||
|| || +--------+ || ||
|| || |selected|==++ ||
|| || +--------+ ||
|| || || (7) ||
VV VV VV VV
+--------------------------------------+
| logout and close connection |
+--------------------------------------+
(1) connection without pre-authentication (OK
greeting) (2) pre-authenticated connection
(PREAUTH greeting) (3) rejected connection (BYE
greeting)
(4) successful LOGIN or AUTHENTICATE command
(5) successful SELECT or EXAMINE command
(6) CLOSE command, or failed SELECT or EXAMINE
command (7) LOGOUT command, server shutdown, or
connection closed
A literal is a sequence of zero or more octets (including CR and LF), prefix-quoted with an octet count in the form of an open brace ("{"), the number of octets, close brace ("}"), and CRLF. In the case of literals transmitted from server to client, the CRLF is immediately followed by the octet data. In the case of literals transmitted from client to server, the client must wait to receive a command continuation request (described later in this document) before sending the octet data (and the remainder of the command).
A quoted string is a sequence of zero or more 7-bit characters, excluding CR and LF, with double quote (<">) characters at each end.
The empty string is respresented as either "" (a quoted string with zero characters between double quotes) or as {0} followed by CRLF (a literal with an octet count of 0).
Note: Even if the octet count is 0, a client
transmitting a literal must wait to receive a
command continuation
request.
Although a BINARY body encoding is defined, unencoded binary strings are not permitted. A "binary string" is any string with NUL characters. Implementations MUST encode binary data into a textual form such as BASE64 before transmitting the data. A string with an excessive amount of CTL characters may also be considered to be binary, although this is not required.
The empty list is represented as () -- a parenthesized list with no members.
Regardless of what implementation decisions a client may take on remembering data from the server, a client implementation MUST record mailbox size updates. It MUST NOT assume that any command after initial mailbox selection will return the size of the mailbox.
Command arguments, identified by "Arguments:" in the command descriptions below, are described by function, not by syntax. The precise syntax of command arguments is described in the Formal Syntax section.
Some commands cause specific server data to be returned; these are identified by "Data:" in the command descriptions below. See the response descriptions in the Responses section for information on these responses, and the Formal Syntax section for the precise syntax of these responses. It is possible for server data to be transmitted as a result of any command; thus, commands that do not specifically require server data specify "no specific data for this command" instead of "none".
The "Result:" in the command description refers to the possible tagged status responses to a command, and any special interpretation of these status responses.
Data: mandatory untagged response: CAPABILITY
Result: OK - capability completed
BAD - command unknown or arguments invalid
The CAPABILITY command requests a listing of capabilities that the server supports. The server MUST send a single untagged CAPABILITY response with "IMAP4" as the first listed capability before the (tagged) OK response. This listing of capabilities is not dependent upon connection state or user. It is therefore not necessary to issue a CAPABILITY command more than once in a session.
Example: C: abcd CAPABILITY
S: * CAPABILITY IMAP4
S: abcd OK CAPABILITY completed
Data: no specific data for this command (but see below)
Result: OK - noop completed
BAD - command unknown or arguments invalid
The NOOP command always succeeds. It does nothing.
Since any command can return a status update as untagged data, the NOOP command can be used as a periodic poll for new messages or message status updates during a period of inactivity. The NOOP command can also be used to reset any inactivity autologout timer on the server.
Example: C: a002 NOOP
S: a002 OK NOOP completed
. . .
C: a047 NOOP
S: * 22 EXPUNGE
S: * 23 EXISTS
S: * 3 RECENT
S: * 14 FETCH (FLAGS (\Seen \Deleted))
S: a047 OK NOOP completed
Data: mandatory untagged response: BYE
Result: OK - logout completed
BAD - command unknown or arguments invalid
The LOGOUT command informs the server that the client is done with the session. The server must send a BYE untagged response before the (tagged) OK response, and then close the network connection.
Example: C: A023 LOGOUT
S: * BYE IMAP4 Server logging out
S: A023 OK LOGOUT completed
(Server and client then close the connection)
Server implementations may allow non-authenticated access to certain mailboxes. The convention is to use a LOGIN command with the userid "anonymous". A password is required. It is implementation-dependent what requirements, if any, are placed on the password and what access restrictions are placed on anonymous users.
Once authenticated (including as anonymous), it is not possible to re-enter non-authenticated state.
In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT), the following commands are valid in non-authenticated state: AUTHENTICATE and LOGIN.
Data: continuation data may be requested
Result: OK - authenticate completed, now in authenticated state
NO - authenticate failure: unsupported authentication
mechanism, credentials rejected
BAD - command unknown or arguments invalid,
authentication exchange cancelled
The AUTHENTICATE command indicates an authentication mechanism, such as described in [IMAP-AUTH], to the server. If the server supports the requested authentication mechanism, it performs an authentication protocol exchange to authenticate and identify the user. Optionally, it also negotiates a protection mechanism for subsequent protocol interactions. If the requested authentication mechanism is not supported, the server should reject the AUTHENTICATE command by sending a tagged NO response.
The authentication protocol exchange consists of a series of server challenges and client answers that are specific to the authentic