A client enters the Authenticated State upon successful login. It is from this state that the client is actually able to do something useful.

Once in this state, a client may create, rename, or delete mailboxes, change the mail accounts or newsgroups to which the client is subscribed, and examine the contents of mailboxes. From here, the client may also select a given mailbox in order to manipulate the contents of a mailbox, and that puts the user into the Selected State, covered next.

Before looking at the commands for this state, we should discuss mailboxes and how they are held on an IMAP server. Each IMAP mailbox holds messages, and each message may be marked with flags that show its state on the server. Table 11-5 lists these flags. Since several of this state’s commands make use of system flags, they bear discussion before the commands themselves.

Anyone who has used a modern MUA has probably seen information held in these flags. Many MUAs display a message list for each mailbox, which indicates the state of each message. A given message may be marked as being “new” or “read”. If a message has been forwarded or replied to, a marker is set on the display. Behind the scenes, an IMAP server uses system flags to keep track of these status changes. An MUA can use these flags to modify a user interface display.

Most of the flags are easy to understand. An exception may be the Deleted flag. Messages that are marked for deletion are not actually deleted until later, when an EXPUNGE command actually deletes the messages from their current mailbox. Messages that are marked for deletion may appear in a “Trash” mailbox but actually exist in the original mailbox’s file on the server.

The SELECT command is used to select a mailbox. A mailbox must be selected before a client can get access to any of the messages that it contains. Once a mailbox is selected, the session is placed in the Selected State.

The SELECT command takes a mailbox name as an argument. The client may retrieve a list of available mailboxes with the LIST command.

A server must return some status information when a mailbox is selected. Specifically, it returns the FLAGS defined for the mailbox, the number of messages in the box, the number of “recent” messages, and the unique identifier for the mailbox. Additionally, most servers will return the message sequence number of the first unseen message and a list of any flags that the client may change (i.e., the PERMANENTFLAGS response).

If the client is allowed to write to the selected mailbox, the server result should also include the response code [READ-WRITE]. An example:

Client:  FR56 SELECT Conferences
Server:  * 55 EXISTS
Server:  * 5 RECENT
Server:  * OK [UNSEEN 51] Message 51 is the first unseen
Server:  * OK [UIDVALIDITY 21475678] UIDs valid
Server:  * FLAGS (Answered Flagged Deleted Seen Draft)
Server:  * OK [PERMANENTFLAGS (*)] Limited
Server:  FR56 OK [READ-WRITE] SELECT completed

In the preceding example, a client attempts to select a mailbox called Conferences. The server replies with the mandatory EXISTS, RECENT, UIDVALIDITY, and FLAGS data and the the optional UNSEEN and PERMANENTFLAGS data. In this mailbox, 55 messages exist but only 5 are marked as being RECENT. Message number 51 is the first message that has not been viewed by any client. The mailbox’s unique identifier is 21475678. The flags Answered, Flagged, Deleted, Seen, and Draft are all valid for this mailbox, and this client is allowed to change the setting on all flags for some. Finally, the server notes in its result message that the mailbox has been successfully opened for both reading and writing.

The EXAMINE command is much like the SELECT command, except that a mailbox is opened read-only. Repeating the preceding example with an EXAMINE command, we get:

Client:  FR56 EXAMINE Conferences
Server:  * 55 EXISTS
Server:  * 5 RECENT
Server:  * OK [UNSEEN 51] Message 51 is the first unseen
Server:  * OK [UIDVALIDITY 21475678] UIDs valid
Server:  * FLAGS (Answered Flagged Deleted Seen Draft)
Server:  * OK [PERMANENTFLAGS ()] No permanent flags permitted
Server:  FR56 OK [READ-ONLY] EXAMINE completed

The only differences in this example and in the previous one (besides the command itself) are that the client may not permanently change system flags on the mailbox, nor may the client write to the mailbox in any way.

The CREATE command takes the name of a mailbox as an argument and requests the creation of the mailbox on the server. Note that the mailbox name might include the server’s hierarchy separator (which is given in the server response to a LIST command), in which case the server is being asked to create the hierarchy in the mailbox name, if needed.

For example, if we wanted to create a mailbox “Comdex” under the hierarchy “Conferences/1999”, we might do something like this:

Client:  S23G CREATE Conferences/1999/Comdex
Server:  S23G OK CREATE completed

If the hierarchy “Conferences/1999” already existed, fine. If not, it would have been created along with the mailbox.

The DELETE command is the opposite of a CREATE. It takes a mailbox name as an argument and requests that the server delete it. To delete the mailbox that was created in the preceding example:

Client:  S23H DELETE Conferences/1999/Comdex
Server:  S23H OK DELETE completed

Note that with a DELETE, the hierarchy “Conferences/1999” will not be deleted. If you want to delete the hierarchy, you will have to walk up it, deleting as you go. The server will not delete any mailboxes underneath (inferior to) the mailbox that you are trying to delete. The special mailbox “INBOX” cannot be deleted.

One should be careful not to confuse the command to delete mailboxes (DELETE) and the method for deleting messages within a mailbox (see the discussion of the EXPUNGE command in the section “The Selected State,” later in this chapter).

The RENAME command simply renames an existing mailbox. It takes two mailbox names, one existing name and a new name. Like this:

Client:  S245 RENAME Conferences Space
Server:  S245 OK RENAME completed

When a RENAME command renames a parent (superior) mailbox, the names of its children (inferior) mailboxes are also changed. Therefore, the preceding example would have renamed not only “Conferences” to “Space”, but also “Conferences/ 1999” to “Space/1999”.

The SUBSCRIBE command allows a client to add a mailbox to the list of subscribed mailboxes.

Note that there is a subtle difference between mailboxes that are “subscribed” or “active” and mailboxes that are not marked so. The list of subscribed mailboxes may be viewed with the LSUB command. The list of any mailbox that the user may access on the server may be viewed with the LIST command.

The SUBSCRIBE command takes a mailbox name as an argument, like this:

Client:  S289 SUBSCRIBE "~/nsmail/customers/OWA"
Server:  S289 OK SUBSCRIBE completed

Note that the '~' character used in the mailbox name is used under Unix and Unix-like operating systems to refer to a user’s home directory.

The UNSUBSCRIBE command takes a mailbox name as an argument and removes the mailbox from the list of “active” or “subscribed” mailboxes. It is the opposite of a SUBSCRIBE command:

Client:  S291 UNSUBSCRIBE "~/nsmail/customers/Web/OWA"
Server:  S29l OK UNSUBSCRIBE completed

The LIST command takes a “reference name” and a mailbox name as arguments. The “reference name” is analogous to a directory, folder, or path; it is the place to find the mailbox named. The mailbox name may include wildcards. This command returns a list of all mailboxes that match the request.

The asterisk character (*) can be used to match any character. The percent sign (%) can be used to match any character except the server’s hierarchy delimiter.

The LIST command may be used to determine which mailboxes are available for a SELECT or similar command.

Client: f89 list "~/nsmail/customers/Web" *
Server: * LIST (NoSelect) "/" ~/nsmail/customers/Web
Server: * LIST (NoInferiors Marked) "/" ~/nsmail/customers/Web/DTSBI
Server: * LIST (NoInferiors Marked) "/" ~/nsmail/customers/Web/IPB
Server: * LIST (NoInferiors Marked) "/" ~/nsmail/customers/Web/OWA
Server: f89 OK LIST completed

The server’s response in the preceding example shows a single reference name, ~/nsmail/customers/Web, being queried for all mailboxes. Note that the reference (directory) itself is marked with a NoSelect flag. Each mailbox is then listed, showing its flags, hierarchy delimiter, and mailbox name.

The LSUB command is similar but only shows those mailboxes that have been marked active with a SUBSCRIBE command. For example:

Client: g78 LSUB "~/nsmail/customers/Web" *
Server: g78 OK LSUB completed
Client: df78 SUBSCRIBE "~/nsmail/customers/Web/OWA"
Server: df78 OK SUBSCRIBE completed
Client: g79 LSUB "~/nsmail/customers/Web" *
Server: * LSUB () "/" ~/nsmail/customers/Web/OWA
Server: g79 OK LSUB completed

As we can see, if a client gives a reference name and a mailbox name (or wildcard) to an LSUB command, the server returns zero or more lines showing the results. In this case, an error is not returned if no mailboxes are found.

The example shows an LSUB command that returns no data. A SUBSCRIBE command is then used to mark a mailbox “active,” after which a subsequent LSUB command returns the mailbox name in the same format as a LIST.

The STATUS command takes a mailbox name and a “status code” as arguments. The server returns the status of a mailbox, even if it is currently selected. This can save time when a mailbox is already selected and the status needs to be checked or confirmed.

More than one CIMAP) status code may be specified in a single request. The possible status codes are listed in Table 11-6.

Checking the MESSAGES and RECENT status codes on a mailbox returns the total number of messages in the box and the number that have the Recent flag set:

client: 89jl STATUS "~/nsmail/customers/Web/OWA" (MESSAGES RECENT)
Server: * STATUS ~/nsmail/customers/Web/OWA (MESSAGES 7 RECENT 0)
Server: 89jl OK STATUS completed

The APPEND command takes a mailbox name and some literal text representing a message and appends the text (as a message) to the mailbox. It optionally takes a list of flags to set on the new message and a date/time string before the literal text. This is a multiline command.

At the end of the APPEND command line is a bracketed number, indicating the length (in octets, including CRLFs) of the message to follow. This is needed so that the server knows when the client is finished.

Appending a simple “Hello, World” message to a mailbox looks like this:

Client:  ASDl APPEND "~/nsmail/customers/Bentley" (Seen Answered) {265}
Client:  Date: Mon, 12 Apr 1999 23:44:05 +1000
Client:  From:  [email protected]
Client:  Subject: Yet Another Hello World Message
Client:  To:  [email protected]
Client:  Message-Id: <[email protected]>
Client:  MIME-Version: 1.0
Client:  Content-Type: text/plain; CHARSET=US-ASCII
Client:
Client:  Hello, World!
Client:
Server:  ASDl OK APPEND completed

Table 11-7 lists the lMAP commands that are valid in the Authenticated State.