Network Working Group Mark Crispin Internet Draft: IMAP4 University of Washington Obsoletes: RFC 1176, 1064, draft-ietf-imap-imap2bis-**.txt March 1994 Document: internet-drafts/draft-ietf-imap-imap4-01.txt INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4 Status of this Memo This document is an Internet Draft. Internet Drafts are working documents of the Internet Engineering Task Force (IETF), its Areas, and its Working Groups. Note that other groups may also distribute working documents as Internet Drafts. Internet Drafts are draft documents valid for a maximum of six months. Internet Drafts may be updated, replaced, or obsoleted by other documents at any time. It is not appropriate to use Internet Drafts as reference material or to cite them other than as a "working draft" or "work in progress". Please check the I-D abstract listing contained in each Internet Draft directory to learn the current status of any this or any other Internet Draft. This is a draft document of the IETF IMAP Working Group. It is a preliminary specification of the IMAP4 protocol, based upon the IMAP2bis Internet drafts, unpublished IMAP2bis.TXT document, RFC 1176, and RFC 1064. Proposed extensions to the IMAP4 protocol still under discussion are not documented here. A revised version of this draft document will be submitted to the RFC editor as a Proposed Standard for the Internet Community. Discussion and suggestions for improvement are requested. This document will expire before 31 July 1994. Distribution of this draft is unlimited. Comments are solicited and should be sent to imap@CAC.Washington.EDU. Crispin [Page 1] Internet Draft IMAP4 March 8, 1994 Introduction The Internet Message Access Protocol, Version 4 (IMAP4) allows a client to access and manipulate electronic mail messages on a server. IMAP4 is designed to permit manipulations of remote message folders, called "mailboxes", as if they were local. IMAP4 includes operations for creating, deleting, and renaming mailboxes; checking for new messages; permanently removing messages; setting and clearing flags; RFC 822 and MIME parsing; searching; and selective fetching of message attributes, texts, and portions thereof. IMAP4 does not specify a means of posting mail; this function is handled by a mail transfer protocol such as SMTP (RFC 821). IMAP4 is designed to be upwards compatible from the IMAP2 protocol described in RFC 1176. IMAP4 assumes a reliable data stream such as provided by TCP. When TCP is used, an IMAP4 server listens on port 143. Crispin [Page 2] Internet Draft IMAP4 March 8, 1994 System Model and Philosophy There are three fundamental models of client/server email: offline, online, and disconnected use. IMAP4 can be used in any one of these three models. The offline model is the most familiar form of client/server email today, and is used by protocols such as POP-3 (RFC 1225) and UUCP. In this model, a client application periodically connects to a server. It downloads all the pending messages to the client machine and deletes these from the server. Thereafter, all mail processing is local to the client. This model is store-and-forward; it moves mail on demand from an intermediate server (maildrop) to a single destination machine. The online model is most commonly used with remote filesystem protocols such as NFS. In this model, a client application manipulates mailbox data on a server machine. A connection to the server is maintained throughout the session. No mailbox data are kept on the client; the client retrieves data from the server as is needed. IMAP4 introduces a form of the online model that requires considerably less network bandwidth than a remote filesystem protocol, and provides the opportunity for using the server for CPU or I/O intensive functions such as parsing and searching. The disconnected use model is a hybrid of the offline and online models, and is used by protocols such as PCMAIL (RFC 1056). In this model, a client user downloads some set of messages from the server, manipulates them offline, then at some later time uploads the changes. The server remains the authoritative repository of the messages. The problems of synchronization (particularly when multiple clients are involved) are handled through the means of unique identifiers for each message. Each of these models have their own strengths and weaknesses: Feature Offline Online Disc ------- ------- ------ ---- Can use multiple clients NO YES YES Minimum use of server connect time YES NO YES Minimum use of server resources YES NO NO Minimum use of client disk resources NO YES NO Multiple remote mailboxes NO YES YES Fast startup NO YES NO Mail processing when not online YES NO YES Although IMAP4 has its origins as a protocol designed to accommodate the online model, it can support the other two models as well. This Crispin [Page 3] Internet Draft IMAP4 March 8, 1994 makes possible the creation of clients that can be used in any of the three models. For example, a user may wish to switch between the online and disconnected models on a regular basis (e.g. owing to travel). IMAP4 is designed to transmit message data on demand, and to provide the facilities necessary for a client to decide what data it needs at any particular time. There is generally no need to do a wholesale transfer of an entire mailbox or even of the complete text of a message. This makes a difference in situations where the mailbox is large, or when the link to the server is slow. More specifically, IMAP4 supports server-based RFC 822 and MIME processing. With this information, it is possible for a client to determine in advance whether it wishes to retrieve a particular message or part of a message. For example, a user connected to an IMAP4 server via a dialup link can determine that a message has a 2000 byte text segment and a 40 megabyte video segment, and elect to fetch only the text segment. In IMAP4, the client/server relationship lasts only for the duration of the TCP connection, and mailbox state is maintained on the server. There is no registration of clients. Except for any unique identifiers used in disconnected use operation, the client initially has no knowledge of mailbox state and learns it from the IMAP4 server when a mailbox is selected. This initial transfer is minimal; the client requests additional state data as it needs. Crispin [Page 4] Internet Draft IMAP4 March 8, 1994 Protocol Overview The IMAP4 protocol consists of a sequence of operations consisisting of a client command, server data, and a server command result response. Unlike most Internet protocols, both client commands and server command result 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 server command result response is given the same tag as the client command. Data and non-result responses from the server are identified by the special reserved tag of "*". These are conventionally referred to as "untagged data" or "unsolicited responses". This reflects the fact that the server may send an arbitrary amount of "untagged data" in addition to any data specifically requested in the current command. There is no syntactic difference between data responses which result from a specific command and those which are sent unilaterally by the server. One form of unilaterally transmitted untagged data that commonly occurs is an alert of a change to the mailbox made by some process other than the IMAP4 client or server; for example, changes in the size of the mailbox (new mail) or in the status of individual messages. An example of a unilaterally transmitted non-result response is an announcement of an impending server shutdown. There is another special reserved tag, "+", discussed below. The server must be listening for a connection. When a connection is opened the server sends a greeting message and then waits for commands. This greeting is either a PREAUTH (meaning that the user has already been identified and authenticated by an external mechanism such as rsh) or OK (meaning that the user is not yet authenticated) unsolicited response. The server may also send a BYE unsolicited response and close the connection if it rejects the connection. The client opens a connection and waits for the greeting. The client must not send any commands until it has received the greeting from the server. Once the greeting has been received, the client may begin sending commands. It is not under any obligation to wait for a server response to a command before sending another command, subject to the constraints of underlying flow control. When commands are received the server acts on them and responds with command result responses, often prefixed by some amount of server untagged data. Crispin [Page 5] Internet Draft IMAP4 March 8, 1994 In general, the command result responses do not themselves contain the requested data. Instead, they indicate the completion status of the request. There are three fundamental command result responses: success (OK), error (NO), request faulty or not understood (BAD). The effect of a command can not be considered complete until a command result response with a tag matching the command is received from the server. It is not required that a server process a command to completion before beginning processing of the next command, except when the processing of the previous command may affect the results of the next command by changing the state of the current mailbox. This rule has certain other effects; for example, this implies that an EXPUNGE response can not be transmitted as part of a response to a command that uses sequence numbers, because EXPUNGE responses result in message numbers being changed. Client implementations should update their local cache of data with any untagged data received from the server. Unlike command result responses, untagged data are not necessarily associated with specific commands. The tagged command result response signals that the client cache is now updated with the results of the corresponding command. One artifact of this rule is the way new mail notification from the server to the client takes place. If, during the execution of any command, the server observes that the mailbox size has changed, the server should alert the client by sending unsolicited EXISTS and RECENT responses reflecting the changed size. Similarly, any observed change in message status should cause an unsolicited FETCH response with the new flag data. If authentication has not yet been completed, it must now be done via the LOGIN command before any access to data is permitted. The only permitted commands before successful authentication are LOGIN, NOOP, and LOGOUT. See the section below on authentication. Once authenticated, the client must send a mailbox selection command to access the desired mailbox. No mailbox is selected by default. The interpretation of mailbox names is implementation-dependent. However, the mailbox name INBOX is a special name reserved to mean "the primary mailbox for this user on this server". If it is desired to export hierarchical mailbox names, mailbox names must be left-to- right hierarchical using a single character to separate levels of hierarchy. The same hierarchy separator character is used for all levels of hierarchy within a single name. By convention, if the name of the first hierarchical element of a a Crispin [Page 6] Internet Draft IMAP4 March 8, 1994 mailbox name starts with a "#", this element is considered to be the identifier of a well-known collection of mailboxes or "namespace". For example, some IMAP implementations may wish to partition netnews mailboxes from other mailboxes using a "#news" namespace, and would export the newsgroup named "comp.mail.misc" as "#news.comp.mail.misc". The implementation-dependent interpretation of mailbox names permits some names to be interpreted on a per-user basis and other names to be interpreted on a systemwide basis. For example, a UNIX-based server might interpret names such as "foo", "mail/blurdybloop", and "#backup/gazonk" as per-user; and names such as "/usr/lib/imap.msgs" and "#news.comp.mail.misc" as systemwide. On a successful selection, the server will send a list of valid flags, number of messages, and number of messages arrived since last access for this mailbox as untagged data, followed by an OK command result response. The client may close access to this mailbox and access a different one by sending another selection command. Several flags are predefined in IMAP4. All predefined IMAP4 flags (called, for historical reasons, "system flags") begin with a backslash ("\") character. Servers MUST, at a minimum, support all the predefined flags in this specification. In addition, a server may also have some implementation-defined per-mailbox flags (called, for historical reasons, "keywords") that do not begin with backslash. Clients should use the information from the server's FLAGS response at message selection time to determine what flags the server supports for the currently selected mailbox. The client requests mailbox data with FETCH commands, and receives it via the untagged data mechanism. Three major categories of mailbox data exist. The first category is data that are associated with a message as an entity in the mailbox. There are now four such items of data: the "internal date", the "RFC 822 size", the "flags", and the "unique id". The internal date is the date and time of final delivery of the message as defined by SMTP (RFC 821). The RFC 822 size is the size in octets of the message, expressed as an RFC 822 text string. The flags are status flags associated with the message. The unique id is an identifier that is guaranteed to refer to this message and to none other in the mailbox and that, unlike IMAP4 sequence numbers, persists across sessions and never changes as a result of an EXPUNGE. The second category is data that describe the composition and delivery information of a message; that is, information such as the message sender, recipient lists, message-ID, subject, MIME structure, Crispin [Page 7] Internet Draft IMAP4 March 8, 1994 etc. This is the information that is stored in the RFC 822 and MIME headers. In IMAP4, the RFC 822 header information that may be fetched is called the "envelope structure" (not to be confused with SMTP (RFC 821) envelopes). Similarly, the MIME header information that may be fetched is called the "body structure". A client can use the parsed envelope and body structures and not worry about having to do its own RFC 822 or MIME parsing. The third category is textual data, some of which are intended for direct human viewing. IMAP4 defines six such items: RFC822.HEADER, RFC822.HEADER.LINES, RFC822.HEADER.LINES.NOT, RFC822.TEXT, RFC822, and MIME body parts. It is possible to fetch an individual MIME body part of a message without fetching any other data associated with the message. A simple client can "FETCH RFC822" to get the entire message without any processing. A more advanced client might fetch some combination of the first and second categories of data for use as a presentation menu. Then, when the user wishes to read a particular message, it will fetch the appropriate texts. Individual data items in IMAP4 are represented as atoms (one or more non-special characters), strings (a quoted sequence of characters), or numbers. Some data items may be either atoms or strings. The atom "NIL" represents the non-existence of a data item, as distinct from the empty string "" or empty list (). Data structures in IMAP4 are represented as an S-expression list similar to that used in the Lisp programming language. An S- expression consists of a sequence of data items delimited by space and bounded at each end by parentheses. An S-expression may itself contain other S-expressions, using parentheses to indicate nesting. S-expression syntax was chosen because it provides a concise and precise means of expressing nested data (e.g. MIME structures). The client can alter certain data with a STORE command. As an example, a message is marked for deletion from a mailbox by setting the \Deleted flag with a STORE command. Other client operations that can be done to a mailbox include copying messages to other mailboxes, permanently removing messages that are marked as deleted, checking for updated mailbox state, and searching for messages that match certain criteria. It is also possible to select a different mailbox, create a new mailbox, rename an existing mailbox, or delete an existing mailbox. The client should end the session with the LOGOUT command. The server returns a "BYE" followed by an "OK", at which point both the Crispin [Page 8] Internet Draft IMAP4 March 8, 1994 client and the server close the connection. If the client closes the network connection without a LOGOUT command, the server should do its normal logout procedures without attempting any further interaction with the client. Crispin [Page 9] Internet Draft IMAP4 March 8, 1994 Authentication Pre-authentication is only possible when the connection to the IMAP4 service is made through some link protocol that provides its own authentication mechanism. It is not used with a TCP connection to port 143. An example of pre-authentication is the BSD "RSH" protocol, that provides authentication through a "trusted host" facility. Another example would be a manual invocation of an IMAP4 server from a logged-in timesharing job. A pre-authenticated IMAP4 server should recognize that authentication has already happened, and enter the post-login state. In its greeting message, it should use the unsolicited response "PREAUTH" instead of "OK" to indicate that external authentication has taken place. This is an example of a pre-authentication scenario. In this and all other examples in this document, S: indicates server dialog and C: indicates client dialog. S: * PREAUTH IMAP4 Server pre-authenticated as user "Smith" C: A001 SELECT INBOX S: * FLAGS (\Answered \Flagged \Deleted \Seen \Junked) S: * 19 EXISTS S: * 2 RECENT S: * OK [UNSEEN 14] Message 14 is the first unseen message S: A001 OK SELECT complete A connection that is not pre-authenticated is constrained to using the LOGIN command for establishing authentication. Authentication via the LOGIN command is with either a user name and password pair, or with a user identifier and Kerberos authenticator. See the description of the LOGIN command for more details. Servers may allow non-authenticated access to certain mailboxes. The convention is to use a LOGIN command with the userid "anonymous". A password is still required. It is implementation-dependent what requirements, if any, are placed on the password and what access restrictions are placed on anonymous users. Implementations are NOT required to support pre-authentication, Kerberos authentication, or the anonymous convention. Crispin [Page 10] Internet Draft IMAP4 March 8, 1994 Summary of Defined Commands and Responses Commands || Responses -------- || --------- || Pre-Authentication Commands || Tagged Command Result Responses --------------------------- || ------------------------------- NOOP / LOGIN / LOGOUT || OK / NO / BAD || Mailbox Management || Untagged Status Responses ------------------ || ------------------------- CREATE / DELETE / RENAME || PREAUTH / OK / NO / BAD / BYE LIST / LSUB / SUBSCRIBE / || UNSUBSCRIBE || Untagged Listing Responses || -------------------------- Mailbox Selection || LIST / LSUB ----------------- || SELECT / EXAMINE || Untagged Data Responses || ----------------------- Message Management || FLAGS / SEARCH ------------------ || EXISTS / RECENT / EXPUNGE CHECK / EXPUNGE || FETCH || Message Copying || Command Continuation Ready Response --------------- || APPEND / COPY || || Message Data Transfer || FETCH / PARTIAL / STORE / || SEARCH / UID / x_command || Note: this listing is only of the commands and responses which are part of the IMAP4 protocol and not deprecated. Crispin [Page 11] Internet Draft IMAP4 March 8, 1994 Commands tag NOOP The NOOP command returns an OK to the client. By itself, it does nothing else. However, since any command can return a status update as untagged data, this command can be used to poll for new mail or for message status updates. Another possible use of this command is for the client to "ping" the server so that the client and server know that each other are still alive. This is useful with servers that have an inactivity autologout timer. 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: C: a001 LOGIN SMITH SESAME S: a001 OK LOGIN completed logs in as user SMITH with password SESAME. If a server supports authentication via Kerberos, it may accept the string "@KERBEROS:" followed by the hexadecimal representation of a Kerberos authenticator. EXAMPLE: The following is a Kerberos login scenario (note that the line breaks in the sample authenticator are for editorial clarity and are not in a real authenticator): S: * OK Kerberos IMAP4 Server C: a001 LOGIN smith @KERBEROS:040700414e445245572e434d552e4544550 038202c868f3890b377fc8266acc1bedb96b80d3fa76489898e74cd1c952dc 4003ea3428f29f1c470016cf5adc22f939e6deff2747254c1815d5b0b90d4c 5a2cba21eb0abe32f9acbf568d751bf4cc13f5ba4e6d82c638a8b5421 S: a001 OK [df84a4cb8323454f] Login OK via Kerberos The token in the brackets in the OK response is the Kerberos authentication response, encrypted with the session key in network byte order and an incremented checksum as in the usual Kerberos procedure. Crispin [Page 12] Internet Draft IMAP4 March 8, 1994 tag LOGOUT The LOGOUT command informs the server that the client is done with the session. The server should send an unsolicited BYE response before the (tagged) OK response, and then close the network connection. EXAMPLE: C: A023 LOGOUT S: * BYE IMAP4 Server logging out S: A023 OK LOGOUT completed Server and client then close the connection. Mailbox manipulation commands - CREATE, DELETE, RENAME These commands permit the manipulation of entire mailboxes. tag CREATE mailbox The CREATE command creates a mailbox with the given name. This command returns an OK response only if a new mailbox with that name has been created. It is an error to attempt to create a mailbox with a name that refers to an extant mailbox. Any error in creation will return a NO response. If the mailbox argument is suffixed with the hierarchy separator character (obtained from the server via a LIST command), this is a declaration to the server that the client may, in the future, create mailbox names under this name in the hierarchy. Server implementations that do not require this declaration should ignore it. Discussion: The IMAP4 protocol permits the selection of non-terminal names in the hierarchy as mailboxes, and the creation of new names under a formerly terminal name in the hierarchy. In some server implementations, it may not be possible for a name to be both a level of hierarchy and a selectable mailbox, or only certain classes of mailbox may be at non-terminal levels of hierarchy. The hierarchy separator character suffix provides the necessary hint for the server to choose which type of name to create. Creating INBOX is not permitted. EXAMPLES: C: a003 CREATE blurdybloop S: a003 OK CREATE completed creates a mailbox named "blurdybloop". Crispin [Page 13] Internet Draft IMAP4 March 8, 1994 C: a004 CREATE owatagusiam/ S: a004 OK CREATE completed C: a005 CREATE owatagusiam/blurdybloop S: a005 OK CREATE completed where "/" was returned as the hierarchy separator from LIST, creates a new level of hierarchy named "owatagusiam", and then creates a mailbox named "blurdybloop" inside "owatagusiam". tag DELETE mailbox The DELETE command deletes a mailbox with the given name. This command returns an OK response only if a mailbox with that name has been deleted. It is an error to attempt to delete a mailbox name that does not exist. Any error in deletion will return a NO response. A server SHOULD NOT attempt to test that a mailbox is empty before permitting deletion; this would prevent the deletion of a mailbox that for some reason can not be opened or expunged, leaving to possible denial of service problems. Any such checking should be left to the discretion of the client. Deleting INBOX is not permitted. EXAMPLE: C: a003 DELETE blurdybloop S: a003 OK DELETE completed deletes the mailbox named "blurdybloop". tag RENAME old_mailbox new_mailbox The RENAME command changes the name of a mailbox. This command returns an OK response only if a mailbox with the old name exists and has been successfully renamed to the new name. It is an error to attempt to rename with an old mailbox name that does not exist or a new mailbox name that already exists. Any error in renaming will return a NO response. Renaming INBOX is permitted. A new, empty INBOX is created in its place. EXAMPLE: C: a003 RENAME blurdybloop owatagusiam S: a003 OK RENAME completed renames the mailbox named "blurdybloop" to the new name "owatagusiam". Crispin [Page 14] Internet Draft IMAP4 March 8, 1994 Listing commands - LIST, LSUB The listing commands accept two arguments; a reference, and a mailbox name with possible wildcards. These commands return some set of unsolicited replies that have as their value a list of attributes, a separator character, and a mailbox name. An empty ("" string) reference argument indicates that the mailbox name is interpreted as by SELECT. The returned mailbox names MUST match the supplied mailbox name pattern. A non-empty reference argument is the name of a mailbox or a level of mailbox hierarchy. It identifies a context in which the mailbox name is interpreted in an implementation-defined manner. The returned mailbox names are canonicalized to a single unambiguous left-to-right hierarchy with a single separator character. Any part of the reference included in the returned mailbox name SHOULD be in the same form as the reference argument and not canonicalized into some other form. For example, on UNIX, a reference of "~smith/Mail" should not be canonicalized into "/u2/users/smith/Mail". Here are some examples of how references and mailbox names might be interpreted on a UNIX-based server: Reference Mailbox Name Interpretation ------------ ------------ -------------- ~smith/Mail/ foo.* ~smith/Mail/foo.* ~smith/Mail/ /usr/docs/foo /usr/docs/foo archive/ % archive/% archive/ ~jones/Mail/* ~jones/Mail/* #news. comp.mail.* #news.comp.mail.* Three wildcard characters are defined in the mailbox name argument: * zero or more characters may match at this position % zero or more characters, except for a hierarchy delimiter, may match at this position ? any single character (including a hierarchy delimiter) may match at this position For example, on a server in which "." is the hierarchy delimiter, and where the set of valid names are abc, bar, foobar, foodbar, foo.bar, and food.on.the.bar, the results from various references and patterns are: Crispin [Page 15] Internet Draft IMAP4 March 8, 1994 Reference Pattern Results --------- ------- ------- * abc, bar, foobar, foodbar, foo.bar, food.on.the.bar % abc, bar, (\Noselect) foo, (\Noselect) food, foobar, foodbar *bar bar, foobar, foodbar, foo.bar, food.on.the.bar %bar bar, foobar, foodbar foo?bar foodbar, foo.bar foo*bar foobar, foodbar, foo.bar, food.on.the.bar foo *bar foobar, foodbar, foo.bar, food.on.the.bar foo. *bar foo.bar Depending upon the implementation, the \Noinferiors attribute may also be associated with the names bar, foobar, foodbar, foo.bar, and food.on.the.bar. Servers are permitted to "hide" mailboxes from the wildcard characters by not having certain characters match the wildcards in certain situations. For example, a UNIX-based server might want to hide mailboxes such as "/usr/lib/imap.messages" from the pattern "*" by having an initial "/" character fail to match the wildcard characters. Two returned attributes are presently defined. \Noinferiors indicates that it is not possible for any child levels of hierarchy to exist under this name (that is, no child levels exist now and none can be created in the future). \Noselect indicates it is not possible to use this name as a selectable mailbox. The returned separator character delimits levels of hierarchy in a mailbox name. A client may use it to create child mailboxes, and to search higher or lower levels of naming hierarchy. All children of a top-level hierarchy node must use the same separator character. A NIL separator means that no hierarchy exists; the name is a "flat" name. The returned mailbox names MUST be valid as new references; and, unless \Noselect is indicated, they must also be valid as arguments for commands, such as SELECT, which accept mailbox names. tag LIST reference mailbox The LIST command accepts as arguments a reference name followed by a mailbox name, including possible wildcards, that specifies some subset of names from the complete set of all names available to the user. Zero or more unsolicted LIST replies Crispin [Page 16] Internet Draft IMAP4 March 8, 1994 are returned. The special name INBOX is included in the output from LIST if it matches the input arguments and INBOX is supported by this server for this user. The criteria for omitting INBOX is whether SELECT INBOX will return failure; it is not relevant whether the user's real INBOX resides on this or some other server. LIST and LSUB provide a mechanism for the user to identify that this is his or her real INBOX. The exact meaning of "names available to the user" is implementation-dependent, since the concept of a bounded or deterministic set of "mailboxes available to the user" may not be meaningful for a particular server or server implementation. EXAMPLE: C: A002 LIST "~/Mail/" "%" S: * LIST (\Noselect) "/" ~/Mail/foo S: * LIST () "/" ~/Mail/meetings S: A002 OK LIST completed tag LSUB reference mailbox The LSUB command accepts as arguments reference name followed by a mailbox name, including possible wildcards, that specifies some subset of names from the set of names that the user has declared as being "active" or "subscribed". Zero or more unsolicited LSUB replies are returned. The exact meaning of "subscribed" is implementation-dependent, since the concept of a set of "subscribed" names that is preserved across sessions may not be meaningful for a particular server or server implementation. EXAMPLE: C: A002 LSUB "#news." "comp.mail.*" S: * LSUB () "." #news.comp.mail.mime S: * LSUB () "." #news.comp.mail.misc S: A002 OK LSUB completed indicates that the user is subscribed to the two news groups listed, and to no other news groups with names beginning with "comp.mail.". tag FIND ALL.MAILBOXES mailbox This OBSOLETE command accepted a mailbox name, including possible wildcards, that specifies some subset of names from the complete set of all names available to the user. It Crispin [Page 17] Internet Draft IMAP4 March 8, 1994 returned zero or more unsolicted MAILBOX replies. The wildcard character "%" was treated identically to "?" in this command. It is not required to support FIND ALL.MAILBOXES in new implementations. It is documented here for the benefit of implementors who may wish to support it for compatibility with old software. tag FIND MAILBOXES mailbox This OBSOLETE command accepted a mailbox name, including possible wildcards, that specifies some subset of names from the set of names that the user has declared as being "active" or "subscribed". It returned zero or more unsolicited MAILBOX replies. The wildcard character "%" was treated identically to "?" in this command. It is not required to support FIND MAILBOXES in new implementations. It is documented here for the benefit of implementors who may wish to support it for compatibility with old software. Subscription commands - SUBSCRIBE, UNSUBSCRIBE These commands permit the manipulation of mailbox subscriptions. Subscription status should be preserved between sessions. tag SUBSCRIBE mailbox The SUBSCRIBE command adds the specified mailbox name to the list of "active" or "subscribed" mailboxes as returned by the LSUB command. This command returns an OK response only if the subscription is successful. The optional word "MAILBOX" may appear after "SUBSCRIBE". It has no effect on the execution of the command. EXAMPLES: C: A002 SUBSCRIBE comp.mail.mime S: A002 OK SUBSCRIBE completed C: A003 SUBSCRIBE MAILBOX comp.mail.misc S: A003 OK SUBSCRIBE completed Crispin [Page 18] Internet Draft IMAP4 March 8, 1994 tag UNSUBSCRIBE mailbox The UNSUBSCRIBE command removes the specified mailbox name from the list of "active" or "subscribed" mailboxes as returned by the LSUB command. This command returns an OK response only if the unsubscription is successful. The optional word "MAILBOX" may appear after "UNSUBSCRIBE". It has no effect on the execution of the command. EXAMPLES: C: A002 UNSUBSCRIBE comp.mail.mime S: A002 OK UNSUBSCRIBE completed C: A003 UNSUBSCRIBE MAILBOX comp.mail.misc S: A003 OK UNSUBSCRIBE completed tag SELECT mailbox This command selects a particular mailbox. The server must check that the user is permitted read access to this mailbox. Before returning an OK to the client, the server MUST send the following untagged data to the client: FLAGS mailbox's defined flags EXISTS the number of messages in the mailbox RECENT the number of messages added to the mailbox since the previous time this mailbox was read to define the initial state of the mailbox at the client. If it can not be determined which messages were added since the previous time a mailbox was read, then all messages SHOULD be considered recent. An example of this is if no "last read" time information is available or a read-only mailbox that does not permit a change of "last read" time. The server SHOULD also send an UNSEEN special information token in an unsolicited OK, indicating the first unseen message in the mailbox. If the client may not change the permanent state of one or more of the flags listed in the FLAGS unsolicited response, the server SHOULD send a PERMANENTFLAGS special information token in an unsolicited OK, listing the flags that the client may change permanently. Note that the PERMANENTFLAGS special information token can also be used to inform the client that it is possible to define new user flags. Multiple selection commands are permitted in a session. The previous mailbox is automatically deselected when a new selection is made. If concurrent access to multiple mailboxes is desired, Crispin [Page 19] Internet Draft IMAP4 March 8, 1994 the client should open additional sessions as needed. The text of an OK response to the SELECT command should begin with either the "[READ-ONLY]" or "[READ-WRITE]" special information token to show the mailbox's access status. Other special information tokens may be defined in a revision to this protocol. EXAMPLE: C: A002 SELECT INBOX S: * 172 EXISTS S: * 1 RECENT S: * OK [UNSEEN 12] Message 12 is the first unseen message S: * FLAGS (\Answered \Flagged \Deleted \Seen \Junked) S: A002 OK [READ-WRITE] SELECT completed tag EXAMINE mailbox The EXAMINE command is similar to SELECT, and returns the same output; however, the selected mailbox is identified as read-only and no changes are permitted to this mailbox. EXAMPLE: C: A002 EXAMINE blurdybloop S: * 17 EXISTS S: * 2 RECENT S: * OK [UNSEEN 8] Message 8 is the first unseen message S: * FLAGS (\Answered \Flagged \Deleted \Seen \Junked) S: A002 OK [READ-ONLY] EXAMINE completed tag CHECK The CHECK command requests a checkpoint of the mailbox. CHECK may cause an operation that may take a non-instantaneous amount of real-time to complete. The exact meaning of a checkpoint is implementation-dependent. Possible interpretations include forcing an update of the server's disk of all changes made to the selected mailbox, rescanning of the entire mailbox, etc. If an implementation has no such considerations, CHECK should be equivalent to NOOP. CHECK should NOT be used to poll for new mail; new mail checking happens implicitly as part of every command. NOOP should be used for any new mail polling. CHECK should NOT be used to get the current size of the mailbox; there is no guarantee that CHECK will cause an EXISTS or RECENT unsolicited response. EXAMPLE: C: a001 CHECK S: a001 OK CHECK completed Crispin [Page 20] Internet Draft IMAP4 March 8, 1994 tag EXPUNGE The EXPUNGE command permanently removes all messages with the \Deleted flag set from the currently selected mailbox. Before returning an OK to the client, for each message that is removed, an unsolicited EXPUNGE response is sent and the subsequent messages in the mailbox are immediately renumbered (see the description of the unsolicited EXPUNGE response for more details). EXAMPLE: C: A007 EXPUNGE S: 3 EXPUNGE S: 5 EXPUNGE S: 8 EXPUNGE S: A007 EXPUNGE completed In this example, messages 3, 6, and 10 had the \Deleted flag set. After message 3 was expunged, message 6 became message 5, and message 10 became message 9. After message 5 was expunged, message 9 became message 8. tag COPY sequence mailbox The COPY command copies the specified message(s) to the specified destination mailbox. The flags and internal date of the message(s) SHOULD be preserved in the copy. If the destination mailbox does not exist, a server SHOULD return an error. It SHOULD NOT automatically create the mailbox. Unless it is certain that the destination mailbox can not be created, the server MUST send the special information token "[TRYCREATE]" as the prefix of the text of the tagged NO response. This gives a hint to the client that it can attempt a CREATE command and retry the COPY if the CREATE is successful. If the COPY command is unsuccessful for any reason, IMAP4 server implementations MUST restore the destination mailbox to its prior state before the COPY attempt. EXAMPLE: C: A003 COPY 2:4 MEETING S: A003 COPY completed copies messages 2, 3, and 4 to mailbox "MEETING". tag APPEND mailbox [flag_list] [date_time] literal The APPEND command appends the literal argument as a new message in the specified destination mailbox. This argument is in the format of an RFC 822 message. If any flags or date_time are Crispin [Page 21] Internet Draft IMAP4 March 8, 1994 specified, those flags and internal date SHOULD be set in the resulting message. If the append is unsuccessful for any reason the mailbox must be restored to its prior state before the APPEND attempt; no partial appending is permitted. If the mailbox is currently selected, the normal new mail actions should occur. Server implementations SHOULD return a NO response if the length of the literal is zero. If the destination mailbox does not exist, a server MUST return an error, and MUST NOT automatically create the mailbox. Unless it is certain that the destination mailbox can not be created, the server MUST send the special information token "[TRYCREATE]" as the prefix of the text of the tagged NO response. This gives a hint to the client that it can attempt a CREATE command and retry the APPEND if the CREATE is successful. Note that this functionality is unsuitable for message delivery, because it does not provide a mechanism to transfer SMTP (RFC 821) envelope information. EXAMPLE: C: A003 APPEND saved-messages (\Seen) {311} C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) C: From: Fred Foobar C: Subject: afternoon meeting C: To: mooch@owatagu.siam.edu C: Message-Id: C: Mime-Version: 1.0 C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII C: C: Hello Joe, do you think we can meet at 3:30 tommorrow? C: S: A003 OK APPEND completed tag FETCH sequence data 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 currently defined data items that can be fetched are: ALL Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE) BODY Non-extensible form of BODYSTRUCTURE. This form is deprecated and its use should be avoided in new implementations. Crispin [Page 22] Internet Draft IMAP4 March 8, 1994 BODY[section] The text of a particular body section. The section specification is a set of one or more part numbers delimited by periods. Single-part messages only have a part 1. Multipart messages are assigned consecutive part numbers, as they occur in the message. If a particular part is of type message or multipart, its parts must be indicated by a period followed by the part number within that nested multipart part. It is not permitted to fetch a multipart part itself, only its individual members. A part of type MESSAGE and subtype RFC822 also has nested parts. These are the parts of the MESSAGE part's body. Nested part 0 of a part of type MESSAGE and subtype RFC822 is the RFC 822 header of the message. Every message has at least one part. EXAMPLE: Here is a complex message with its associated section specifications. 1 TEXT/PLAIN 2 APPLICATION/OCTET-STREAM 3 MESSAGE/RFC822 3.0 (RFC 822 header of the message) 3.1 TEXT/PLAIN 3.2 APPLICATION/OCTET-STREAM [4] MULTIPART/MIXED 4.1 IMAGE/GIF 4.2 MESSAGE/RFC822 4.2.0 (RFC 822 header of the message) 4.2.1 TEXT/PLAIN [4.2.2] MULTIPART/ALTERNATIVE 4.2.2.1 TEXT/PLAIN 4.2.2.2 TEXT/RICHTEXT Note that there is no section specification for the Multi-part parts (no section 4 or 4.2.2). The \Seen flag is implicitly set; if this causes the flags to change they should be included as part of the fetch results. BODY.PEEK[section] An alternate form of BODY[section] that does not implicitly set the \Seen flag. Crispin [Page 23] Internet Draft IMAP4 March 8, 1994 BODYSTRUCTURE The MIME body structure of the message. This is computed by the server by parsing the MIME header lines. ENVELOPE The envelope structure of the message. This is computed by the server by parsing the RFC 822 header into the component parts, defaulting various fields as necessary. FAST Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE) FLAGS The flags that are set for this message. FULL Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE BODY) INTERNALDATE The date and time of final delivery of the message as defined by RFC 821. RFC822 The message in RFC 822 format. The \Seen flag is implicitly set; if this causes the flags to change they should be included as part of the fetch results. This is the concatenation of RFC822.HEADER and RFC822.TEXT. RFC822.PEEK An alternate form of RFC822 that does not implicitly set the \Seen flag. RFC822.HEADER The RFC 822 format header of the message as stored on the server including the delimiting blank line between the header and the body. RFC822.HEADER.LINES header_list All header lines (including continuation lines) of the RFC 822 format header of the message with a field-name (as defined in RFC 822) that matches any of the strings in header_list. The matching is case-independent but otherwise exact. RFC822.HEADER.LINES.NOT header_list All header lines (including continuation lines) of the RFC 822 format header of the message with a field-name (as defined in RFC 822) that does not match any of the strings in header_list. The matching is case-independent but otherwise exact. Crispin [Page 24] Internet Draft IMAP4 March 8, 1994 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. The \Seen flag is implicitly set; if this causes the flags to change they should be included as part of the fetch results. RFC822.TEXT.PEEK An alternate form of RFC822.TEXT that does not implicitly set the \Seen flag. UID The unique identifier for the message. EXAMPLES: C: A003 FETCH 2:4 ALL fetches the flags, internal date, RFC 822 size, and envelope structure for messages 2, 3, and 4. C: A004 FETCH 3 RFC822 fetches the RFC 822 representation for message 3. C: A005 FETCH 4 (FLAGS RFC822.HEADER) fetches the flags and RFC 822 format header for message 4. C: A006 FETCH 3 BODY[4.1] fetches body part 4.1 for message 3. C: A007 FETCH 3 RFC822.HEADER.LINES (SUBJECT DATE TO CC FROM) fetches the five listed header lines for message 3. tag PARTIAL msgno data start_octet octet_count The PARTIAL command is equivalent to the associated FETCH command, with the added functionality that only the specified number of octets, beginning at the specified starting octet, are returned. Only a single message can be fetched at a time. The first octet of a message, and hence the minimum for the starting octet, is octet 1. The following FETCH items are valid data for PARTIAL: RFC822, RFC822.PEEK, RFC822.HEADER, RFC822.TEXT, RFC822.TEXT.PEEK, BODY[section], and BODY.PEEK[section]. Any partial fetch that attempts to read beyond the end of the text is truncated as appropriate. If the starting octet is beyond the end of the text, an empty string is returned. Crispin [Page 25] Internet Draft IMAP4 March 8, 1994 The data are returned with the FETCH response. There is no indication of the range of the partial data in this response; thus it is generally not possible to implement caching with PARTIAL data. It is also not possible to stream multiple PARTIAL commands of the same data item without processing and synchronizing at each step, since each PARTIAL fetch of data replaces any prior (PARTIAL) FETCH of the data. Note that a possible problem exists in partial fetching. It is possible to break in the middle of a line or a critical sequence such as a BASE64 quadruple or QUOTED-PRINTABLE shift. Implementations using partial fetching should keep this in mind. There is no requirement that partial fetches follow any sequence; so if it turns out that a partial fetch of octets 1 through 10000 breaks in an awkward place, it is permitted to continue with a partial fetch of 9987 through 19987, etc. The handling of the \Seen flag is the same as in the associated FETCH command. EXAMPLE: C: A005 PARTIAL 4 RFC822 1 1024 S: * 1 FETCH (RFC822 {1024} S: Return-Path: S: ... S: ......... FLAGS (\Seen)) S: A005 OK PARTIAL completed tag STORE sequence data value The STORE command alters data associated with a message in the mailbox. The currently defined data items that can be stored are: FLAGS Replace the flags for the message with the argument (in flag list format). +FLAGS Add the flags in the argument to the message's flag list. -FLAGS Remove the flags in the argument from the message's flag list. EXAMPLE: A003 STORE 2:4 +FLAGS (\Deleted) marks messages 2, 3, and 4 for deletion. Crispin [Page 26] Internet Draft IMAP4 March 8, 1994 tag UID command argument(s) The UID command takes as its arguments a COPY, FETCH, SEARCH, or STORE command with arguments appropriate for the associated command. However, instead of message numbers, it uses unique identifiers in the sequence argument to reference a particular message or range of messages. The unique identifier of a message is guaranteed not to refer to any other message in the mailbox. Unlike IMAP4 sequence numbers, unique identifiers persist across sessions. Sequence ranges are permitted; note however that there is no guarantee that unique identifiers be contiguous. A non-existent unique identifier within a sequence range is ignored without any error message generated. The number after the "*" in a message data response (most notably, FETCH) is always a message number, not a unique identifier, even in the case of a UID command response. However, servers MUST implicitly include UID as part of any FETCH response caused by a UID command, regardless of whether UID was specified as a FETCH data item. The numbers returned in a SEARCH response are unique identifiers in the case of a UID SEARCH. EXAMPLE: C: A003 UID FETCH 4827313:4828442 FLAGS S: * 23 FETCH (FLAGS (\Seen) UID 4827313) S: * 24 FETCH (FLAGS (\Seen) UID 4827943) S: * 25 FETCH (FLAGS (\Seen) UID 4828442) S: A003 UID FETCH completed Note that the UID was returned for each message, even though the FETCH request did not explicitly specify UID as a FETCH data item. tag SEARCH [search_charset] search_criteria The SEARCH command searches the mailbox for messages that match the given searching criteria. Searching criteria are in the form of one or more search keys. The unsolicited "SEARCH number(s)" response from the server is a list of message numbers corresponding to those messages which match the searching criteria. When multiple keys are specified, the result is the intersection (AND function) of all the messages that match those keys. For Crispin [Page 27] Internet Draft IMAP4 March 8, 1994 example, A003 SEARCH DELETED FROM "SMITH" SINCE 1-Feb-1994 returns the message numbers for all deleted messages from Smith that were placed in the mailbox since February 1, 1994. Search criteria may also contain one or more parenthesized groups of keys, for use with the OR and NOT keys. Server implementations MAY exclude MIME body parts with terminal content types other than TEXT and MESSAGE from consideration in SEARCH matching. The optional search_charset consists of the atom "CHARSET" followed by a registered MIME character set. It indicates the character set of subsequent strings used in the search criteria. RFC 1522 strings which appear in RFC 822/MIME message headers MUST be decoded prior to matching. Server implementations MUST also decode MIME content transfer encodings prior to matching. If the server does not support the specified character set, it must return a tagged NO response (not a BAD). However, server implementations MUST support the character set US-ASCII. In all search keys that use strings, a message matches the key if the string is a substring of the field. The matching is case- independent. The currently defined search keys are: sequence Messages within the specified sequence range. ALL All messages in the mailbox; the default initial key for ANDing. ANSWERED Messages with the \Answered flag set. BCC astring Messages that contain the specified string in the envelope structure's BCC field. BEFORE date Messages whose internal date is earlier than the specified date. BODY astring Messages that contain the specified string in the body of the message. CC astring Messages that contain the specified string in the envelope structure's CC field. DELETED Messages with the \Deleted flag set. Crispin [Page 28] Internet Draft IMAP4 March 8, 1994 FLAGGED Messages with the \Flagged flag set. FROM astring Messages that contain the specified string in the envelope structure's FROM field. HEADER header_line astring Messages that have a header with a field-name (as defined in RFC 822) of header_line and which contains the specified string in the RFC 822 field-body. JUNKED Messages with the \Junked flag set. KEYWORD flag Messages with the specified flag set. LARGER number Messages with an RFC822.SIZE larger than the specified number of characters. NEW Messages that have the \Recent flag set but not the \Seen flag. This is functionally equivalent to "(RECENT UNSEEN)". NOT search_key Messages that do not match the specified search key. OLD Messages that do not have the \Recent flag set. This is functionally equivalent to "NOT RECENT" (as opposed to "NOT NEW"). ON date Messages whose internal date is within the specified date. OR search_key1 search_key2 Messages which match either search key. RECENT Messages that have the \Recent flag set. SEEN Messages that have the \Seen flag set. SENTBEFORE date Messages whose RFC 822 Date: header is earlier than the specified date. SENTON date Messages whose RFC 822 Date: header is within the specified date. SENTSINCE date Messages whose RFC 822 Date: header is within or later than the specified date. Crispin [Page 29] Internet Draft IMAP4 March 8, 1994 SINCE date Messages whose internal date is within or later than the specified date. SMALLER number Messages with an RFC822.SIZE smaller than the specified number of characters. SUBJECT astring Messages that contain the specified string in the envelope structure's SUBJECT field. TEXT astring Messages that contain the specified string in the header or body of the message. TO astring Messages that contain the specified string in the envelope structure's TO field. UID sequence Messages with unique identifiers within the specified unique identifier sequence range. UNANSWERED Messages that do not have the \Answered flag set. UNDELETED Messages that do not have the \Deleted flag set. UNFLAGGED Messages that do not have the \Flagged flag set. UNJUNKED Messages that do not have the \Junked flag set. UNKEYWORD flag Messages that do not have the specified flag set. UNSEEN Messages that do not have the \Seen flag set. EXAMPLES: C: A003 SEARCH HEADER Keywords "Paris" matches messages with "Paris" in the Keywords header. C: A003 SEARCH NOT SUBJECT "Paris meeting" matches messages which don't have "Paris meeting" in the subject header. C: A007 SEARCH FROM SMITH (OR DELETED JUNKED) Messages which are from Smith and have the \Deleted or \Junked flag set. Crispin [Page 30] Internet Draft IMAP4 March 8, 1994 Responses Command Completion Responses This group of responses indicate the completion of a command, and whether or not that command was successful. These responses are tagged, using the tag from the command. The response text is a line of human readable text, optionally prefixed by data inside square brackets that convey a special information token and possible arguments. The currently defined special information tokens are: ALERT The human-readable text contains a special alert that MUST be presented to the user, preferably in a fashion that calls the user's attention to the message. PARSE An error occurred in parsing the RFC 822 or MIME headers of a message in the mailbox. PERMANENTFLAGS Followed by a list of flags, indicates which of the known flags that the client may change permanently. The special flag \* indicates that it is possible to create new user flags by attempting to store those flags in the mailbox. Any flags which are in the FLAGS unsolicited response, but not the PERMANENTFLAGS list, can not be set permanently. An attempt to STORE a flag that is not in the PERMANENTFLAGS list MUST either be rejected with a NO reply or affect the state for the remainder of the current session only. READ-ONLY The mailbox is open read-only, or its access while open has changed from read-write to read-only. READ-WRITE The mailbox is open read-write, or its access while open has changed from read-only to read-write. TRYCREATE An APPEND or COPY attempt failed because the target mailbox does not exist. The server sends this as a hint to the client that the operation would probably succeed if the mailbox is first created by means of the CREATE command. UNSEEN Followed by a decimal number, indicates the number of the first unread message. This is intended to be used with certain mailbox formats to assist the user in finding the first unread message in those cases Crispin [Page 31] Internet Draft IMAP4 March 8, 1994 where "unread" and "recent" are separate concepts. hex string A hexadecimal string is returned as a special information token to represent a Kerberos return authenticator. This only occurs in response to a LOGIN command that uses Kerberos authentication. Other special information tokens defined by particular client or server implementations should be prefixed with an "X" until they are added to a revision of this protocol. tag OK resp_text This response indicates successful completion of the command with that tag. The response text may be useful in a protocol telemetry log for debugging purposes. EXAMPLES: C: a001 LOGIN SMITH SESAME S: a001 OK LOGIN completed C: a002 EXAMINE old_archive ... S: a002 OK [READ-ONLY] EXAMINE completed tag NO resp_text This response indicates unsuccessful completion of the command with that tag. The response text is a line of human-readable text that probably should be displayed to the user in an error report by the client. EXAMPLE: C: a002 SELECT garply S: a002 NO SELECT failed: no such mailbox as "garply" tag BAD resp_text This response indicates faulty protocol received from the client. The response text is a line of human-readable text that should be recorded in any telemetry as part of a bug report to the maintainer of the client. EXAMPLES: C: quit S: quit BAD Missing command C: a002 BLURDYBLOOP S: a002 BAD Command unrecognized: BLURDYBLOOP Crispin [Page 32] Internet Draft IMAP4 March 8, 1994 Status Responses This group of responses convey status information, and are always untagged. The response text is a line of human readable text. As with command completion responses, the human readable text may have an optional prefix inside square brackets that conveys special information between cooperating servers and clients. * PREAUTH resp_text This response is one of three possible greetings at session startup. It indicates that the session has already been authenticated by external means and thus no LOGIN command is needed. * OK resp_text This response indicates an information message from the server. It does not indicate completion of any particular request, nor is it necessarily related to any request. The text is a line of human-readable text that should be presented to the user as an information message. This response is also one of three possible greetings at session startup. It indicates that the session is not yet authenticated and that a LOGIN command is needed. EXAMPLE: C: A002 SELECT INBOX S: ... S: * OK [UNSEEN 17] Message 17 is the first unseen message S: A002 OK SELECT completed * NO resp_text This response indicates a warning message from the server. It does not indicate completion of any request, nor is it necessarily related to any request. The text is a line of human-readable text that should be presented to the user as a warning of improper operation. EXAMPLES: S: * NO Disk is full, please delete unnecessary data S: * NO Server problem #23, please contact your administrator Crispin [Page 33] Internet Draft IMAP4 March 8, 1994 * BAD resp_text This response indicates a serious error message from the server. It does not indicate completion of any request, nor is it necessarily related to any request. It may also indicate a faulty command from the client in which a tag could not be parsed. The text is a line of human-readable text that should be presented to the user as a serious or possibly fatal error. EXAMPLE: S: * BAD Command line too long * BYE text This response indicates that the server is about to close the connection. The text is a line of human-readable text that should be displayed to the user in a status report by the client. This may be sent as part of a normal logout sequence, or as a panic shutdown announcement by the server. It is also used by some servers as an announcement of an inactivity autologout. This response is also one of three possible greetings at session startup. It indicates that the server is not willing to accept a session from this client. EXAMPLE: S: * BYE Autologout; idle for too long Data responses This group of responses convey data about the mailbox or messages inside the mailbox and 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. * LIST mstring This response occurs as a result of a LIST command. The mstring contains information about a name which matches the pattern in the command. EXAMPLE: C: A002 LIST "~/Mail/" "%" S: * LIST (\Noselect) "/" ~/Mail/foo S: * LIST () "/" ~/Mail/meetings S: A002 OK LIST completed Crispin [Page 34] Internet Draft IMAP4 March 8, 1994 * LSUB mstring This response occurs as a result of a LSUB command. The mstring contains information about a name which matches the pattern in the command. EXAMPLE: C: A002 LSUB "#news." "comp.mail.*" S: * LSUB () "." #news.comp.mail.mime S: * LSUB () "." #news.comp.mail.misc S: A002 OK LSUB completed * MAILBOX text_line This OBSOLETE response occurs as a result of the obsolete commands FIND MAILBOXES and FIND ALL.MAILBOXES. The text_line is a name which matches the pattern in the command. * SEARCH number(s) This response occurs as a result of a SEARCH command. The number(s) refer to those messages that match the search criteria. Each number is delimited by a space. EXAMPLE: C: A003 SEARCH from "Jones" S: * SEARCH 2 3 6 S: A003 SEARCH completed * FLAGS flag_list This response occurs as a result of a selection command. The flag list are the list of flags (at a minimum, the system-defined flags) that are applicable for this mailbox. Flags other than the system flags are a function of the server implementation. EXAMPLE: C: A002 SELECT INBOX S: * FLAGS (\Answered \Flagged \Deleted \Seen \Junked) ... * number message_data This response may occurs as a result of any command while a mailbox is selected. The message_data is one of the following: Crispin [Page 35] Internet Draft IMAP4 March 8, 1994 EXISTS The number of messages in the mailbox. RECENT The number of messages that have arrived since the previous time this mailbox was read. EXPUNGE The specified message number has been permanently removed from the mailbox, and the next message in the mailbox (if any) becomes that message number. The message number for each successive message in the mailbox is immediately decremented by 1; this means that if the last 5 messages in a 9-message mailbox are expunged the client will receive 5 unsolicited EXPUNGE responses for message 5. An unsolicited EXPUNGE response MUST NOT be sent except while responding to a request other than FETCH, STORE, or SEARCH. All references to message numbers sent after an unsolicited EXPUNGE response are adjusted to reflect the effect of the expunge. Discussion: a potential ambiguity exists with the FETCH, STORE, and SEARCH requests if the server is permitted to send unsolicited EXPUNGE responses. This is because these requests can be streamed. If two successive FETCH requests are streamed, and if during the time of the processing of the first request there is an expunge response, then the sequence of the second request is no longer valid. FETCH data This is the principal means that data about a message are returned to the client. The data are in an S-expression form, and consists of a sequence of pairs of data item name and their values. The current data items are: BODY Similar to BODYSTRUCTURE, but without the extension data. BODY[section] A string expressing the body contents of the specified section. The string should be interpreted by the client according to the content transfer encoding, body type, and subtype. Crispin [Page 36] Internet Draft IMAP4 March 8, 1994 Note that non-textual data are transfer encoded; therefore, the string is likely to be 7-bit US-ASCII. This is NOT necessarily the byte size or character set of the interpreted result. BODYSTRUCTURE An S-expression format list that describes the body structure of a message. This is computed by the server by parsing the RFC 822 header and body into the component parts, defaulting various fields as necessary. Multiple parts are indicated by S-expression nesting. Instead of a body type as the first element of the list there is a nested body. The second element of the list is the multipart subtype (mixed, digest, parallel, alternative, etc.). Extension data follows the multipart subtype. Extension data is never returned with the older BODY fetch, but may be returned with a BODYSTRUCTURE fetch. Extension data, if present, must be in the defined order. The extension data of a multipart body part are in the following order: body parameter list - an S-expression list of attribute/value pairs [e.g. (foo bar baz rag) where "bar" is the value of "foo" and "rag" is the value of "baz"] as defined in MIME. Any subsequent extension data are not yet defined in this version of the protocol. Such extension data consist of zero or more NILs, strings, numbers, and/or potentially nested lists of such data. Clients which do a BODYSTRUCTURE fetch MUST be prepared to accept such extension data. Servers MUST NOT send such extension data until it has been defined by a revision of this protocol. The basic fields of a non-multipart body part are in the following order: body type - a string giving the content type name as defined in MIME body subtype - a string giving the content subtype name as defined in MIME body parameter list - an S-expression list of attribute/value pairs [e.g. (foo bar baz rag) where "bar" is the value of "foo" and "rag" is Crispin [Page 37] Internet Draft IMAP4 March 8, 1994 the value of "baz"] as defined in MIME. body id - a string giving the content id as defined in MIME. body description - a string giving the content description as defined in MIME. body encoding - a string giving the content transfer encoding as defined in MIME. body size - a number giving the size of the body in octets. Note that this size is the size in its transfer encoding and not the resulting size after any decoding. A body type of type MESSAGE and subtype RFC822 contains, immediately after the basic fields, the envelope structure, body structure, and size in text lines of the encapsulated message. A body type of type TEXT contains, immediately after the basic fields, the size of the body in text lines. Note that this size is the size in its transfer encoding and not the resulting size after any decoding. Extension data follows the basic fields and the type-specific fields listed above. Extension data is never returned with the older BODY fetch, but may be returned with a BODYSTRUCTURE fetch. Extension data, if present, must be in the defined order. The extension data of a non-multipart body part are in the following order: body MD5 - a string giving the content MD5 value as defined in MIME Any subsequent extension data are not yet defined in this version of the protocol, and would be in the form described above under multipart extension data. ENVELOPE An S-expression format list that describes the envelope structure of a message. This is computed by the server by parsing the RFC 822 header into the component parts, defaulting various fields as necessary. The fields of the envelope structure are in the following order: date, subject, from, sender, reply-to, to, cc, bcc, in-reply-to, and message-id. Crispin [Page 38] Internet Draft IMAP4 March 8, 1994 The date, subject, in-reply-to, and message-id fields are strings. The from, sender, reply-to, to, cc, and bcc fields are lists of address structures. An address structure is an S-expression format list that describes an electronic mail address. The fields of an address structure are in the following order: personal name, source-route (a.k.a. the at-domain-list in SMTP (RFC 821)), mailbox name, and host name. RFC 822 group syntax is indicated by a special form of address structure in which the host name field is NIL. If the mailbox name field is also NIL, this is an end of group marker (semi-colon in RFC 822 syntax). If the mailbox name field is non-NIL, this is a start of group marker, and the mailbox name field holds the group name phrase. Any field of an envelope or address structure that is not applicable is presented as NIL. Note that the server must default the reply-to and sender fields from the from field; a client is not expected to know to do this. FLAGS An S-expression format list of flags that are set for this message. This may include the following system flags: \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 \Junked Message has been "junked" (dismissed as unwanted) as well as the following special flag: \Recent Message arrived since the previous time this mailbox was read Discussion: the \Junked flag can be thought of as the opposite of \Flagged; that is, junked messages have lower than normal priority. It differs from Crispin [Page 39] Internet Draft IMAP4 March 8, 1994 \Deleted in that a junked message is not removed from the mailbox by EXPUNGE. One possible use of the \Junked flag is with shared mailboxes (e.g. netnews) where it is impossible or undesirable to set \Deleted status. INTERNALDATE A string containing the date and time of final delivery of the message as defined by SMTP (RFC 821). RFC822 A string expressing the message in RFC 822 format. RFC822.HEADER A string expressing the RFC 822 format header of the message, including the delimiting blank line between the header and the body. This is used for the FETCH data items RFC822.HEADER, RFC822.HEADER.LINES, and RFC822.HEADER.LINES.NOT (note that a blank line is always included regardless of header line restrictions). RFC822.SIZE A number indicating the number of characters in the message as expressed in RFC 822 format. RFC822.TEXT A string expressing the text body of the message, omitting the RFC 822 header. UID A number expressing the unique identifier of the message. COPY OBSOLETE. New server implementations MUST NOT transmit this response. Client implementations SHOULD ignore this response and not report an error. STORE data OBSOLETE. Functionally equivalent to the FETCH response. New server implementations MUST NOT transmit this response. Client implementations SHOULD treat this response as equivalent to the FETCH response and not report an error. Crispin [Page 40] Internet Draft IMAP4 March 8, 1994 Command Continuation Ready Response + resp_text This response indicates that the server is ready to accept the text of a literal from the client. The text of this response is a line of human-readable text of the server's choosing (it is generally never seen by a client's human user). The purpose of this command is to solve a synchronization problem that can occur if a string in a command is a literal. This may occur when logging in (if the password contains "funny" characters), and always occurs when using the APPEND command, since a message consists of multiple lines. Normally, a command from the client is a single text line. If the server detects an error in the command, it can simply discard the remainder of the line. It cannot do this for commands that contain literals, since a literal can be an arbitrarily long amount of text, and the server may not even be expecting a literal. This mechanism is provided so the client knows not to send a literal until the server expects it, preserving client/server synchronization. No such synchronization protection is provided for literals sent from the server to the client. Any synchronization problems in this direction would be caused by a bug in the client or server. EXAMPLE: C: A001 LOGIN SMITH {7} S: + Ready for additional command text C: fat man S: A001 OK LOGIN completed Crispin [Page 41] Internet Draft IMAP4 March 8, 1994 Sample IMAP4 session The following is a transcript of an IMAP4 session. A long line in this sample is broken for editorial clarity. S: * OK IMAP4 Service Ready C: a001 login mrc secret S: a001 OK LOGIN completed C: a002 select inbox S: * 18 EXISTS S: * FLAGS (\Answered \Flagged \Deleted \Seen \Junked) S: * 2 RECENT S: * OK [UNSEEN 17] Message 17 is the first unseen message S: a002 OK [READ-WRITE] SELECT completed S: a003 fetch 12 full S: * 12 FETCH (FLAGS (\Seen) INTERNALDATE "14-Jul-1993 02:44:25 -0700" RFC822.SIZE 4282 ENVELOPE ("Wed, 14 Jul 1993 02:23:25 -0700 (PDT)" "IMAP4 WG mtg summary and minutes" (("Terry Gray" NIL "gray" "cac.washington.edu")) (("Terry Gray" NIL "gray" "cac.washington.edu")) (("Terry Gray" NIL "gray" "cac.washington.edu")) ((NIL NIL "imap" "cac.washington.edu")) ((NIL NIL "minutes" "CNRI.Reston.VA.US") ("John Klensin" NIL "KLENSIN" "INFOODS.MIT.EDU")) NIL NIL "") BODY ("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 3028 92)) S: a003 OK FETCH completed C: a004 fetch 12 rfc822.header S: * 12 FETCH (RFC822.HEADER {346} S: Date: Wed, 14 Jul 1993 02:23:25 -0700 (PDT) S: From: Terry Gray S: Subject: IMAP4 WG mtg summary and minutes S: To: imap@cac.washington.edu S: cc: minutes@CNRI.Reston.VA.US, John Klensin S: Message-Id: S: Mime-Version: 1.0 S: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII S: S: ) S: a004 OK FETCH completed C: a005 store 12 +flags \deleted S: * 12 FETCH (FLAGS (\Seen \Deleted)) S: a005 OK +FLAGS completed C: a006 logout S: * BYE IMAP4 server terminating connection S: a006 OK LOGOUT completed Crispin [Page 42] Internet Draft IMAP4 March 8, 1994 Design Discussion IMAP4 is a textual protocol. The use of MIME encoding in IMAP4 makes it possible to support 8-bit textual and binary mail. IMAP4 implementations MAY transmit 8-bit or multi-octet characters in literals, but should do so only when the character set is identified. For example, 8-bit characters are specifically permitted in MIME body parts (fetching BODY[section]) of type TEXT. 8-bit characters are also permitted in the argument to APPEND. Servers MUST NOT transmit 8-bit characters in RFC822.HEADER fetch results. Servers MUST NOT transmit 8-bit characters in RFC822.TEXT (and by extension RFC822) fetch results, unless there are MIME data in the message that identify the character sets of all 8-bit data. Because 8-bit characters are permitted in the argument to APPEND, a server that is unable to preserve 8-bit data properly MUST be able to reversibly convert 8-bit APPEND data to 7-bit using MIME. Although a BINARY body encoding is defined, IMAP4 does not permit unencoded binary strings. A "binary string" is any string with NUL characters; a string with an excessive amount of CTL characters may also be considered to be binary. The mixing of unencoded binary in the same stream as textual commands would make the protocol more vulnerable to synchronization problems. Implementations MUST encode binary data into BASE64 before transmitting it with IMAP4. When operating in the online model, an IMAP4 client should maintain a local cache of data from the mailbox. This cache is an incomplete model of the mailbox, and at startup is generally empty. As the client processes all untagged data, it updates the cache based on this data. When a tagged response arrives, the client's cache has been updated from the associated request. Note that a server can send data that the client did not request, such as mailbox size or flag updates. A server MUST send mailbox size updates automatically while processing a command. A server SHOULD send message flag updates automatically, without requiring the client to request such updates explicitly. Regardless of what implementation decisions a client may take on caching, a client MUST record EXISTS and RECENT updates and MUST NOT assume that a CHECK or NOOP command will return EXISTS or RECENT information. Although it is permitted for a server to send an unsolicited response (other than EXPUNGE) while there is no command in progress, this Crispin [Page 43] Internet Draft IMAP4 March 8, 1994 practice SHOULD NOT be followed because of flow control considerations. It can cause an incautious implementation to deadlock. A deadlock is avoided if either of the following conditions are true: (1) except for the greeting, the server never sends responses while there is no command in progress; (2) the server process is capable of reading commands while sending data. The latter condition generally requires either a multi-threading server implementation or use of a polling facility and non-blocking I/O. If a server has an inactivity autologout timer, that timer MUST be of at least 30 minutes' duration. The receipt of a NOOP command from the client during that interval should suffice to reset the autologout timer. Periodic transmission of a NOOP from the client during periods of inactivity also has the benefit of avoiding the possible deadlock noted above. It is frequently asked why there is no message posting function in IMAP4. Message posting is orthogonal to the scope of a mail access protocol and detracts from its primary focus. SMTP (RFC 821) provides the minimal functionality needed for message posting without losing valuable capabilities (such as blind carbon copies). Any message posting function in IMAP4 would need, at a minimum, to provide equivalent functionality. At the time of the writing of this document, an extensive set of extensions to SMTP (RFC 821) is in the Internet standards process. Should those extensions become an Internet Standard it would be necessary to revise IMAP4 again to provide corresponding capabilities, were a message posting facility to be included in IMAP4. In other words, a duplication of effort would be required each time a change is made to message transport technology. Another undesirable aspect of message posting in IMAP4 occurs when a remote server is used. It is unlikely that a client would support multiple means of posting a message. It adds excessive size and complexity that can not be afforded, particularly on smaller machines. It also can lead to poor performance. Consider a client connecting to an IMAP4 server over an interactive satellite link to a foreign country. A local message posting (SMTP (RFC 821)) server is available that uses a lower-cost batched link. Here, it would be wasteful to use the interactive link for posting. Message posting to IMAP4 has been suggested as a means of authenticating postings. The problem is that access authentication credentials are not necessarily the same as posting authentication credentials. At some sites, the disclosure of a portion of access authentication credentials in a mail message (as a "From" or "Sender" address) may be a serious security breach of greater significance Crispin [Page 44] Internet Draft IMAP4 March 8, 1994 than forged mail. The Internet message transport infrastructure has no concept of authentication credentials, and neither authentication syntax nor semantics are transferred within a message. As a result, any attempt at authenticating a message via posting authentication is completely ineffective once the message leaves the authenticating server; any indication of authentication in the message can easily be reproduced further down the line. Public-key based message authentication systems such as Privacy Enhanced Mail are now under development to address this problem. IMAP4 does not address problems with multiple IMAP4 servers at a single site, access control lists, and mobility of client configuration and address book information. These and other issues are being considered for a companion protocol. Crispin [Page 45] Internet Draft IMAP4 March 8, 1994 Formal Syntax The following syntax specification uses the augmented Backus-Naur Form (BNF) notation as specified in RFC 822 with one exception; the delimiter used with the "#" construct is a single space (SPACE) and not a comma. Except as noted otherwise, all alphabetic characters in the IMAP4 protocol are case-insensitive. For example, "LOGIN", "login" and "lOgIn" all refer to the same command, and \FLAGGED, \Flagged, and \FlAgGeD all refer to the same flag. The use of upper or lower case characters to define token strings is for editorial clarity only, although they may be construed as defining a suggested usage. Implementations MUST accept these strings in a case-insensitive fashion. Syntax marked as obsolete may be encountered with implementations written for an older version of this specification. New implementations SHOULD accept obsolete syntax as input, but MUST NOT otherwise use it. address ::= "(" addr_name SPACE addr_adl SPACE addr_mailbox SPACE addr_host ")" addr_adl ::= nstring addr_host ::= nstring ;; NIL indicates RFC 822 group syntax addr_mailbox ::= nstring ;; NIL indicates end of RFC 822 group; if non-NIL ;; and addr_host is NIL, holds RFC 822 group name addr_name ::= nstring append ::= "APPEND" SPACE mailbox [SPACE flag_list] [SPACE date_time] SPACE literal astring ::= atom / string ATCHAR ::= atom ::= 1*ATCHAR atom_specials ::= "(" / ")" / "{" / list_wildcards / quoted_specials body ::= "(" body_structure ")" Crispin [Page 46] Internet Draft IMAP4 March 8, 1994 body2 ::= "(" body2_structure ")" body2_extension ::= nstring / number / "(" 1#body2_extension ")" ;; Future expansion. Clients MUST accept body2 ;; extension fields. Servers MUST NOT generate ;; body2 extension fields. body2_md5 ::= nstring ;; MD5 checksum body2_multipart ::= 1*body2 SPACE body_subtype SPACE body_parameter [SPACE 1#body2_extension] body2_structure ::= body2_terminal / body2_multipart body2_terminal ::= body_terminal SPACE body2_md5 [SPACE 1#body2_extension] body_basic ::= body_type_basic SPACE body_subtype SPACE body_fields body_fields ::= body_parameter SPACE body_id SPACE body_desc SPACE body_encoding SPACE body_size body_desc ::= nstring body_encoding ::= <"> ("7BIT" / "8BIT" / "BINARY" / "BASE64"/ "QUOTED-PRINTABLE") <"> / string body_id ::= nstring body_msg ::= body_msg_822 / body_msg_other body_msg_822 ::= body_type_msg SPACE body_subtyp_822 SPACE body_fields SPACE envelope SPACE body SPACE body_size_lines body_msg_other ::= body_type_msg SPACE body_subtype SPACE body_fields ;; Subtype MUST NOT be "RFC822" body_multipart ::= 1*body SPACE body_subtype body_parameter ::= "(" 1#(string string) ")" / nil body_section ::= number / number "." body_section body_size ::= number ;; Size in octets body_size_lines ::= number Crispin [Page 47] Internet Draft IMAP4 March 8, 1994 body_structure ::= body_terminal / body_multipart body_subtype ::= string body_subtyp_822 ::= <"> "RFC822" <"> body_terminal ::= body_basic / body_msg / body_text body_text ::= body_type_text SPACE body_subtype SPACE body_fields SPACE body_size_lines body_type_basic ::= <"> ("APPLICATION" / "AUDIO" / "IMAGE" / "VIDEO") <"> / string body_type_msg ::= <"> "MESSAGE" <"> body_type_text ::= <"> "TEXT" <"> CHAR ::= CHAR8 ::= check ::= "CHECK" copy ::= "COPY" SPACE sequence SPACE mailbox CR ::= create ::= "CREATE" SPACE mailbox ;; Use of INBOX gives a NO error CRLF ::= CR LF CTL ::= date ::= date_text / <"> date_text <"> date_day ::= 1*2DIGIT ;; Day of month date_day_fixed ::= (SPACE 1DIGIT) / 2DIGIT ;; Fixed-format version of date_day date_month ::= "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" / "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec" date_text ::= date_day "-" date_month "-" (date_year / date_year_old) Crispin [Page 48] Internet Draft IMAP4 March 8, 1994 date_year ::= 4DIGIT date_year_old ::= 2DIGIT ;; OBSOLETE, (year - 1900) date_time ::= <"> (date_time_new / date_time_old) <"> date_time_new ::= date_day_fixed "-" date_month "-" date_year SPACE time SPACE zone date_time_old ::= date_day_fixed "-" date_month "-" date_year_old SPACE time "-" zone_old ;; OBSOLETE delete ::= "DELETE" SPACE mailbox_other DIGIT ::= digit_hex :: DIGIT / "a" / "b" / "c" / "d" / "e" / "f" envelope ::= "(" env_date SPACE env_subject SPACE env_from SPACE env_sender SPACE env_reply-to SPACE env_to SPACE env_cc SPACE env_bcc SPACE env_in-reply-to SPACE env_message-id ")" env_bcc ::= "(" 1*address ")" / nil env_cc ::= "(" 1*address ")" / nil env_date ::= nstring env_from ::= "(" 1*address ")" / nil env_in-reply-to ::= nstring env_message-id ::= nstring env_reply-to ::= "(" 1*address ")" / nil env_sender ::= "(" 1*address ")" / nil env_subject ::= nstring env_to ::= "(" 1*address ")" / nil examine ::= "EXAMINE" SPACE mailbox expunge ::= "EXPUNGE" Crispin [Page 49] Internet Draft IMAP4 March 8, 1994 extension ::= "X" 1*ATCHAR fetch ::= "FETCH" SPACE sequence SPACE ("ALL" / "FULL" / "FAST" / fetch_att / "(" 1#fetch_att ")") fetch_att ::= fetch_att_lines / fetch_att_other / fetch_att_text fetch_att_lines ::= "RFC822.HEADER.LINES" SPACE header_list / "RFC822.HEADER.LINES.NOT" SPACE header_list / fetch_att_other ::= "BODY" / "BODYSTRUCTURE" / "ENVELOPE" / "FLAGS" / "INTERNALDATE" / "RFC822.SIZE" / "UID" / extension fetch_att_text ::= "BODY[" body_section "]" / "BODY.PEEK[" body_section "]" / "RFC822" / "RFC822.PEEK" / "RFC822.HEADER" / "RFC822.TEXT" / "RFC822.TEXT.PEEK" find ::= "FIND MAILBOXES" SPACE list_mailbox ;; OBSOLETE find_all ::= "FIND ALL.MAILBOXES" SPACE list_mailbox ;; OBSOLETE flag_autocreate ::= "\*" flag_fetchable ::= "(" 0#(flag_storable / flag_recent) ")" flag_list ::= "(" flag_storable ")" flag_permanent ::= "(" 0#(flag_storable / flag_autocreate) ")" flag_recent ::= "\Recent" flag_storable ::= 1#(flag_system / flag_user) flag_system ::= "\Answered" / "\Flagged" / "\Deleted" / "\Seen" / "\Junked" / flag_sys_ext flag_sys_ext ::= "\" extension flag_user ::= atom greeting ::= "*" SPACE (resp_cond_auth / resp_cond_bye) CRLF header_line ::= astring header_list ::= "(" 1#header_line ")" Crispin [Page 50] Internet Draft IMAP4 March 8, 1994 inbox ::= "INBOX" ;; Case-independent, but SHOULD be upper-case kerberos_auth ::= 1*digit_hex kerberos_resp ::= 1*digit_hex LF ::= list ::= "LIST" SPACE mailbox_other SPACE list_mailbox list_mailbox ::= 1* / string list_wildcards ::= "%" / "?" / "*" literal ::= "{" number "}" CRLF 1*CHAR8 ;; The number represents the number of CHAR8 octets login ::= "LOGIN" SPACE userid SPACE password logout ::= "LOGOUT" lsub ::= "LSUB" SPACE mailbox_other SPACE list_mailbox mailbox ::= inbox / mailbox_other mailbox_other ::= astring ;; May not be INBOX. May be case-dependent ;; as a function of server implementation message_data ::= number SPACE (msg_exists / msg_recent / msg_expunge / msg_fetch / msg_obsolete) msg_copy ::= "COPY" ;; OBSOLETE msg_exists ::= "EXISTS" msg_expunge ::= "EXPUNGE" Crispin [Page 51] Internet Draft IMAP4 March 8, 1994 msg_fetch ::= "FETCH" SPACE "(" 1#("BODY" SPACE body / "BODYSTRUCTURE" SPACE body2 / "BODY[" body_section "]" nstring / "ENVELOPE" SPACE envelope / "FLAGS" SPACE flag_fetchable / "INTERNALDATE" SPACE date_time / "RFC822" SPACE nstring / "RFC822.HEADER" SPACE nstring / "RFC822.SIZE" SPACE number / "RFC822.TEXT" SPACE nstring / "UID" SPACE uniqueid) ")" msg_obsolete ::= msg_copy / msg_store ;; OBSOLETE untagged data responses msg_recent ::= "RECENT" msg_store ::= "STORE" SPACE "(" 1#("FLAGS" SPACE flag_fetchable ")" ;; OBSOLETE mstring ::= mstring_attr SPACE mstring_sep SPACE mailbox ;; Represents a mailbox mstring_attr ::= "(" 0#("\Noinferiors" / "\Noselect" / flag_sys_ext) ")" mstring_sep ::= <"> quoted_char <"> / nil nil ::= "NIL" nonmessage_data ::= "LIST" SPACE mstring / "LSUB" SPACE mstring / "SEARCH" [SPACE 1#number] / "FLAGS" SPACE flag_list / "MAILBOX" SPACE text_line noop ::= "NOOP" nstring ::= string / nil number ::= 1*DIGIT partial ::= "PARTIAL" SPACE number SPACE fetch_att_text SPACE number SPACE number password ::= astring / "@KERBEROS:" kerberos_auth QCHAR ::= quoted_char ::= QCHAR / "\" quoted_specials Crispin [Page 52] Internet Draft IMAP4 March 8, 1994 quoted_specials ::= <"> / "\" quoted_string ::= <"> *quoted_char <"> ready ::= "+" SPACE resp_text rename ::= "RENAME" SPACE mailbox SPACE mailbox_other request ::= tag SPACE (request_auth / request_authed / request_open) ;; Modal based on state request_any ::= noop / logout ;; Valid in all modes request_auth ::= request_any / login ;; Valid only when in not authenticated mode request_authed ::= request_any / create / delete / rename / list / lsub / subscribe / unsubscribe / select / examine / append / find / find_all / x_command ;; Valid only when in authenticated or mailbox open mode request_open ::= request_authed / check / expunge / copy / fetch / partial / store / uid / search / x_command ;; Valid only when in mailbox open mode response ::= * response_done response_data ::= "*" SPACE (resp_cond_state / resp_cond_bye / message_data / nonmessage_data) CRLF response_done ::= response_tagged / response_fatal response_fatal ::= "*" SPACE resp_cond_bye CRLF response_tagged ::= tag SPACE resp_cond_state CRLF resp_cond_auth ::= ("OK" / "PREAUTH") SPACE resp_text ;; Authentication condition resp_cond_bye ::= "BYE" SPACE resp_text ;; Server will disconnect condition resp_cond_state ::= ("OK" / "NO" / "BAD") SPACE resp_text ;; Status condition resp_text ::= [resp_token SPACE] text_line Crispin [Page 53] Internet Draft IMAP4 March 8, 1994 resp_token ::= "[" resp_token_type "]" resp_token_type ::= "PARSE" / "PERMANENTFLAGS" SPACE flag_permanent / "READ-ONLY" / "READ-WRITE" / "TRYCREATE" / "UNSEEN" SPACE number/ extension / kerberos_resp search ::= "SEARCH" SPACE [search_charset SPACE] search_criteria search_charset ::= "CHARSET" SPACE astring ;; Must be registered with IANA as a MIME character set search_criteria ::= 1#search_key search_key ::= search_new / search_old search_new ::= "HEADER" SPACE header_line SPACE astring / "JUNKED" / "LARGER" SPACE number / "NOT" SPACE search_key / "OR" SPACE search_key SPACE search_key / "SENTBEFORE" SPACE date / "SENTON" SPACE date / "SENTSINCE" SPACE date / "SMALLER" SPACE number / "UID" SPACE sequence / "UNJUNKED" / extension / sequence / "(" search_criteria ")" ;; New in IMAP4 search_old ::= "ALL" / "ANSWERED" / "BCC" SPACE astring / "BEFORE" SPACE date / "BODY" SPACE astring / "CC" SPACE astring / "DELETED" / "FLAGGED" / "FROM" space astring / "KEYWORD" SPACE flag_user / "NEW" / "OLD" / "ON" SPACE date / "RECENT" / "SEEN" / "SINCE" SPACE date / "SUBJECT" SPACE astring / "TEXT" SPACE astring / "TO" SPACE astring / "UNANSWERED" / "UNDELETED" / "UNFLAGGED" / "UNKEYWORD" SPACE flag_user / "UNSEEN" ;; Defined in RFC-1176 select ::= "SELECT" SPACE mailbox sequence ::= sequence_num / (sequence "," sequence) / (sequence_num ":" sequence_num) ;; Identifies a set of messages by consecutive numbers ;; from 1 to the number of messages in the mailbox. ;; Comma delimits individual numbers, colon delimits ;; between two numbers inclusive. ;; Example: 2,4:7,9,12:* is 2,4,5,6,7,9,12,13,14,15 for ;; a mailbox with 15 messages. Crispin [Page 54] Internet Draft IMAP4 March 8, 1994 sequence_num ::= number / "*" ;; * is the largest number in use. For message numbers, ;; it is the number of messages in the mailbox. For ;; unique identifiers, it is the unique identifier of ;; the message whose message number is the number of ;; message in the mailbox (that is, the last message). SPACE ::= store ::= "STORE" SPACE sequence SPACE store_att SPACE store_flags store_att ::= "+FLAGS" / "-FLAGS" / "FLAGS" store_flags ::= flag_list / flag_storable string ::= quoted_string / literal subscribe ::= "SUBSCRIBE" [SPACE "MAILBOX"] SPACE mailbox tag ::= 1*TCHAR TCHAR ::= TEXTCHAR ::= text_line ::= 1*TEXTCHAR time ::= 2DIGIT ":" 2DIGIT ":" 2DIGIT ;; Hours minutes seconds uid ::= "UID" SPACE (copy / fetch / search / store) ;; Uniqueids used instead of message numbers uniqueid ::= number ;; Strictly ascending unsubscribe ::= "UNSUBSCRIBE" [SPACE "MAILBOX"] SPACE mailbox userid ::= astring x_command ::= extension ;; Experimental extensions Crispin [Page 55] Internet Draft IMAP4 March 8, 1994 zone ::= ("+" / "-") 4DIGIT ;; Signed four-digit value of hhmm representing ;; hours and minutes west of Greenwich (that is, ;; (the amount that the given time differs from ;; Universal Time). Subtracting the timezone ;; from the given time will give the UT form. ;; The Universal Time zone is "+0000". zone_old ::= "UT" / "GMT" / "Z" / ;; +0000 "AST" / "EST" / "CST" / "MST" / ;; -0400 to -0700 "PST" / "YST" / "HST" / "BST" / ;; -0800 to -1100 "ADT" / "EDT" / "CDT" / "MDT" / ;; -0300 to -0600 "PDT" / "YDT" / "HDT" / "BDT" / ;; -0700 to -1000 "A" / "B" / "C" / "D" / "E" / "F" / ;; +0100 to +0600 "G" / "H" / "I" / "K" / "L" / "M" / ;; +0700 to +1200 "N" / "O" / "P" / "Q" / "R" / "S" / ;; -0100 to -0600 "T" / "U" / "V" / "W" / "X" / "Y" ;; -0700 to -1200 ;; OBSOLETE A protocol session is as follows: Server: greeting * Server: response > Crispin [Page 56] Internet Draft IMAP4 March 8, 1994 Compatibility Notes This is a summary of hints and recommendations to enable an IMAP4 implementation, written to this specification, to interoperate with implementations that conform to earlier specifications. None of these hints and recommendations are required by this specification; implementors must decide for themselves whether they want their implementation to fail if it encounters old software. IMAP4 has been designed to be upwards compatible with earlier specifications. For the most part, IMAP4 facilities that were not in earlier specifications should be invisible to clients unless the client asks for the facility. In some cases, older servers may support some of the capabilities listed as being "new in IMAP4" as experimental extensions to the IMAP2 protocol described in RFC 1176. This information may not be complete; it reflects current knowledge of server and client implementations as well as "folklore" acquired in the evolution of the protocol. IMAP4 client interoperability with old servers In general, a client should be able to discover whether a server supports a facility by trial-and-error; if an attempt to use a facility generates a BAD response, the client can assume that the server does not support the facility. Some servers may disable certain commands as a matter of intentional site policy. Such servers should return a NO response to disabled commands instead of a BAD response. A quick way to check whether a server implementation supports this specification is to try a UID FETCH 0 UID command. An OK or NO response would indicate a server that conforms to this specification; a BAD response would indicate an older server. Known problems are noted below: The CREATE, DELETE, and RENAME commands are new in IMAP4, and may not be present in old servers. A safe mechanism to test whether these commands are present is to try a CREATE INBOX command. If the response is NO, these commands are supported by the server. If the response is BAD, they are not. If the response is OK, the server's implementation is broken, since creating INBOX is not permitted. Crispin [Page 57] Internet Draft IMAP4 March 8, 1994 The FIND MAILBOXES and FIND ALL.MAILBOXES commands of RFC 1176 have been replaced with the new LSUB and LIST commands. If the response to an LSUB or LIST command is BAD, a client may wish to attempt an FIND MAILBOXES or FIND ALL.MAILBOXES command before deciding that it is not possible to list mailboxes on the remote system. The FIND BBOARDS, FIND ALL.BBOARDS, and BBOARD commands of RFC 1176 are removed from IMAP4. There is no equivalent to the bboard commands, which provided a separate namespace with implicit restrictions on what may be done in that namespace. The LSUB and LIST commands are new in IMAP4. A BAD response to these commands indicates a server that does not support mailbox listing. Note that the definition of the LSUB and LIST commands differ significantly from the FIND command of RFC 1176. The SUBSCRIBE and UNSUBSCRIBE commands are new in IMAP4. A server that supports LSUB will also support the SUBSCRIBE and UNSUBSCRIBE commands. The experimental IMAP2bis version had SUBSCRIBE and UNSUBSCRIBE commands with a different syntax, but did not support the LSUB command. The EXAMINE command is new in IMAP4. A BAD response to this command indicates a server that does not support an explicit read-only mode of access, and a SELECT command should be used instead. Older server implementations may automatically create the destination mailbox on COPY if that mailbox does not already exist. This was how a new mailbox was created in older specifications. If the server does not support the CREATE command (see above for how to test for this), it will probably create a mailbox on COPY. The APPEND command is new in IMAP4. A way to see if this command is implemented is to try to append a zero-length stream to a mailbox name that is known not to exist (or at least, highly unlikely to exist) on the remote system. Although IMAP4 clients SHOULD avoid asking for the same data more than once (by having a client-based cache of data returned by the server), this is not a requirement of the protocol. However, IMAP4 clients MUST cache data from the EXISTS and RECENT unsolicited responses. Only the SELECT command is guaranteed to return EXISTS/RECENT information. Crispin [Page 58] Internet Draft IMAP4 March 8, 1994 The use of * in a sequence to indicate the largest number in use is new in IMAP4. A BAD response to an attempt to fetch data using * as a sequence number indicates a server that does not support this capability. With message number sequences, the same effect can be obtained by using the number of messages in the mailbox from the EXISTS unsolicited response. The BODY, BODY[section], and FULL fetch data items are new in IMAP4. A BAD response to an attempt to fetch these data items indicates a server that does not support server-based MIME parsing. The BODYSTRUCTURE fetch data item is new in IMAP4. A BAD response to an attempt to fetch this data item indicates a server that does not support extensible results from server- based MIME parsing. Servers running the experimental IMAP2bis version may support the older, non-extensible, BODY fetch data item. A client should attempt this data item before deciding that the server does not support MIME. The use of nested part 0 of a part of type MESSAGE in a BODY or BODYSTRUCTURE fetch to get only the RFC 822 header of the message is new, and is not in the experimental IMAP2bis version. A server that returns NIL probably supports IMAP2bis; with such servers the only way to obtain the RFC 822 header is to fetch the entire nested message. The RFC822.HEADER.LINES and RFC822.HEADER.LINES.NOT fetch data items are new in IMAP4. A BAD response to an attempt to fetch this data item indicates a server that does not support selective header fetching. A client should use RFC822.HEADER and remove the unwanted information. The BODY.PEEK[section], RFC822.PEEK, and RFC822.TEXT.PEEK fetch data items are new in IMAP4. A BAD response to an attempt to fetch one of these data items indicates a server that does not support fetching of message data without implicitly setting the \Seen flag. A client should use the corresponding non-PEEK versions and manually clear the \Seen flag as necessary. The UID fetch data item and the UID commands are new in IMAP4. A BAD response to an attempt to use these indicates a server that does not support unique identifiers. The PARTIAL command is new in IMAP4. If this command causes a BAD response, then the client should use the appropriate FETCH command and ignore the unwanted data. Crispin [Page 59] Internet Draft IMAP4 March 8, 1994 The SEARCH command has been extended in several ways in IMAP4, including the addition of a character set specifier for international searching. A BAD response to a SEARCH command which attempts to use any search capability other than those listed in search_old in the grammar indicates a server that does not support any of the new SEARCH capabilities. A client should reformulate its search request using only the searching options listed in search_old. This may entail doing multiple searches to achieve the desired results. IMAP4 client implementations must accept all responses and data formats documented in this specification, including those labeled as obsolete. This includes the COPY and STORE unsolicited responses and the old format of dates and times. The experimental IMAP2bis version did not provide a way to set flags or internal date on APPEND. Client implementations which receive a BAD response to an APPEND command with flag list and/or internal date should retry the command without any flag list and internal date arguments. Older server implementations may not preserve flags or internal dates on COPY. Some server implementations may not permit the preservation of certain flags on COPY or their setting with APPEND as site policy. The experimental IMAP2bis version specified that the TRYCREATE special information token is sent as a separate unsolicited OK response instead of inside the NO response. IMAP4 server interoperability with old clients In general, there should be no interoperation problem between a server conforming to this specification and a well-written client that conforms to an earlier specification. Known problems are noted below: Clients written to use undocumented private server extensions that are not in any published specification may work poorly with server implementations that do not have those extensions. Poor wording in the description of the CHECK command in earlier specifications implied that a CHECK command is the way to get the current number of messages in the mailbox. This is incorrect. A CHECK command does not necessarily result in an EXISTS response. Clients must remember the most recent EXISTS value sent from the server, and should not generate unnecessary Crispin [Page 60] Internet Draft IMAP4 March 8, 1994 CHECK commands. An incompatibility exists with COPY in IMAP4. COPY in IMAP4 servers does not automatically create the destination mailbox if that mailbox does not already exist. This may cause problems with old clients that expect automatic mailbox creation in COPY. The PREAUTH unsolicited response is new in IMAP4. It is highly unlikely that an old client would ever see this response. The COPY unsolicited response is obsolete. Clients should ignore this response without reporting an error. The STORE unsolicited response is obsolete. Clients should treat this response as identical to a FETCH response. The format of dates and times has changed due to the impending end of the century. Clients must accept a four-digit year instead of a two-digit year, and a signed four-digit timezone value instead of a timezone name. In particular, client implementations must not treat a date/time as a fixed format string; nor may they assume that the time begins at a particular octet. An incompatibility exists with the use of "\" in quoted strings. This is best avoided by using literals instead of quoted strings if "\" or <"> is embedded in the string. Crispin [Page 61] Internet Draft IMAP4 March 8, 1994 Acknowledgements Bill Yeager and Rich Acuff contributed invaluable suggestions in the evolution of IMAP2 from the original IMAP. James Rice pointed out several ambiguities in the previous IMAP2 specification. My colleagues on the Pine team -- Steve Hubert, Laurence Lundblade, David Miller, and Mike Seibel -- worked long and hard to create a fantastic email user agent with worldwide popularity. Without their efforts, IMAP2 would have languished in obscurity. Terry Gray, our boss, provided much-needed moral support and guidance, while refusing to let us get away with "good enough" when "great" was possible. John G. Myers and Chris Newman carefully examined the formal grammar and identified numerous mistakes and omissions in the drafts of this specification. Rob Austein contributed important information on the workings of disconnected access. They also provided invaluable input towards the overall architecture of the present protocol, and endured long meetings to reach the present protocol. The present protocol would not have come into existence without the assistance of the rest of the IETF IMAP2 working group, in particular Ned Freed and Adam Treister. Any mistakes, flaws, or sins of omission in this IMAP4 protocol specification are, however, strictly my own; and the mention of any name above does not imply an endorsement. Security Considerations Security issues are discussed in this memo only as far as authentication to access a server are concerned. Author's Address Mark R. Crispin Networks and Distributed Computing, JE-30 University of Washington Seattle, WA 98195 Phone: (206) 543-5762 EMail: MRC@CAC.Washington.EDU Crispin [Page 62]