Network Working Group J. Rice Request for Comments: 1203 Stanford Obsoletes: RFC 1064 February 1991 INTERACTIVE MAIL ACCESS PROTOCOL - VERSION 3 Status of this Memo This RFC suggests a method for workstations to access mail dynamically from a mailbox server ("repository"). This RFC specifies a standard for the SUMEX-AIM community and an Experimental Protocol for the Internet community. Discussion and suggestions for improvement are requested. Please refer to the current edition of the "IAB Official Protocol Standards" for the standardization state and status of this protocol. Distribution of this memo is unlimited. Scope The following document is a modified version of RFC 1064, the definition of the IMAP2 protocol. This RFC has been written specifically as a counter proposal to RFC 1176, which itself proposes modifications to IMAP2. Sadly, RFC 1176 was made without internal consultation with the IMAP community, so we are in a position of feeling we have to present a counter proposal to what, if we do not act, will become a de facto standard. The reasons for this counter proposal are numerous but fall mostly into the following categories: - IMAP2 is insufficiently powerful for a number of server/client interactions which we believe to be important. RFC 1176 negligibly enhances the functionality of IMAP2. - IMAP2 makes what we believe to be an erroneous definition for unsolicited vs. solicited data. IMAP3 as specified herein attempts to correct this. RFC 1176 makes no effort to remedy these problems. - RFC 1176 has explicitly modified the intent of RFC 1064 by allowing the server to make assumptions about the client's caching architecture. We believe this to be a grave error and do not support it in this proposal. - RFC 1176 specifies a number of "optional" features in the protocol without specifying a suitable metaprotocol by which servers and clients can adequately negotiate over the set of implemented features. This proposal specifies a mechanism by which servers and clients can come to an unambiguous understanding about which features are usable by each party. Rice [Page 1] RFC 1203 IMAP3 February 1991 - RFC 1176 pays only lip-service to being network protocol independent and, in fact assumes the use of TCP/IP. Neither RFC 1064 nor this proposal make any such assumption. Although there are numerous other detailed objections to RFC 1176, we believe that the above will serve to show that we believe strongly in the importance of mailbox abstraction level mail protocols and, after a couple of years of use of IMAP2 under RFC 1064 we believe that we have a good enough understanding of the issues involved to be able to take the next step. It is important to take this next step because of the rapid pace of both mail system and user interface development. We believe that, for IMAP not to die in its infancy, IMAP must be ready to respond to emerging ISO and RFC standards in mail, such as for multi-media mail. We believe that RFC 1176 not only provides a very small increment in functionality over RFC 1064 but also adds a number of bugs, which would be detrimental to the IMAP cause. Thus we propose the following definition for IMAP3. Compatibility notes: In revising the IMAP2 protocol it has been our intent, wherever possible to make upwards compatible changes to produce IMAP3. There were, however, some places that had to be changed incompatibly in order to compensate for either ambiguities in the IMAP2 protocol as defined by RFC 1064 or behavior that proved undesirable in the light of experience. It is our goal, however, that existing IMAP2 clients should still be supported and that, at least for the foreseeable future, all IMAP3 servers will support IMAP2 behavior as their default mode. The following are the major differences between this proposal, RFC 1176 and RFC 1064: - In this proposal we specify a difference between "solicited" and "unsolicited" data sent from the server. It is generally the case that data sent by the server can be sent either in response to an explicit request by the client or by the server of its own volition. Any data that the server is required to sent to the client as the result of a request is said to be solicited and carries the same tag as the request that provoked it. Any data sent by the server to the client that is not required by the protocol is said to be unsolicited and carries the special "*" tag. RFC 1176 preserves the original RFC 1064 terminology that calls all such data sent by the server "unsolicited" even when Rice [Page 2] RFC 1203 IMAP3 February 1991 it is, in fact, solicited. - This proposal introduces the experimental concept of distinguishing between Generic, Canonical and Concrete keys, allowing the mailbox to be viewed as a relational database indexed by these keys. This should allow the IMAP protocol to evolve away from its current reliance on RFC 822. RFC 1176 does not have such a unifying model. - The SEARCH command has been changed so as to allow multiple simultaneous searches to be made and to allow unsolicited search messages to be sent by the server. Such a change is essential to allow more sophisticated servers that can process commands asynchronously, possibly substantially delaying searches over slow backing storage media, for example. It is also important to allow servers to be able to send unsolicited search messages that might inform the client of interesting patterns of messages, such as new and unseen mail. - This proposal introduces a specific protocol for the negotiation of protocol versions and server features. This is important because it allows client/server pairs to come to an agreement on what behavior is really available to it. RFC 1176 introduces a number of "optional" commands, which are in some way analogous to "feature-introduced" commands in this proposal. The principle distinction between these is that in RFC 1176 there is no way for a client to discover the set of optional commands, nor is there a way for it to determine whether a specific command really is supported, since RFC 1176 requires the use of the "BAD" response if a feature is not supported. There is, therefore, no way for the client to determine why the attempted command did not work. This also means that, for example, a client cannot disable certain user commands or make them invisible on menus if they are not supported, since there is no way for the client to discover whether the commands are indeed supported without trying to execute such a command. - This proposal introduces a mechanism for clients to create and delete user flags (keywords). This is nor supported in either RFC 1176 or RFC 1064, requiring the user to add keys manually on the server, generally by editing some form of "init" file. - RFC 1064 has no mechanism for determining whether a mailbox is readonly or not. RFC 1176 introduces a non-enforced convention of encoding data about the readonly status of a mailbox in the SELECT message's OK respose comment field. This is not regular with respect to the rest of the protocol, in which the comment field is used for no purpose other than documentation. This Rice [Page 3] RFC 1203 IMAP3 February 1991 proposal introduces specific protocol additions for the dynamic determination and modification of the readonly/readwrite status of mailboxes. Introduction The intent of the Interactive Mail Access Protocol, Version 3 (IMAP3) is to allow a (possibly unreliable) workstation or similar machine to access electronic mail from a reliable mailbox server in an efficient manner. Although different in many ways from POP2 (RFC 937), IMAP3 may be thought of as a functional superset of POP2, and the POP2 RFC was used as a model for this RFC. There was a cognizant reason for this; RFC 937 deals with an identical problem and it was desirable to offer a basis for comparison. Like POP2, IMAP3 specifies a means of accessing stored mail and not of posting mail; this function is handled by a mail transfer protocol such as SMTP (RFC 821). A comparison with the DMSP protocol of PCMAIL can be found at the end of "System Model and Philosophy" section. This protocol assumes a reliable data stream such as provided by TCP or any similar protocol. When TCP is used, the IMAP server listens on port 220. When CHAOS is used the IMAP server listens for the logical contact name "IMAP3". Communication in IMAP is defined to be using the ASCII character interpretation of data. Communication using other conventions may be possible by the selection of features on some servers. System Model and Philosophy Electronic mail is a primary means of communication for the widely spread SUMEX-AIM community. The advent of distributed workstations is forcing a significant rethinking of the mechanisms employed to manage such mail. With mainframes, each user tends to receive and process mail at the computer he used most of the time, his "primary host". The first inclination of many users when an independent workstation is placed in front of them is to begin receiving mail at the workstation, and, in fact, many vendors have implemented facilities to do this. However, this approach has several disadvantages: (1) Workstations (especially Lisp workstations) have a software design that gives full control of all aspects of the system to the user at the console. As a result, background tasks, Rice [Page 4] RFC 1203 IMAP3 February 1991 like receiving mail, could well be kept from running for long periods of time either because the user is asking to use all of the machine's resources, or because, in the course of working, the user has (perhaps accidentally) manipulated the environment in such a way as to prevent mail reception. This could lead to repeated failed delivery attempts by outside agents. (2) The hardware failure of a single workstation could keep its user "off the air" for a considerable time, since repair of individual workstation units might be delayed. Given the growing number of workstations spread throughout office environments, quick repair would not be assured, whereas a centralized mainframe is generally repaired very soon after failure. (3) It is more difficult to keep track of mailing addresses when each person is associated with a distinct machine. Consider the difficulty in keeping track of a large number of postal addresses or phone numbers, particularly if there was no single address or phone number for an organization through which you could reach any person in that organization. Traditionally, electronic mail on the ARPANET involved remembering a name and one of several "hosts" (machines) whose name reflected the organization in which the individual worked. This was suitable at a time when most organizations had only one central host. It is less satisfactory today unless the concept of a host is changed to refer to an organizational entity and not a particular machine. (4) It is very difficult to keep a multitude of heterogeneous workstations working properly with complex mailing protocols, making it difficult to move forward as progress is made in electronic communication and as new standards emerge. Each system has to worry about receiving incoming mail, routing and delivering outgoing mail, formatting, storing, and providing for the stability of mailboxes over a variety of possible filing and mailing protocols. Consequently, while the workstation may be viewed as an Internet host in the sense that it implements IP, it should not be viewed as the entity which contains the user's mailbox. Rather, a mail server machine (sometimes called a "repository") should hold the mailbox, and the workstation (hereafter referred to as a "client") should access the mailbox via mail transactions. Because the mail server machine would be isolated from direct user manipulation, it could achieve high software reliability easily, and, as a shared resource, Rice [Page 5] RFC 1203 IMAP3 February 1991 it could achieve high hardware reliability, perhaps through redundancy. The mail server could be used from arbitrary locations, allowing users to read mail across campus, town, or country using more and more commonly available clients. Furthermore, the same user may access his mailbox from different clients at different times, and multiple users may access the same mailbox simultaneously. The mail server acts an an interface among users, data storage, and other mailers. The mail access protocol is used to retrieve messages, access and change properties of messages, and manage mailboxes. This differs from some approaches (e.g., Unix mail via NFS) in that the mail access protocol is used for all message manipulations, isolating the user and the client from all knowledge of how the data storage is used. This means that the mail server can utilize the data storage in whatever way is most efficient to organize the mail in that particular environment, without having to worry about storage representation compatibility across different machines. In defining a mail access protocol, it is important to keep in mind that the client and server form a macrosystem, in which it should be possible to exploit the strong points of both while compensating for each other's weaknesses. Furthermore, it's desirable to allow for a growth path beyond the hoary text-only RFC 822 protocol. Unlike POP2, IMAP3 has extensive features for remote searching and parsing of messages on the server. For example, a free text search (optionally in conjunction with other searching) can be made throughout the entire mailbox by the server and the results made available to the client without the client having to transfer the entire mailbox and searching itself. Since remote parsing of a message into a structured (and standard format) "envelope" is available, a client can display envelope information and implement commands such as REPLY without having any understanding of how to parse RFC 822, etc., headers. Additionally, IMAP3 offers several facilities for managing a mailbox beyond the simple "delete message" functionality of POP2. In spite of this, IMAP3 is a relatively simple protocol. Although servers should implement the full set of IMAP3 functions, a simple client can be written which uses IMAP3 in much the way as a POP2 client. IMAP3 differs from the DMSP protocol of PCMAIL (RFC 1056) in a more fundamental manner, reflecting the differing architectures of IMAP and PCMAIL. PCMAIL is either an online ("interactive mode"), or offline ("batch mode") system. IMAP is primarily an online system in which real-time and simultaneous mail access were considered Rice [Page 6] RFC 1203 IMAP3 February 1991 important. In PCMAIL, there is a long-term client/server relationship in which some mailbox state is preserved on the client. There is a registration of clients used by a particular user, and the client keeps a set of "descriptors" for each message which summarize the message. The server and client synchronize their states when the DMSP connection starts up, and, if a client has not accessed the server for a while, the client does a complete reset (reload) of its state from the server. In IMAP, the client/server relationship lasts only for the duration of the IMAP3 connection. All mailbox state is maintained on the server. There is no registration of clients. The function of a descriptor is handled by a structured representation of the message "envelope". This structure makes it unnecessary for a client to know anything about RFC 822 parsing. There is no synchronization since the client does not remember state between IMAP3 connections. This is not a problem since in general the client never needs the entire state of the mailbox in a single session, therefore there isn't much overhead in fetching the state information that is needed as it is needed. There are also some functional differences between IMAP3 and DMSP. DMSP has functions for sending messages, printing messages, and changing passwords, all of which are done outside of IMAP3. DMSP has 16 binary flags of which 8 are defined by the system. IMAP has flag names; there are currently 5 defined system flag names and a facility for some number (29 in the current implementations) of user flag names. IMAP3 has a sophisticated message search facility in the server to identify interesting messages based on dates, addresses, flag status, or textual contents without compelling the client to fetch this data for every message. It was felt that maintaining state on the client is advantageous only in those cases where the client is only used by a single user, or if there is some means on the client to restrict access to another user's data. It can be a serious disadvantage in an environment in which multiple users routinely use the same client, the same user routinely uses different clients, and where there are no access restrictions on the client. It was also observed that most user mail access is to a relatively small set of "interesting" messages, which were either "new" mail or mail based upon some user-selected criteria. Consequently, IMAP3 was designed to easily identify those "interesting" messages so that the client could fetch the state of those messages and not those that were not "interesting". One crucial philosophical difference between IMAP and other common Rice [Page 7] RFC 1203 IMAP3 February 1991 mail protocols is that IMAP is a mailbox access protocol, not a protocol for manipulating mail files. In the IMAP model, unlike other mail system models in which mail is stored in a linear mail file, no specification is made for the implementation architecture for mail storage. Servers may choose to implement mailboxes as files but this is a detail of which the client can be totally unaware. What is more, in the IMAP model, mailboxes are viewed as mappings from keys into values. There are broadly three types of keys, generic, canonical and concrete. Generic keys are generic, mail protocol independent keys defined by IMAP which are meaningful across multiple mail encoding formats. An example of such a generic key might be "TO", which would be associated with the "To:" field of an RFC 822 format message. Canonical keys represent the way in which the server can associate values that are generally "about" a certain key concept, possibly integrating several mail format specific fields, without having to worry the client with the particular details of any particular message format. Thus, the canonical TO key (called $TO) could denote anything that could reasonably be construed as being directed towards someone. Hence, in an RFC 822 message the server could find the union of the "To:", "Resent-To", "Apparently-To:" and "CC:" fields to be the appropriate value associated with the canonical $TO key. Concrete keys allow the client to gain access to certain mail format specific concepts, that are not pre-specified by the IMAP protocol, in a well defined manner. For example, If the client asks for the value associated with the "APPARENTLY-TO" key then, if the message were to be in RFC 822 format, the server would look for a header field called "Apparently-To:". If no such field is found or the field is not implemented or meaningful for the particular message format then the server will respond with the null value, called NIL, indicating the non-existence of the field. Thus, IMAP servers are at liberty to implement mailboxes as a relational databases if it seems convenient. Indeed, we anticipate that future mail systems will tend to use database technology for the storage and indexing of mailboxes as a result of the pressure caused by the increasing size of mailboxes. Although for historical reasons IMAP is currently somewhat closely associated with RFC 822, we anticipate that future developments in IMAP will remove these mail format specific components and will move towards the generic model mentioned above. This will allow IMAP more easily to incorporate such things as multi-media mail. Rice [Page 8] RFC 1203 IMAP3 February 1991 The Protocol The IMAP3 protocol consists of a sequence of client commands and server responses to those commands, with extra information from the server data being sent asynchronously to and independent to the responses to client commands. Unlike most Internet protocols, commands and responses are tagged. That is, a command begins with a unique identifier (typically a short alphanumeric sequence such as a Lisp "gensym" function would generate e.g., A0001, A0002, etc.), called a tag. The response to this command is given the same tag from the server. We distinguish between data sent by the server as the result of a client request, which we term "SOLICITED" and data sent by the server not as the result of a client request, which we term "UNSOLICITED". The server may send unsolicited data at any time that would not fragment another piece of data on the same stream rendering it unintelligible. The server is contractually required, however, to return all data that is solicited by the client before the return of the completion signal for that command, i.e., all solicited data must be returned within the temporal extent of the request/completion acknowledgement wrapper. This does not, however, preclude the simultaneous processing of multiple requests by the client, it simply requires that the client be confident that it has all the requested data when a request finishes. This allows the implementation of both synchronous and asynchronous clients. Solicited data is identified by the tag of the initial request by the client. Unsolicited data is identified by the special reserved tag of "*". There is another special reserved tag, "+", discussed below. Note: the tagging of SOLICITED data is only permitted for a selected server version other than 2.0. No assumptions concerning serial or monolithic processing by the server can be made by a correct client. The server is at liberty to process multiple requests by the same client in any order. This allows servers to process costly searches over mailboxes on slow backing storage media in the background, while still preserving interactive performance. Clients can, however, assume the serialization of the request/data/completion behavior mentioned above. When a connection is opened the server sends an unsolicited OK response as a greeting message and then waits for commands. When commands are received the server acts on them and responds with responses, often interspersed with data. Rice [Page 9] RFC 1203 IMAP3 February 1991 The client opens a connection, waits for the greeting, then sends a LOGIN command with user name and password arguments to establish authorization. Following an OK response from the server, the client then sends a SELECT command to access the desired mailbox. The user's default mailbox has a special reserved name of "INBOX" which is independent of the operating system that the server is implemented on. The server will generally send a list of valid flags, number of messages, and number of messages arrived since last access for this mailbox as solicited data, followed by an OK response. The client may terminate access to this mailbox and access a different one with another SELECT command. Because the SELECT command affects the state of the server in a fundamental way, the server is required to process all outstanding commands for any given mailbox before sending the OK tag for the SELECT command. Thus, the client will always know that all responses before an OK SELECT response will refer to the old mailbox and all responses following it will apply to the new mailbox. Because, in the real world, local needs or experimental work will dictate that servers will support both supersets of the defined behavior and incompatible changes, servers will support a SELECT.VERSION command and a SELECT.FEATURES command, the purpose of which is to allow clients to select the overall behavior and specific features that they want from a server. The default behavior of any server is to process commands and to have interaction syntax the same as is specified by IMAP2 in RFC 1064. A server may not behave in any other manner unless the SELECT.VERSION or SELECT.FEATURES commands are used to select different behavior. Over time, when groups of generally useful changes to the current, default behavior of the server are found, these will be collected together and incorporated in such a way that all of the features can be selected simply by selecting a particular major version number of the protocol. It should be noted that the version numbers (both major and minor) selected by the SELECT.VERSION command denote versions of the IMAP protocol, not versions of the server per se. Thus, although in general changes to the protocol specification will be made in such a way that they are upwards compatible, this cannot be guaranteed. No client should rely on tests of the form "if major_version > 2 then..." being valid for all protocol versions, since incompatible changes might be made in the future. The client reads mailbox information by means of FETCH commands. The actual data is transmitted via the solicited data mechanism (that is, FETCH should be viewed as poking the server to include the desired data along with any other data it wishes to transmit to the client). There are three major categories of data which may be fetched. Rice [Page 10] RFC 1203 IMAP3 February 1991 The first category is that data which is associated with a message as an entity in the mailbox. There are presently three such items of data: the "internal date", the "RFC 822 size", and the "flags". The internal date is the date and time that the message was placed in the mailbox. The RFC 822 size is subject to deletion in the future; it is the size in bytes of the message, expressed as an RFC 822 text string. Current clients only use it as part of a status display line. The flags are a list of status flags associated with the message (see below). All of the first category data can be fetched by using the macro-fetch word "FAST"; that is, "FAST" expands to "(FLAGS INTERNALDATE RFC822.SIZE)". The second category is that data which describes the composition and delivery information of a message; that is, information such as the message sender, recipient lists, message-ID, subject, etc. This is the information which is stored in the message header in RFC 822 format message and is traditionally called the "envelope". [Note: this should not be confused with the SMTP (RFC 821) envelope, which is strictly limited to delivery information.] IMAP3 defines a structured and unambiguous representation for the envelope which is particularly nice for Lisp-based parsers. A client can use the envelope for operations such as replying and not worry about RFC 822 at all. Envelopes are discussed in more detail below. The first and second category data can be fetched together by using the macro-fetch word "ALL"; that is, "ALL" expands to "(FLAGS INTERNALDATE RFC822.SIZE ENVELOPE)". The third category is that data which is intended for direct human viewing. The present RFC 822 based IMAP3 defines three such items: RFC822.HEADER, RFC822.TEXT, and RFC822 (the latter being the two former appended together in a single text string). Fetching "RFC822" is equivalent to typing the RFC 822 representation of the message as stored on the mailbox without any filtering or processing. Typically, a client will "FETCH ALL" for some or all of the messages in the mailbox for use as a presentation menu, and when the user wishes to read a particular message will "FETCH RFC822.TEXT" to get the message body. A more primitive client could, of course, simply "FETCH RFC822" a la POP2-type functionality. The client can alter certain data by means of a STORE command. As an example, a message is deleted from a mailbox by a STORE command which includes the \DELETED flag as one of the flags being set. Other client operations include copying a message to another mailbox (COPY command), permanently removing deleted messages (EXPUNGE command), checking for new messages (CHECK command), and searching for messages which match certain criteria (SEARCH command). Rice [Page 11] RFC 1203 IMAP3 February 1991 The client terminates the session with the LOGOUT command. The server returns a "BYE" followed by an "OK". A Typical Scenario Client Server ------ ------ {Wait for Connection} {Open Connection} --> <-- * OK IMAP3 Server Ready {Wait for command} A001 SUPPORTED.VERSIONS --> <-- * SUPPORTED.VERSIONS ((2 0 ) (3 0 EIGHT.BIT.TRANSPARENT AUTO.SET.SEEN TAGGED.SOLICITED)) A001 OK Supported Versions returned. {Wait for command} A002 SELECT.VERSION (3 0) --> <-- A002 OK Version 3.0 Selected. {Wait for command} A002 SELECT.FEATURES TAGGED.SOLICITED --> <-- A002 OK Features selected. {Wait for command} A003 LOGIN Fred Secret --> <-- A003 OK User Fred logged in {Wait for command} A004 SELECT INBOX --> <-- A004 FLAGS (Meeting Notice \Answered \Flagged \Deleted \Seen) <-- A004 19 EXISTS <-- A004 2 RECENT <-- A004 OK Select complete {Wait for command} A005 FETCH 1:19 ALL --> <-- A005 1 Fetch (......) ... <-- A005 18 Fetch (......) <-- A005 19 Fetch (......) <-- A005 OK Fetch complete {Wait for command} A006 FETCH 8 RFC822.TEXT --> <-- A006 8 Fetch (RFC822.TEXT {893} ...893 characters of text... <-- ) <-- A006 OK Fetch complete {Wait for command} Rice [Page 12] RFC 1203 IMAP3 February 1991 A007 STORE 8 +Flags \Deleted --> <-- A007 8 Store (Flags (\Deleted \Seen)) <-- A007 OK Store complete {Wait for command} A008 EXPUNGE --> <-- A008 19 EXISTS <-- A008 8 EXPUNGE <-- A008 18 EXISTS <-- A008 Expunge complete {Wait for command} A009 LOGOUT --> <-- A009 BYE IMAP3 server quitting <-- A009 OK Logout complete {Close Connection} --><-- {Close connection} {Go back to start} A more complex scenario produced by a pipelining multiprocess client. Client Server ------ ------ {Wait for Connection} {Open session as above} <-- A004 19 EXISTS <-- A004 2 RECENT <-- A004 OK Select complete {Wait for command} A005 SEARCH RECENT --> <-- A005 SEARCH (18 19) (RECENT) <---A005 OK Search complete A006 FETCH 18:19 ALL RFC822.TEXT A007 STORE 18:19 +FLAGS (\SEEN) A008 FETCH 1:17 ALL --> <-- A006 18 Fetch (... RFC822.TEXT ...) A009 STORE 18 +FLAGS (\DELETED) <-- A006 19 Fetch (... RFC822.TEXT ...) <-- A006 OK Fetch complete <-- A007 18 STORE (Flags (\Seen)) A010 STORE 19 +FLAGS (\DELETED) <-- A007 19 STORE (Flags (\Seen)) <-- A007 OK Store complete <-- A008 1 Fetch (......) ... <-- A008 16 Fetch (......) <-- A008 17 Fetch (......) <-- A008 OK Fetch complete <-- A009 18 STORE (Flags (\Seen \Deleted)) Rice [Page 13] RFC 1203 IMAP3 February 1991 <-- A009 OK Store complete <-- A010 19 STORE (Flags (\Seen \Deleted)) <-- A010 OK Store complete {Wait for command} <-- * EXISTS 23 <-- * RECENT 4 <-- * SEARCH (20 21 22 23) (RECENT) A011 FETCH 20:23 ALL RFC822.TEXT Conventions The following terms are used in a meta-sense in the syntax specification below: An ASCII-STRING is a sequence of arbitrary ASCII characters. An ATOM is a sequence of ASCII characters delimited by SP or CRLF. A CHARACTER is any ASCII character except """", "{", CR, LF, "%", or "\". A CRLF is an ASCII carriage-return character followed immediately by an ASCII linefeed character. A NUMBER is a sequence of the ASCII characters which represent decimal numerals ("0" through "9"), delimited by SP, CRLF, ",", or ":". A SP is the ASCII space character. A TEXT_LINE is a human-readable sequence of ASCII characters up to but not including a terminating CRLF. One of the most common fields in the IMAP3 protocol is a STRING, which may be an ATOM, QUOTED-STRING (a sequence of CHARACTERs inside double-quotes), or a LITERAL. A literal consists of an open brace ("{"), a number, a close brace ("}"), a CRLF, and then an ASCII- STRING of n characters, where n is the value of the number inside the brace. In general, a string should be represented as an ATOM or QUOTED-STRING if at all possible. The semantics for QUOTED-STRING or LITERAL are checked before those for ATOM; therefore an ATOM used in a STRING may only contain CHARACTERs. Literals are most often sent from the server to the client; in the rare case of a client to server literal there is a special consideration (see the "+ text" response below). Another important field is the SEQUENCE, which identifies a set of Rice [Page 14] RFC 1203 IMAP3 February 1991 messages by consecutive numbers from 1 to n where n is the number of messages in the mailbox. A sequence may consist of a single number, a pair of numbers delimited by colon indicating all numbers between those two numbers, or a list of single numbers and/or number pairs. For example, the sequence 2,4:7,9,12:15 is equivalent to 2,4,5,6,7,9,12,13,14,15 and identifies all of those messages. Definitions of Commands and Responses Summary of Commands and Responses Commands: tag NOOP tag LOGIN user password tag LOGOUT tag SELECT mailbox tag CHECK tag EXPUNGE tag COPY sequence mailbox tag FETCH sequence data tag STORE sequence data value tag SEARCH criteria tag BBOARD bboard tag FIND (BBOARDS / MAILBOXES) pattern tag READONLY tag READWRITE tag SELECT.VERSION (major_version minor_version) tag SELECT.FEATURES features tag SUPPORTED.VERSIONS tag FLAGS tag SET.FLAGS Responses (can be either solicited or unsolicited): */tag FLAGS flag_list */tag SEARCH (numbers) (criteria) */tag EXISTS */tag RECENT */tag EXPUNGE */tag STORE data */tag FETCH data */tag BBOARD bboard_name */tag MAILBOX non_inbox_mailbox_name */tag SUPPORTED.VERSIONS version_data */tag READONLY */tag READWRITE */tag OK text */tag NO text */tag BAD text Rice [Page 15] RFC 1203 IMAP3 February 1991 */tag BYE text Responses (can only be solicited): tag COPY message_number Responses (can only be unsolicited): + text Commands tag NOOP The NOOP command returns an OK to the client. By itself, it does nothing, but certain things may happen as side effects. For example, server implementations which implicitly check the mailbox for new mail may do so as a result of this command. The primary use of this command is to for the client to see if the server is still alive (and notify the server that the client is still alive, for those servers which have inactivity autologout timers). tag LOGIN user password The LOGIN command identifies the user to the server and carries the password authenticating this user. This information is used by the server to control access to the mailboxes. EXAMPLE: A001 LOGIN SMITH SESAME logs in as user SMITH with password SESAME. tag LOGOUT The LOGOUT command indicates the client is done with the session. The server sends a solicited BYE response before the (tagged) OK response, and then closes the connection. tag SELECT mailbox The SELECT command selects a particular mailbox. The server must check that the user is permitted read access to this mailbox. Prior to returning an OK to the client, the server must send an solicited FLAGS and EXISTS response to the client giving the flags list for this mailbox (simply the system flags if this mailbox doesn't have any special flags) and the number of messages in the mailbox. It is also recommended that the server send a RECENT unsolicited response to the client for the benefit of clients which make use of the number of new messages in a mailbox. It is further recommended that servers should send an unsolicited READONLY message if the mailbox that has been selected is not Rice [Page 16] RFC 1203 IMAP3 February 1991 writable by the user. Multiple SELECT commands are permitted in a session, in which case the prior mailbox is deselected first. The default mailbox for the SELECT command is INBOX, which is a special name reserved to mean "the primary mailbox for this user on this server". The format of other mailbox names is operating system dependent (as of this writing, it reflects the path of the mailbox on the current servers), though it could reflect any server-specific naming convention for the namespace of mailboxes. Such a namespace need not and should not be viewed as being equivalent or linked to the server machine's file system. EXAMPLES: A002 SELECT INBOX ;; selects the default mailbox. A002 197 EXISTS ;; server says 197 messages in INBOX A002 5 RECENT ;; server says 5 are recent. A002 OK Select complete. or A003 SELECT /usr/fred/my-mail.txt ;; select a different user specified mailbox. ... tag CHECK The CHECK command forces a check for new messages and a rescan of the mailbox for internal change for those implementations which allow multiple simultaneous read/write access to the same mailbox (e.g., TOPS-20). It is recommend that periodic implicit checks for new mail be done by servers as well. The server must send a solicited EXISTS response prior to returning an OK to the client. tag EXPUNGE The EXPUNGE command permanently removes all messages with the \DELETED flag set in its flags from the mailbox. Prior to returning an OK to the client, for each message which is removed, a solicited EXPUNGE response is sent indicating which message was removed. The message number of each subsequent message in the mailbox is immediately decremented by 1; this means that if the last 5 messages in a 9-message mailbox are expunged you will receive 5 "5 EXPUNGE" responses for message 5. To ensure mailbox integrity and server/client synchronization, it is recommended that the server do an implicit check prior to commencing the expunge and again when the expunge is completed. Furthermore, if the server allows multiple simultaneous access to the same mailbox the server must guarantee both the integrity of the mailbox and Rice [Page 17] RFC 1203 IMAP3 February 1991 the views of it held by the clients. EXPUNGE is not allowed if the user does not have write access to this mailbox. If a user does not have write access to the mailbox then the server is required to signal this fact by replying with a NO response with a suitable text string that can be presented to the user explaining that the mailbox is read-only. It is further recommended that servers send an unsolicited READONLY message to clients that attempt an expunge operation on a read only mailbox. tag COPY sequence mailbox The COPY command copies the specified message(s) to the specified destination mailbox. If the destination mailbox does not exist, the server should create it. Prior to returning an OK to the client, the server must return a solicited COPY response for each message copied. EXAMPLE: A003 COPY 2:4 MEETING copies messages 2, 3, and 4 to mailbox "MEETING". COPY is not allowed if the user does not have write access to the destination mailbox. If a user does not have write access to the destination mailbox then the server is required to signal this fact by replying with a NO response with a suitable text string that can be presented to the user explaining that the mailbox is read-only. It is further recommended that servers send an unsolicited READONLY message to clients that attempt to copy to a read only mailbox. IMAP3 does not specify "where" the message will be put in the mailbox to which it has been copied. tag FETCH sequence fetch_att 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 an S-expression list. The attributes that can be fetched are any of those mentioned specifically below along with any generic, canonical or concrete key. The set of predefined generic keys is: {BCC, BODY, CC, FROM, HEADER, SIZE, SUBJECT, TEXT, TO}. The set of predefined canonical keys is {$CC, $FROM, $SUBJECT, $TO}. The value returned by the server for a non-existent or non-meaningful key is defined to be the null value, NIL. ALL Equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE) ENVELOPE The envelope of the message. The envelope is computed by the server by parsing the header, Rice [Page 18] RFC 1203 IMAP3 February 1991 i.e., the RFC 822 header for an RFC822 format message, into the component parts, defaulting various fields as necessary. FAST Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE) FLAGS The flags which are set for this message. This may include the following system flags: \RECENT Message arrived since last read of this mailbox \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 INTERNALDATE The date and time the message was written to the mailbox. RFC822 The message in RFC 822 format. RFC822.HEADER The RFC 822 format header of the message. RFC822.SIZE The number of characters in the message as expressed in RFC 822 format. RFC822.TEXT The text body of the message, omitting the RFC 822 header. EXAMPLES: A003 FETCH 2:4 ALL fetches the flags, internal date, RFC 822 size, and envelope for messages 2, 3, and 4. A004 FETCH 3 RFC822 fetches the RFC 822 representation for message 3. A005 FETCH 4 (FLAGS RFC822.HEADER) fetches the flags and RFC 822 format header for message 4. A006 FETCH 42 $SUBJECT A006 FETCH $SUBJECT "Some subject text..." A006 OK FETCH completed ok. fetches the canonical subject field. Rice [Page 19] RFC 1203 IMAP3 February 1991 A007 FETCH 42 APPARENTLY-TO A007 FETCH APPARENTLY-TO NIL A007 OK FETCH found no value. fetches the concrete apparently-to field. tag STORE sequence data value The STORE command alters the values associated with particular keys for a message in the mailbox. As is the case for the FETCH command, any generic, canonical or concrete key may be used to index the value provided. In addition to these, the following pre-defined keys are provided. FLAGS Replace the flags for the message with the argument (in flag list format). The server must respond with a solicited STORE FLAGS message, showing the new state of the flags after the store. +FLAGS Add the flags in the argument to the message's flag list. The server must respond with a solicited STORE FLAGS message, showing the new state of the flags after the store. -FLAGS Remove the flags in the argument from the message's flag list. The server must respond with a solicited STORE FLAGS message, showing the new state of the flags after the store. RFC822.HEADER Replace the header of the message(s) with that specified. This allows users to use their mailboxes as databases with header fields as keys. The server must respond with solicited STORE RFC822.HEADER, STORE RFC822.SIZE and STORE ENVELOPE messages, showing the new state of the reparsed header after the store. RFC822.TEXT Replace the body of the messages with that specified. The server must respond with solicited STORE RFC822.TEXT and STORE RFC822.SIZE messages, showing the new state of the message after the store. STORE is not allowed if the user does not have write access to this mailbox. The server is required to send a solicited STORE response for Rice [Page 20] RFC 1203 IMAP3 February 1991 each store operation that results in a format transformation by the server. For example, the server is required to send a STORE FLAGS response when the client performs a STORE +FLAGS or a STORE -FLAGS, since the client may not easily be able to know what the result of this command will be. Similarly, if the client emits a STORE FROM command then the server should respond with a suitable STORE FROM response because the client would be sending a string value to be stored and the server should transform this into a set of addresses. In general, however, although it is legal for the server to send a solicited STORE response for each STORE operation, this is discouraged, since it might result in the retransmission of very large and unnecessary amounts of data that have been stored. EXAMPLE: A003 STORE 2:4 +FLAGS (\DELETED) marks messages 2, 3, and 4 for deletion. tag SEARCH search_criteria The SEARCH command searches the mailbox for messages which match the given set of criteria. The server response SEARCH (criteria) (numbers) gives the set of messages which match the conjunction of the criteria specified. In addition to each of the search criteria there is its logical inverse. The logical inverse criterion is denoted by the ~ (tilda) sign. Thus, no message that matches the criterion: FROM crispin will match the criterion: ~FROM crispin The criteria for the search can be any generic, canonical or concrete key. In addition to these, the following pre-defined keys are also provided: ALL All messages in the mailbox; the default initial criterion for ANDing. ANSWERED Messages with the \ANSWERED flag set. BCC string Messages which contain the specified string in the envelope's BCC field. BEFORE date Messages whose internal date is earlier than the specified date. Rice [Page 21] RFC 1203 IMAP3 February 1991 BODY string Messages which contain the specified string in the body of the message. CC string Messages which contain the specified string in the envelope's CC field. DELETED Messages with the \DELETED flag set. FLAGGED Messages with the \FLAGGED flag set. FROM string Messages which contain the specified string in the envelope's FROM field. HEADER string Messages which contain the specified string in the message header. KEYWORD flag Messages with the specified flag set. NEW Messages which have the \RECENT flag set but not the \SEEN flag. This is functionally equivalent to "RECENT UNSEEN". OLD Messages which do not have the \RECENT flag set. ON date Messages whose internal date is the same as the specified date. RECENT Messages which have the \RECENT flag set. SEEN Messages which have the \SEEN flag set. SINCE date Messages whose internal date is later than the specified date. SUBJECT string Messages which contain the specified string in the envelope's SUBJECT field. TEXT string Messages which contain the specified string. TO string Messages which contain the specified string in the envelope's TO field. EXAMPLE: A003 SEARCH DELETED FROM "SMITH" SINCE 1-OCT-87 returns the message numbers for all deleted messages from Smith that were placed in the mailbox since October 1, 1987. Implementation note: The UNANSWERED, UNDELETED, UNFLAGGED, Rice [Page 22] RFC 1203 IMAP3 February 1991 UNKEYWORD and UNSEEN criteria, described below, are preserved in IMAP3 for IMAP2 compatibility. They are, however, considered obsolete and new Client programs are encouraged to use the ~ notation for the logical inverses of search criteria with a view to the dropping of this outmoded syntax in later versions. UNANSWERED Messages which do not have the \ANSWERED flag set. UNDELETED Messages which do not have the \DELETED flag set. UNFLAGGED Messages which do not have the \FLAGGED flag set. UNKEYWORD flag Messages which do not have the specified flag set. UNSEEN Messages which do not have the \SEEN flag set. tag READONLY The READONLY command indicates that the client wishes to make the mailbox read-only. The server is required to reply with a solicited READONLY or READWRITE response. tag READWRITE The READWRITE command indicates that the client wishes to make the mailbox read-write. The server is required to reply with a solicited READONLY or READWRITE response. tag SUPPORTED.VERSIONS The SUPPORTED.VERSIONS solicits from the server a SUPPORTED.VERSIONS message, which encapsulates information about which versions and features the server supports. tag SELECT.VERSION (major_version minor_version) The SELECT.VERSION command indicates that the client wishes to select certain behavior on the part of the server. The major and minor versions indicate the specific version of the protocol being selected. EXAMPLE: A002 SELECT.VERSION (3 0) A client may not request a server version that is not supported by Rice [Page 23] RFC 1203 IMAP3 February 1991 the server, i.e., which is specifically mentioned in the response to a SUPPORTED.VERSIONS command. An attempt to do so by a client will result in a NO response from the server. It is an error for the SELECT.VERSION command to be used after a mailbox has been selected. The rationale for this is that for some server implementations it might be necessary to spawn separate programs to implement widely divergent protocol versions. Thus, the client cannot be allowed to expect any server state to be preserved after the use of the SELECT.VERSION command. The default version of all servers is 2.0, i.e., IMAP2 as defined by RFC 1064. tag SELECT.FEATURES 1#features The SELECT.FEATURES command indicates that the client wishes to select certain specific features on the part of the server. A client may not request a feature that is not supported by the server, i.e., one that is explicitly mentioned in the set of features for the selected version returned by the SUPPORTED.VERSIONS command. An attempt to do so by a client will result in a NO response from the server. EXAMPLE: A002 SELECT.FEATURES AUTO.SET.SEEN ~TAGGED.SOLICITED EIGHT.BIT.TRANSPARENT i.e., select the set of features called AUTO.SET.SEEN and EIGHT.BIT.TRANSPARENT and deselect the feature called TAGGED.SOLICITED. The use of the SELECT.FEATURES command completely resets the set of selected features. Note: These are only example feature names and are not necessarily supported by any server. See the appendix on features for more information on features. Note: Some features, when present in the server, will cause the upwards compatible extension of the grammar, i.e., by adding extra commands. The server is at liberty not to remove these upwards compatible extensions to the command tables when a feature is disabled. Thus, it is an error for a client to rely on getting a NO or BAD response in any way, for instance to determine the selectedness or presence of a feature. tag BBOARD bboard The BBOARD command is equivalent to SELECT, except that its argument is a bulletin board (BBoard) name. The format of a BBoard name is implementation specific, although it is strongly encouraged to use something that resembles a name in a generic sense and not a file or mailbox name on the particular system. There is no requirement that a BBoard name be a mailbox name or a file name (in particular, Unix netnews has a completely different namespace from mailbox or file names). Rice [Page 24] RFC 1203 IMAP3 February 1991 The result from the BBOARD command is identical from that of the SELECT command. For example, in the TOPS-20 server implementation, the command A0002 BBOARD FOO is exactly equivalent to the command A0002 SELECT POBOX:FOO.TXT Note: the equivalence in this example is *not* required by the protocol, and merely reflects the fuzzy distinction between mailboxes and BBoards on TOPS-20. tag FIND (BBOARDS / MAILBOXES) pattern The FIND command accepts as arguments the keywords BBOARDS or MAILBOXES and a pattern which specifies some set of BBoard/mailbox names which are usable by the BBOARD/SELECT command. Two wildcard characters are defined; "*" specifies that any number (including zero) characters may match at this position and "%" specifies that a single character may match at this position. For example, FOO*BAR will match FOOBAR, FOOD.ON.THE.BAR and FOO.BAR, whereas FOO%BAR will match only FOO.BAR; furthermore, "*" will match all BBoards/mailboxes. The following quoting convention applies to wildcards: "\*" is the literal "*" character, "\%" is the literal "%" character and "\\" is the literal "\" character. Notes: The format of mailboxes is server implementation dependent. The special mailbox name INBOX is not included in the output to the FIND MAILBOXES command. The FIND command solicits any number of BBOARD or MAILBOX responses from the server as appropriate. Examples: A0002 FIND BBOARDS * A0002 BBOARD FOOBAR A0002 BBOARD GENERAL A0002 OK FIND completed or A0002 FIND MAILBOXES FOO%BA* A0002 MAILBOX FOO.BAR A0002 MAILBOX FOO.BAZZAR A0002 OK FIND completed Note: Although the use of explicit file or path names for mailboxes is discouraged by this standard, it may be unavoidable. It is important that the value returned in the MAILBOX solicited reply be usable in the SELECT command without remembering any path specification which may have been used in the FIND MAILBOXES pattern. Rice [Page 25] RFC 1203 IMAP3 February 1991 tag FLAGS The FLAGS command solicits a FLAGS response from the server. tag SET.FLAGS flag_list The SET.FLAGS command defines the user specifiable flags for this mailbox, i.e., the keywords. If this set does not include flags formerly sent to the client by the server in a FLAGS message then this constitutes a request to delete the flag. Any new flags should be created. This command does not affect the system defined flags and any system flags that are included in the flag_list will be ignored. The server must respond to this command with a solicited FLAGS message. If the deletion of a flag results in the invalidation of the flag sets of any messages then the server is required to send solicited STORE FLAGS messages to the client for each modified message. Responses: */tag OK text In its solicited form this response identifies successful completion of the command with the indicated tag. The text is a line of human-readable text which may be useful in a protocol telemetry log for debugging purposes. In its unsolicited form, this response indicates simply that the server is alive. No special action on the part of the client is called for. This is presently only used by servers at startup as a greeting message indicating that they are ready to accept the first comm