Project Specification:

RFC2060-L INTERNET MESSAGE ACCESS PROTOCOL (LITE)

Abstract:

The Internet Message Access Protocol (IMAP-L) allows a client to access and manipulate electronic mail messages on a server. IMAP-L permits manipulation of remote message folders, called "mailboxes", in a way that is functionally equivalent to local mailboxes. IMAP-L includes operations for creating, and deleting mailboxes; checking for messages in the INBOX; permanently removing messages; setting and clearing flags; and fetching of message flags, headers and texts. Messages in IMAP-L are accessed by the use of numbers. These numbers are either message sequence numbers or unique identifiers.

1. IMAP-L Protocol Specification

1.1. Organization of This Document

This document is written from the point of view of the implementor of an IMAP-L client or server. Beyond the protocol overview in section 2, it is not optimized for someone trying to understand the operation of the protocol. The material in sections 3 through 5 provides the general context and definitions with which IMAP-L operates. Sections 6, 7, and 9 describe the IMAP-L commands, responses, and syntax, respectively. The relationships among these are such that it is almost impossible to understand any of them separately. In particular, do not attempt to deduce command syntax from the command section alone; instead refer to the Formal Syntax section.

1.2. Conventions Used in This Document

In examples, "C:" and "S:" indicate lines sent by the client and server respectively.

The following terms are used in this document to signify the requirements of this specification.

1. MUST, or the adjective REQUIRED, means that it is an absolute requirement.
2. MUST NOT that the definition is an absolute prohibition of the specification.
3. SHOULD means that it is required when applicable.
4. SHOULD NOT means that it is prohibited if possible.
5. MAY, CAN, or the adjective OPTIONAL, means that an item is truly optional.

"User" is used to refer to a human user, whereas "client" refers to the software being run by the user.

"Connection" refers to the entire sequence of client/server interaction from the initial establishment of the network connection until its termination. "Session" refers to the sequence of client/server interaction from the time that a mailbox is selected (SELECT or EXAMINE command) until the time that selection ends (SELECT or EXAMINE of another mailbox, CLOSE command, or connection termination).

Characters are 16-bit UNICODE (because that is what Java uses). For our purposes we will use plain text.

2. Protocol Overview

2.1. Link Level

The IMAP-L protocol assumes a reliable data stream such as provided by TCP. When TCP is used, an IMAP-L server listens on port 143. So that we don't interfere with that we will use port 3001.

2.2. Commands and Responses

An IMAP-L connection consists of the establishment of a client/server network connection, an initial greeting from the server, and client/server interactions. These client/server interactions consist of a client command, server data, and a server completion result response. 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 IMAP-L client or server is reading a line.

2.2.1. Client Protocol Sender and Server Protocol Receiver

The client command begins an operation. Each client command is prefixed with an identifier (typically a short alphanumeric string, e.g. A0001, A0002, etc.) called a "tag". A different tag is generated by the client for each command. The protocol receiver of an IMAP-L 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.

2.2.2. Server Protocol Sender and Client Protocol Receiver

Data transmitted by the server to the client and status responses that do not indicate command completion are prefixed with the token "*", and are called untagged responses. Server data MAY ONLY be sent as a result of a client command. 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. There are three possible server completion responses: OK (indicating success), NO (indicating failure), or BAD (indicating protocol error such as unrecognized command or command syntax error). The protocol receiver of an IMAP-L client reads a response line from the server. It then takes action on the response based upon the first token of the response, which can be a tag or an "*".

2.3. Message Attributes

In addition to message text, each message has several attributes associated with it. These attributes may be retrieved individually or in conjunction with other attributes or message texts.

2.3.1. Message Numbers

Messages are accessed by one of two numbers; the unique identifier and the message sequence number.

2.3.1.1. Unique Identifier (UID) Message Attribute

A 32-bit value assigned to each message and each mailbox that is permanently guaranteed not to refer to any other message or mailbox. Unique identifiers are assigned in a strictly ascending fashion in the mailbox; as each message is added to the mailbox it is assigned a higher UID than the message(s) which were added previously. Unlike message sequence numbers, unique identifiers are not necessarily contiguous. Unique identifiers also persist across sessions. Associated with every mailbox is a unique identifier validity value, which is sent in an UIDVALIDITY response code in an OK untagged response at mailbox selection time.

Note: Unique identifiers MUST be strictly ascending in the mailbox at all times. A good value to use for the unique identifier validity value is a 32-bit representation of the creation date/time of the message or mailbox. The unique identifier of a message MUST NOT change during the session or between sessions.

2.3.1.2. Message Sequence Number Message Attribute

A relative position from 1 to the number of messages in the mailbox. This position MUST be ordered by ascending unique identifier. As each new message is added, it is assigned a message sequence number that is 1 higher than the number of messages in the mailbox before that new message was added.

Message sequence numbers can be reassigned during the session. For example, when a message is permanently removed (expunged) from the mailbox, the message sequence number for all subsequent messages is decremented. Similarly, a new message can be assigned a message sequence number that was once held by some other message prior to an expunge.

2.3.2. Message Flags Attribute

A list of zero or more named tokens associated with the message. A flag is set by its addition to this list, and is cleared by its removal. A system flag is a flag name that is pre-defined in this specification. All system flags begin with "\". Certain system flags (\Deleted and \Seen) have special semantics described elsewhere. The currently-defined system flags are:

\Seen Message has been read

\Flagged Message is "flagged" for urgent/special attention

\Deleted Message is "deleted" for removal by later EXPUNGE

System flags are those which the client can add or remove from the message flags permanently; that is, subsequent sessions will see any change in system flags.

2.3.3. Message Date/Time Attribute

The date and time of the message on the server is the date and time which reflects when the message was received. The format is MMDDYYYYHHMISS. This represent: MM for Month, DD for Day, YYYY for Year, HH for 24 hour clock, MI for Minute, SS for Seconds.

2.3.4. Message Size Attribute

The message size is the number of lines in the message. Each line is ended with CRLF.

2.3.5. Header Structure

The header contains a "From:" string, a "Subject:" string, a Date/Time attribute, a Size attribute and the UID.

2.3.6. Body Structure & Message Texts

The body structure of the message contains a single plain-text section.

3. State and Flow Diagram

An IMAP-L server is in one of four states. Most commands are valid in only certain states. It is a protocol error for the client to attempt a command while the command is in an inappropriate state. In this case, a server will respond with a BAD or NO (depending upon server implementation) command completion result.

3.1. Non-Authenticated State

In non-authenticated state, the client MUST supply authentication credentials before most commands will be permitted. This state is entered when a connection starts.

3.2. Authenticated State

In authenticated state, the client is authenticated and MUST select a mailbox to access before commands that affect messages will be permitted. This state is entered when acceptable authentication credentials have been provided, or after an error in selecting a mailbox.

3.3. Selected State

In selected state, a mailbox has been selected to access. This state is entered when a mailbox has been successfully selected.

3.4. Logout State

In logout state, the connection is being terminated, and the server will close the connection.

4. Data Formats

IMAP-L uses textual commands and responses. Data in IMAP-L can be in one of several forms: atom, number, string, parenthesized list, or NIL.

4.1. Atom

An atom consists of one or more non-special characters.

4.2. Number

A number consists of one or more digit characters, and represents a numeric value.

4.3. String

A string is in one of two forms: literal and quoted string. The literal form is the general form of string. The quoted string form is an alternative that avoids the overhead of processing a literal at the cost of limitations of characters that can be used in a quoted string.

A quoted string is a sequence of zero or more characters, excluding CR and LF, with double quote (<">) characters at each end.

The empty string is represented as "" (a quoted string with zero characters between double quotes).

4.4. Parenthesized List

Data structures are represented as a "parenthesized list"; a sequence of data items, delimited by space, and bounded at each end by parentheses. A parenthesized list can contain other parenthesized lists, using multiple levels of parentheses to indicate nesting. The empty list is represented as () -- a parenthesized list with no members.

4.5. NIL

The special atom "NIL" represents the non-existence of a particular data item that is represented as a string or parenthesized list, as distinct from the empty string "" or the empty parenthesized list ().

5. Operational Considerations

5.1. Mailbox Naming

Mailbox names MUST be alphanumeric characters (A-Z,a-z,0-9; no special characters) and are case-insensitive. The case-insensitive mailbox name INBOX is a special name reserved to mean "the primary mailbox for this user on this server". The INBOX mailbox MUST not be deleted.

6. Client Commands

IMAP-L commands are described in this section. Commands are organized by the state in which the command is permitted. Commands which are permitted in multiple states are listed in the minimum permitted state (for example, commands valid in authenticated and selected state are listed in the authenticated state commands). 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 responses to be returned; these are identified by "Responses:" 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 responses 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.

6.1. Client Commands - Any State

The following commands are valid in any state: NOOP, and LOGOUT.

6.1.1. NOOP Command

Arguments: none

Responses: no specific responses 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.

Example: C: a002 NOOP

6.1.2. LOGOUT Command

Arguments: none

Responses: REQUIRED 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 connection. The server MUST send a BYE untagged response before the (tagged) OK response, and then close the network connection.

Example: C: A023 LOGOUT

6.2. Client Commands - Non-Authenticated State

In non-authenticated state, the LOGIN command establishes authentication and enters the authenticated state. The LOGIN command uses the traditional user name and plain-text password pair. Once authenticated it is not possible to re-enter non-authenticated state.

In addition to the universal commands (NOOP, and LOGOUT), the following commands are valid in non-authenticated state: LOGIN.

6.2.1. LOGIN Command

Arguments: user name, password

Responses: no specific responses for this command

Result: OK - login completed, now in authenticated state

NO - login failure: user name or password rejected

BAD - command unknown or arguments invalid

The LOGIN command identifies the client to the server and carries the plain-text password authenticating this user. To authenticate a username and password the password MUST be the reverse order of the username characters. For example: Username = ABC, then Password = CBA

Example: C: a001 LOGIN SMITH HTIMS

6.3. Client Commands - Authenticated State

In authenticated state, commands that manipulate mailboxes as atomic entities are permitted. Of these commands, the SELECT and EXAMINE commands will select a mailbox for access and enter selected state.

In addition to the universal commands (NOOP, and LOGOUT), the following commands are valid in authenticated state: SELECT, EXAMINE, CREATE, DELETE, STATUS.

6.3.1. SELECT Command

Arguments: mailbox name

Responses: REQUIRED untagged responses: EXISTS, UIDVALIDITY

Result: OK - select completed, now in selected state

NO - select failure, now in authenticated state: no such mailbox, can't access mailbox

BAD - command unknown or arguments invalid

The SELECT command selects a mailbox so that messages in the mailbox can be accessed. Before returning an OK to the client, the server MUST send the following untagged data to the client to define the initial state of the mailbox at the client:

The server SHOULD also send an UNSEEN response code in an OK untagged response, indicating the message sequence number of the first unseen message in the mailbox.

Only one mailbox can be selected at a time in a connection. The SELECT command automatically deselects any currently selected mailbox before attempting the new selection. Consequently, if a mailbox is selected and a SELECT command that fails is attempted, no mailbox is selected.

Example: C: A142 SELECT INBOX

6.3.2. EXAMINE Command

The EXAMINE command is identical to SELECT and returns the same output; however, the selected mailbox is read-only. No changes to the permanent state are permitted.

6.3.3. CREATE Command

Arguments: mailbox name

Responses: no specific responses for this command

Result: OK - create completed

NO - create failure: can't create mailbox with that name

BAD - command unknown or arguments invalid

The CREATE command creates a mailbox with the given name. An OK response is returned only if a new mailbox with that name has been created. It is an error to attempt to create INBOX or a mailbox

with a name that refers to an extant mailbox. Any error in creation will return a tagged NO response.

If a new mailbox is created with the same name as a mailbox which was deleted, its unique identifiers MUST be different than any unique identifiers used in the previous incarnation of the mailbox. See the description of the UID attribute for more detail.

Example: C: A003 CREATE owatagusiam

6.3.4. DELETE Command

Arguments: mailbox name

Responses: no specific responses for this command

Result: OK - delete completed

NO - delete failure: can't delete mailbox with that name

BAD - command unknown or arguments invalid

The DELETE command permanently removes the mailbox with the given name. A tagged OK response is returned only if the mailbox has been deleted. It is an error to attempt to delete INBOX or a mailbox name that does not exist. Only empty mailboxes (those that have been expunged of all messages) can be deleted.

Examples: C: A683 DELETE blurdybloop

6.3.5. STATUS Command

Arguments: mailbox name, status data item names

Responses: untagged responses: STATUS

Result: OK - status completed

NO - status failure: no status for that name

BAD - command unknown or arguments invalid

The STATUS command requests the status of the indicated mailbox. It does not change the currently selected mailbox, nor does it affect the state of any messages in the queried mailbox. The STATUS command does not accept wildcards.

The currently defined status data items that can be requested are:

MESSAGES The number of messages in the mailbox.

UIDVALIDITY The unique identifier validity value of the mailbox.

UNSEEN The number of messages which do not have the \Seen flag set.

Example: C: A042 STATUS blurdybloop (UIDNEXT MESSAGES)

6.3.6. LIST Command

Arguments: None

Responses: untagged responses: LIST

Result: OK - list completed

NO - list failure: can't do the list

BAD - command unknown or arguments invalid

The LIST command returns a the names of the mailboxes for this authenticated username. One (because INBOX is always there) or more untagged LIST replies are returned, containing the name of the mailboxes. See the description of the LIST reply for more detail.

The special name INBOX is included in the output from LIST.

Example: C: A001 LIST

6.4. Client Commands - Selected State

In selected state, commands that manipulate messages in a mailbox are permitted.

In addition to the universal commands (NOOP, and LOGOUT), and the authenticated state commands (SELECT, EXAMINE, CREATE, DELETE and STATUS) the following commands are valid in the selected state: CLOSE, EXPUNGE, FETCH, STORE.

6.4.1. CLOSE Command

Arguments: none

Responses: no specific responses 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 if a mailbox is selected, a SELECT, EXAMINE, or LOGOUT command MAY be issued without previously issuing a CLOSE 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

6.4.2. EXPUNGE Command

Arguments: none

Responses: 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: Start with Messages #1,2,3,4,5,6,7,8,9,10,11

C: A202 EXPUNGE

S: * 3 EXPUNGE note: after this is expunged message #4-11 were renumbered to 3-10

S: * 3 EXPUNGE note: after this is expunged message #4-10 were renumbered to 3-9

S: * 5 EXPUNGE note: after this is expunged message #6-9 were renumbered to 5-8

S: * 8 EXPUNGE note: after this is expunged message #1-7 remain

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.3. FETCH Command

Arguments: message set, message data item names

Responses: 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 can be either a single atom or a parenthesized list.

The currently defined data items that can be fetched are:

ALL Header, Body and Flags

HEADER The header information (From:, Subject:), date/time, message size attributes and UID.

FLAGS The flags that are set for this message.

Example: C: A654 FETCH 2:3 (FLAGS BODY)

6.4.4. STORE Command

Arguments: message set, message data item name, value for message data item

Responses: untagged responses: FETCH FLAGS

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.

The currently defined data items that can be stored are:

FLAGS <flag list>

+FLAGS <flag list>

-FLAGS <flag list>

Example: C: A003 STORE 2:4 +FLAGS (\Deleted)

7. Server Responses

Server responses are in two forms: status responses and server data. The information contained in a server response, identified by "Contents:" in the response descriptions below, is described by function, not by syntax. The precise syntax of server responses is described in the Formal Syntax section.

Status responses can be tagged or untagged. Tagged status responses indicate the completion result (OK, NO, or BAD status) 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.

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. deleting of messages).

7.1. Server Responses - Status Responses

Status responses are OK, NO, BAD, and BYE. OK, NO, and BAD may be tagged or untagged. BYE is always untagged.

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:

7.1.1. OK Response

Contents: 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 connection startup. It indicates that the connection is not yet authenticated and that a LOGIN command is needed.

Example: S: * OK IMAP-L server ready

7.1.2. NO Response

Contents: 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 can still complete successfully. The human-readable text describes the condition.

Example: C: A222 DELETE inbox

7.1.3. BAD Response

Contents: 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 can also indicate an internal server failure. The human-readable text describes the condition.

Example: C: ...very long command line...

7.1.4. BYE Response

Contents: 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.

Condition where the BYE response is sent: As part of a normal logout sequence. The server will close the connection after sending the tagged OK response to the LOGOUT command.

Example: S: * BYE

7.2. Server Responses - Mailbox Status

These responses are always untagged. This is how server and mailbox status data are transmitted from the server to the client. Many of these responses typically result from a command with the same name.

7.2.1. STATUS Response

Contents: name status parenthesized list

The STATUS response occurs as a result of a STATUS command. It returns the mailbox name that matches the STATUS specification and the requested mailbox status information. The responses are untagged.

Example: S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 02019999121249)

7.2.2. LIST Response

Contents: mailbox names

The LIST response occurs as a result of a LIST command. It returns a single mailbox name with each response. There can be multiple LIST responses for a single LIST command.

Example: C: A001 LIST

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 a message sequence number.

7.3.1. EXPUNGE Response

Contents: 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 or STORE 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.2. FETCH Response

Contents: 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.

The current data items are:

ALL Flags, Header and Body

FLAGS A parenthesized list of flags that are set for this message.

HEADER A parenthesized list of header information for this message.

BODY A string.

Whatever the order of the requested items are in, always return in Flags, Header, Body order.

The body may contain multiple lines of text. Each line of text is delimited by a CRLF. In this case subsequent lines are responded to the client by using a continuation line. A continuation line is preceded by a + sign. The + sign is followed by the message sequence number, FETCH, line of text ended with a CRLF. See section 8 for an example of the client server interchange.

Example: Fetch Message #23's header information was requested.

7.3.3. FLAGS Response

Contents: flag parenthesized list

The FLAGS response occurs as a result of a FETCH or STORE command. The flag parenthesized list identifies the flags that are applicable for this mailbox.

The update from the FLAGS response MUST be recorded by the client.

Example: S: * 2 FETCH (FLAGS (\Flagged \Deleted \Seen))

7.3.4. EXISTS Response

Contents: none

The EXISTS response reports the number of messages in the mailbox.

This response occurs as a result of a SELECT or EXAMINE command.

The update from the EXISTS response MUST be recorded by the

client.

Example: S: * 23 EXISTS

8. Sample IMAP-L connection

The following is a transcript of an IMAP-L connection. A long line in this sample is broken for editorial clarity.