Because IMAP is a complex protocol, it has many more commands than the simple POP protocols. This section provides a reference for all IMAP commands in the proposed standard. Each command and its possible server responses are described in detail.

Figure 11-1. IMAP usage for a mobile user

Just like the other protocols, any nonstandard commands, such as those proprietary commands that might be created by a particular vendor, are required to begin with an “X”.

Like POP, an IMAP consists of several distinct states. Some commands are only valid in a given state. Before detailing the commands themselves, a high-level look at the states is appropriate.

IMAP sessions may be in one of four states at any one time. These states are:

Upon initial connection to an IMAP server, a client is in the Nonauthenticated State. A client enters the Authenticated State when a user log into the server, providing an appropriate type of authentication credentials.

Once logged in, a client may select a mailbox on which to operate. Selecting a mailbox puts the client in the Selected State and allows access to commands that operate on a mailbox.

The Logout State is entered when a client logs out, a server refuses service, or a connection is otherwise interrupted. This state lasts just long enough for the client and server to close a connection.

Within each state, the client may issue the commands appropriate to that state. That is, a client cannot operate on a mailbox (Selected State) until one has logged in (Authentication State).

Unlike many other protocols, an IMAP client is required to be able to accept any server response at any time. This recognizes the multithreaded nature of modern MUAs, since they may very well issue multiple commands to a server simultaneously from different threads.

To facilitate handling of command responses, a client “tags” each command with a pseudo-random alphanumeric string. Server responses include a copy of the tag so that the client may determine to which command the server is responding.

For example, let’s look at the simplest IMAP command, NOOP, which stands for “no operation” and causes the IMAP server to do exactly nothing. A client NOOP command and its server response looks like this:

Client:  TAG78 NOOP
Server:  TAG78 OK NOOP completed

In this example, the string TAG78 is a tag, which could have been any alphanumeric value. The tag is followed by the NOOP command. The server responds with a line that begins with the tag, showing which command it is responding to. Next, a server status response of OK shows that the command completed successfully, then the command is echoed, followed by some human-readable text.

Later in this chapter we will describe each IMAP command and its server response. You will see that each command is preceded with a tag consisting of letters and numbers and that the server echoes this tag when responding.

Table 11-1 lists the IMAP server status responses. Some server responses contain untagged lines. These lines include data of one sort or another. Each type of response is discussed in this chapter, following the description of the associated command.

If a client command fails, the server responds with an error. For example, suppose we generate an error by giving a nonexistent command. Repeating the previous NOOP example with a misspelling might generate something like this:

Client:  TAG78 NOOOP
Server:  TAG78 BAD Command unrecognized/login please: NOOOP

Server responses may contain some additional information. These optional response codes allow an MUA to take appropriate action and/or show human-readable information to a user. Response codes may be implemented by servers to be more polite; it is always better to tell someone why an error occurred, especially if it is within her power to fix the problem!

Each response code follows a server response on a line by itself. The response code itself is contained within square brackets, followed by the appropriate arguments. For example, a user may be told of an impending shutdown of an IMAP server like this:

Client:  A123 STATUS inbox (MESSAGES)
Server:  * STATUS Inbox (MESSAGES 23)
Server:  * OK [ALERT] This IMAP server will shut down in 6 minutes
Server:  A123 OK STATUS completed

In the preceding example, a client initiated a STATUS request to determine the number of messages in the user’s inbox. Don’t worry about the details of the command and response; we’ll cover that shortly. The server responded with the STATUS response, informing the user that the mailbox Inbox contained 23 messages, and also with an ALERT response code. The client’s MUA must show the user the text that follows an ALERT, perhaps with a dialog box.

Since all commands are initiated by clients, an IMAP server may not broadcast information to clients; it must wait until a connection is made by a client and then piggyback any response codes onto its normal responses. Table 11-2 lists the IMAP response codes.

Other response codes provide clues to the client that explain why a particular command is failing and how the error may be corrected. In many cases, response codes allow a client to try another tack in order to solve a problem.

It is difficult to accomplish much in an IMAP session without first authenticating to the server. Authentication is required before a client may access mailboxes. The ways to authenticate are covered in the next section “The Nonauthenticated State.” First, though, let’s look at what we see in any state.

It is possible to carry on a limited conversation with an IMAP server without authenticating. This is a good way to test connection to a server.

For example, a client may determine what services the server offers. This is done with the CAPABILITY command. This command takes no arguments and returns a list of capabilities that the server supports. It can be used when a client is not authenticated.

Every server that supports the current version of IMAP will return the string IMAP4rev1 as part of its response to a CAPABILITY command, which we can see by telneting to port 143 on a server with an IMAP daemon:

[lovelace]$ telnet morris 143
Trying 192.168.20.1...
Connected to morris.staff.plugged.com.au.
Escape character is "^]".
* OK morris.staff.plugged.com.au IMAP4rev1 v11.241 server ready

The internet Message Access Protocol The server response to a CAPABILITY command consists of two lines. The first line is untagged and shows the list of capabilities. The second line is the server result, showing the server status response.

A typical CAPABILITY command and response might look like this:

Client:  C678 CAPABILITY
Server:  * CAPABILITY IMAP4rev1 AUTH=KERBEROS_V4
Server:  C678 OK CAPABILITY completed

In this example, the server responded by noting that it is capable of speaking the IMAP4rev1 protocol. Additionally, we found out that it also supports the KERBEROS_V4 authentication mechanism. (More on authentication mechanisms later.) The string C678 is the tag used to ensure that the client knows to which command the server responded. It could have been any alphanumeric string.

The NOOP command does nothing (“no operation”). However, it can be used to reset inactivity timeouts on the server. An MUA may send a NOOP command periodically in order to keep the server from closing the connection.

Some IMAP servers will also return status information when a NOOP command is received. Be careful not to count on this, though, as it is not standard and should only be used if the particular server that you are using provides status information. The most common type of information returned is a list showing the status of messages in the currently selected mailbox (e.g., so many exist, so many marked for deletion, etc.).

The server response to a NOOP command will probably consist of just one line, containing the server result. If the server chooses to return status information, it may do so with untagged informational lines before the result line.

A standard NOOP command that does not return status looks like this:

Client:  R6875 NOOP
Server:  R6875 OK NOOP completed

The LOGOUT command informs the server that the client is finished with the connection. The server response to a LOGOUT command is a BYE line and a tagged result line.

An example LOGOUT looks like this:

Client:  Z456 LOGOUT
Server:  * BYE IMAP4revl Server logging out
Server:  Z456 OK LOGOUT completed
(Both close connection)

Table 11-3 lists the IMAP commands that are valid in any state.