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