The server must respond with a solicited STORE FLAGS
message, showing the new state of the flags after
the store.
-FLAGS Remove the flags in the argument from the
message's flag list.
The server must respond with a solicited STORE FLAGS
message, showing the new state of the flags after
the store.
RFC822.HEADER Replace the header of the message(s) with that
specified. This allows users to use their mailboxes
as databases with header fields as keys.
The server must respond with solicited
STORE RFC822.HEADER, STORE RFC822.SIZE and
STORE ENVELOPE messages, showing the new state
of the reparsed header after the store.
RFC822.TEXT Replace the body of the messages with that specified.
The server must respond with solicited
STORE RFC822.TEXT and STORE RFC822.SIZE messages,
showing the new state of the message after the store.
STORE is not allowed if the user does not have write access to
this mailbox.
The server is required to send a solicited STORE response for
each store operation that results in a format transformation by
the server. For example, the server is required to send a
STORE FLAGS response when the client performs a STORE +FLAGS or
a STORE -FLAGS, since the client may not easily be able to know
what the result of this command will be. Similarly, if the
client emits a STORE FROM command then the server should
respond with a suitable STORE FROM response because the client
would be sending a string value to be stored and the server
should transform this into a set of addresses. In general,
however, although it is legal for the server to send a
solicited STORE response for each STORE operation, this is
discouraged, since it might result in the retransmission of
very large and unnecessary amounts of data that have been
stored.
EXAMPLE: A003 STORE 2:4 +FLAGS (\DELETED) marks messages 2, 3,
and 4 for deletion.
tag SEARCH search_criteria
The SEARCH command searches the mailbox for messages which match
the given set of criteria. The server response SEARCH (criteria)
(numbers) gives the set of messages which match the conjunction of
the criteria specified. In addition to each of the search
criteria there is its logical inverse. The logical inverse
criterion is denoted by the ~ (tilda) sign.
Thus, no message that matches the criterion:
FROM crispin
will match the criterion:
~FROM crispin
The criteria for the search can be any generic, canonical or
concrete key. In addition to these, the following pre-defined
keys are also provided:
ALL All messages in the mailbox; the default
initial criterion for ANDing.
ANSWERED Messages with the \ANSWERED flag set.
BCC string Messages which contain the specified string
in the envelope's BCC field.
BEFORE date Messages whose internal date is earlier than
the specified date.
BODY string Messages which contain the specified string
in the body of the message.
CC string Messages which contain the specified string
in the envelope's CC field.
DELETED Messages with the \DELETED flag set.
FLAGGED Messages with the \FLAGGED flag set.
FROM string Messages which contain the specified string
in the envelope's FROM field.
HEADER string Messages which contain the specified string
in the message header.
KEYWORD flag Messages with the specified flag set.
NEW Messages which have the \RECENT flag set but
not the \SEEN flag. This is functionally
equivalent to "RECENT UNSEEN".
OLD Messages which do not have the \RECENT flag
set.
ON date Messages whose internal date is the same as
the specified date.
RECENT Messages which have the \RECENT flag set.
SEEN Messages which have the \SEEN flag set.
SINCE date Messages whose internal date is later than
the specified date.
SUBJECT string Messages which contain the specified string
in the envelope's SUBJECT field.
TEXT string Messages which contain the specified string.
TO string Messages which contain the specified string in
the envelope's TO field.
EXAMPLE: A003 SEARCH DELETED FROM "SMITH" SINCE 1-OCT-87
returns the message numbers for all deleted messages from Smith
that were placed in the mailbox since October 1, 1987.
Implementation note: The UNANSWERED, UNDELETED, UNFLAGGED,
UNKEYWORD and UNSEEN criteria, described below, are preserved in
IMAP3 for IMAP2 compatibility. They are, however, considered
obsolete and new Client programs are encouraged to use the ~
notation for the logical inverses of search criteria with a view
to the dropping of this outmoded syntax in later versions.
UNANSWERED Messages which do not have the \ANSWERED flag
set.
UNDELETED Messages which do not have the \DELETED flag
set.
UNFLAGGED Messages which do not have the \FLAGGED flag
set.
UNKEYWORD flag Messages which do not have the specified flag
set.
UNSEEN Messages which do not have the \SEEN flag set.
tag READONLY
The READONLY command indicates that the client wishes to make the
mailbox read-only. The server is required to reply with a
solicited READONLY or READWRITE response.
tag READWRITE
The READWRITE command indicates that the client wishes to make the
mailbox read-write. The server is required to reply with a
solicited READONLY or READWRITE response.
tag SUPPORTED.VERSIONS
The SUPPORTED.VERSIONS solicits from the server a
SUPPORTED.VERSIONS message, which encapsulates information about
which versions and features the server supports.
tag SELECT.VERSION (major_version minor_version)
The SELECT.VERSION command indicates that the client wishes to
select certain behavior on the part of the server. The major and
minor versions indicate the specific version of the protocol being
selected.
EXAMPLE: A002 SELECT.VERSION (3 0)
A client may not request a server version that is not supported by
the server, i.e., which is specifically mentioned in the response
to a SUPPORTED.VERSIONS command. An attempt to do so by a client
will result in a NO response from the server. It is an error for
the SELECT.VERSION command to be used after a mailbox has been
selected. The rationale for this is that for some server
implementations it might be necessary to spawn separate programs
to implement widely divergent protocol versions. Thus, the client
cannot be allowed to expect any server state to be preserved after
the use of the SELECT.VERSION command. The default version of all
servers is 2.0, i.e., IMAP2 as defined by RFC1064.
tag SELECT.FEATURES 1#features
The SELECT.FEATURES command indicates that the client wishes to
select certain specific features on the part of the server. A
client may not request a feature that is not supported by the
server, i.e., one that is explicitly mentioned in the set of
features for the selected version returned by the
SUPPORTED.VERSIONS command. An attempt to do so by a client will
result in a NO response from the server.
EXAMPLE: A002 SELECT.FEATURES AUTO.SET.SEEN ~TAGGED.SOLICITED
EIGHT.BIT.TRANSPARENT
i.e., select the set of features called AUTO.SET.SEEN and
EIGHT.BIT.TRANSPARENT and deselect the feature called
TAGGED.SOLICITED. The use of the SELECT.FEATURES command
completely resets the set of selected features. Note: These are
only example feature names and are not necessarily supported by
any server. See the appendix on features for more information on
features. Note: Some features, when present in the server, will
cause the upwards compatible extension of the grammar, i.e., by
adding extra commands. The server is at liberty not to remove
these upwards compatible extensions to the command tables when a
feature is disabled. Thus, it is an error for a client to rely on
getting a NO or BAD response in any way, for instance to determine
the selectedness or presence of a feature.
tag BBOARD bboard
The BBOARD command is equivalent to SELECT, except that its
argument is a bulletin board (BBoard) name. The format of a
BBoard name is implementation specific, although it is strongly
encouraged to use something that resembles a name in a generic
sense and not a file or mailbox name on the particular system.
There is no requirement that a BBoard name be a mailbox name or a
file name (in particular, Unix netnews has a completely different
namespace from mailbox or file names).
The result from the BBOARD command is identical from that of the
SELECT command. For example, in the TOPS-20 server
implementation, the command
A0002 BBOARD FOO
is exactly equivalent to the command
A0002 SELECT POBOX:<BBOARD>FOO.TXT
Note: the equivalence in this example is *not* required by the
protocol, and merely reflects the fuzzy distinction between
mailboxes and BBoards on TOPS-20.
tag FIND (BBOARDS / MAILBOXES) pattern
The FIND command accepts as arguments the keywords BBOARDS or
MAILBOXES and a pattern which specifies some set of BBoard/mailbox
names which are usable by the BBOARD/SELECT command. Two wildcard
characters are defined; "*" specifies that any number (including
zero) characters may match at this position and "%" specifies that
a single character may match at this position. For example,
FOO*BAR will match FOOBAR, FOOD.ON.THE.BAR and FOO.BAR, whereas
FOO%BAR will match only FOO.BAR; furthermore, "*" will match all
BBoards/mailboxes. The following quoting convention applies to
wildcards: "\*" is the literal "*" character, "\%" is the literal
"%" character and "\\" is the literal "\" character. Notes: The
format of mailboxes is server implementation dependent. The
special mailbox name INBOX is not included in the output to the
FIND MAILBOXES command.
The FIND command solicits any number of BBOARD or MAILBOX
responses from the server as appropriate.
Examples:
A0002 FIND BBOARDS *
A0002 BBOARD FOOBAR
A0002 BBOARD GENERAL
A0002 OK FIND completed
or
A0002 FIND MAILBOXES FOO%BA*
A0002 MAILBOX FOO.BAR
A0002 MAILBOX FOO.BAZZAR
A0002 OK FIND completed
Note: Although the use of explicit file or path names for
mailboxes is discouraged by this standard, it may be unavoidable.
It is important that the value returned in the MAILBOX solicited
reply be usable in the SELECT command without remembering any path
specification which may have been used in the FIND MAILBOXES
pattern.
tag FLAGS
The FLAGS command solicits a FLAGS response from the server.
tag SET.FLAGS flag_list
The SET.FLAGS command defines the user specifiable flags for this
mailbox, i.e., the keywords. If this set does not include flags
formerly sent to the client by the server in a FLAGS message then
this constitutes a request to delete the flag. Any new flags
should be created. This command does not affect the system
defined flags and any system flags that are included in the
flag_list will be ignored. The server must respond to this
command with a solicited FLAGS message. If the deletion of a flag
results in the invalidation of the flag sets of any messages then
the server is required to send solicited STORE FLAGS messages to
the client for each modified message.
Responses:
*/tag OK text
In its solicited form this response identifies successful
completion of the command with the indicated tag. The text is a
line of human-readable text which may be useful in a protocol
telemetry log for debugging purposes.
In its unsolicited form, this response indicates simply that the
server is alive. No special action on the part of the client is
called for. This is presently only used by servers at startup as
a greeting message indicating that they are ready to accept the
first command. This usage, although legal, is by no means
required. The text is a line of human-readable text which may be
logged in protocol telemetry.
*/tag NO text
In its solicited form this response identifies unsuccessful
completion of the command with the indicated tag. The text is a
line of human-readable text which probably should be displayed to
the user in an error report by the client.
In its unsolicited form this response indicates some operational
error at the server which cannot be traced to any protocol
command. The text is a line of human-readable text which should
be logged in protocol telemetry for the maintainer of the server
and/or the client.
*/tag BAD text
In its solicited form response indicates faulty protocol received
from the client and indicates a bug. The text is a line of
human-readable text which should be recorded in any telemetry as
part of a bug report to the maintainer of the client.
In its unsolicited form response indicates some protocol error at
the server which cannot be traced to any protocol command. The
text is a line of human-readable text which should be logged in
protocol telemetry for the maintainer of the server and/or the
client. This generally indicates a protocol synchronization
problem, and examination of the protocol telemetry is advised to
determine the cause of the problem.
*/tag BYE text
This indicates that the server is about to close the connection.
The text is a line of human-readable text which should be
displayed to the user in a status report by the client. IMAP2
requires that the server emit a solicited BYE response as part of
a normal logout sequence. This solicited form is not required
under IMAP3, though is still legal for compatibility. In its
unsolicited form the BYE response is used as a panic shutdown
announcement by the server. It is required to be used by any
server which performs autologouts due to inactivity.
*/tag number message_data
The solicited (tag number message_data) response is generated as
the result of a number of client requests. The server may also
emit any the following at any time as unsolicited data (i.e., *
number message_data). The message_data is one of the following:
EXISTS The specified number of messages exists in the mailbox.
RECENT The specified number of messages have arrived since the
last time this mailbox was selected with the SELECT
command or equivalent.
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 server must send a solicited EXPUNGE response
for each message that it expunges as the result
of an EXPUNGE command. Note: future versions of the
protocol may allow the use of a message sequence
as a value returned by the EXPUNGE response to allow the
more efficient compaction of client representations of
mailboxes.
STORE data
Functionally equivalent to FETCH, only it is sent by the
server when the state of a mailbox changes. The server
must send solicited STORE responses as the result of
any change caused by a STORE command.
FETCH data
This is the principle means by which data about a
message is sent to the client. The data is in a
Lisp-like S-expression property list form. Just as the
FETCH request from the client can fetch any generic,
canonical or concrete key, so also the FETCH response
can return values for any of these keys as well as for
the pre-defined attributes mentioned below. Note that
the server is permitted to send any unsolicited FETCH
or STORE messages that it should choose, be they the
values associated with generic, canonical or concrete
keys. Clients are required to ignore any such
FETCH responses that it cannot interpret. For example,
clients are not required to be able to understand, i.e.,
use fruitfully, the canonical $TO key, but they are
required to be able to ignore an unsolicited $TO message
correctly.
ENVELOPE An S-expression format list which describes the
envelope of a message. The envelope is computed
by the server by parsing the RFC822 header into
the component parts, defaulting various fields
as necessary.
The fields of the envelope are in the following
order: date, subject, from, sender, reply-to, to,
cc, bcc, in-reply-to, and message-id. 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 addresses.
An address is an S-expression format list which
describes an electronic mail address. The fields
of an address are in the following order:
personal name, source-route (i.e., the
at-domain-list in SMTP), mailbox name, host name
and comments. Implementation note: The addition
of the comment field is an incompatible extension
from IMAP2. The server is required not to provide
this field when running in IMAP2 mode.
Any field of an envelope or address which is
not applicable is presented as the atom 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 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 A string containing the date and time the
message was written to the mailbox.
RFC822 A string expressing the message in RFC822
format.
Note: Some implementations of IMAP2 servers
had the (undocumented) behavior of setting
the \SEEN flag as a side effect of fetching
the body of a message. This resulted in
erroneous behavior for clients that prefetch
messages that the user might not get
around to reading. Thus, this behavior is
explicitly disallowed in IMAP3.
Note: this is not a significant performance
restriction because it is always possible for
IMAP3 clients to use an interaction with the
server of the following type:
A001 FETCH 42 RFC822
A002 STORE 42 +FLAGS (\SEEN)
A001 42 FETCH RFC822 {637} ......
A001 OK Fetch completed
A002 42 STORE FLAGS (\SEEN \FLAGGED...)
A002 OK Store Completed.
RFC822.HEADER A string expressing the RFC822 format
header of the message
RFC822.SIZE A number indicating the number of
characters in the message as expressed
in RFC822 format.
RFC822.TEXT A string expressing the text body of the
message, omitting the RFC822 header.
See also note for RFC822.
*/tag FLAGS flag_list
A solicited FLAGS response must occur as a result of a SELECT
command. The flag list is the list of flags (at a minimum, the
IMAP defined flags) which are applicable for this mailbox. Flags
other than the system flags are a function of the server
implementation.
*/tag SEARCH (numbers) (search_criteria)
This response occurs as a result of a SEARCH command. The
number(s) refer to those messages which match the search criteria.
In its solicited form this message allows clients to find
interesting groups of messages, e.g., unseen messages from
Crispin. In its unsolicited form it allows the server to inform
the client of interesting patterns, e.g., when new mail arrives,
recent and from Crispin. Compatibility note: The search_criteria
are sent by the server along with the matching numbers so
unsolicited SEARCH messages may be interpreted. This syntax is
not upwards compatible with IMAP2 and so the new syntax is
intended to make it simple for clients that are not able to take
advantage of unsolicited SEARCH messages still to interpret
solicited SEARCH messages simply by ignoring everything that
follows the list of numbers with minimal parsing. Such clients
may not, however, simply discard the rest of the line because
there might be LITERALs in the search pattern.
Examples:
A00042 SEARCH (2 3 6) (FROM Crispin ~SEEN)
and
* SEARCH (42) (FROM Crispin RECENT)
*/tag READONLY
This indicates that the mailbox is read-only. The server is
required to respond to a READONLY or READWRITE command with either
a solicited READONLY or a solicited READWRITE response. Note: If
the client attempts a mutation operation, such as STORE, on a
mailbox to which it does not have write access then the server is
required to reply with a solicited READONLY response on the first
such attempted mutation. The server may also choose to send
solicited READONLY responses for each subsequent attempted
mutation.
*/tag READWRITE
This indicates that the mailbox is read-write. The server is
required to respond to a READONLY or READWRITE command with either
a solicited READONLY or a solicited READWRITE response.
*/tag BBOARD bboard_name
This message is produced in its solicited form as a response to a
FIND BBOARDS command. In its unsolicited form it represents a
notification by the server that a new BBoard has been added.
Bboard_name must be a name that can be supplied to the BBOARD
command so as to select the appropriate bboard.
*/tag MAILBOX non_inbox_mailbox_name
This message is produced in its solicited form as a response to a
FIND MAILBOXES command. In its unsolicited form it represents a
notification by the server that a new mailbox has been added,
perhaps as the result of a COPY command creating a new mailbox.
Non_inbox_mailbox_name must be a name that can be supplied to the
SELECT command so as to select the appropriate mailbox. Note:
non_inbox_mailbox_name is never the string "INBOX".
*/tag SUPPORTED.VERSIONS (version_specs)
This message is used either as a response to the
SUPPORTED.VERSIONS or, in its unsolicited form, to indicate the
dynamic addition or removal of support for features or protocol
versions. Each version_spec is of the form (4 2
EIGHT.BIT.TRANSPARENT AUTO.SET.SEEN ...), i.e., a major version
number and a minor version number for the protocol and the set of
features supported under the server's implementation of that
protocol version. A server may not dynamically remove support for
any version or feature that has been selected by any currently
logged in client by the use of the VERSION command.
Example:
A00005 SUPPORTED.VERSIONS ((2 0 )
(2 2 TAGGED.SOLICITED)
(3 0 EIGHT.BIT.TRANSPARENT TAGGED.SOLICITED))
Indicates that two major versions are supported and one minor
version is supported and that tagged solicited messages are
supported in versions 2.2 and 3.0 with eight bit characters being
supported under version 3. For each feature mentioned in the list
of features there is also always the negation of that feature.
For example, if the server supports the TAGGED.SOLICITED feature
then it also supports the ~TAGGED.SOLICITED feature, which
disables this feature. Note: These are only example feature
names and are not necessarily supported by any server. See the
appendix on features for more information on features.
+ text
This response indicates that the server is ready to accept the
text of a literal from the client. 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 in the case of commands which 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 definitely expects it, preserving client/server
synchronization.
In actual practice, this situation is rarely encountered. In the
current protocol, the only client commands likely to contain
literals are the LOGIN command and the STORE RFC822.HEADER or
STORE RFC822.TEXT commands. Consider a situation in which a
server validates the user before checking the password. If the
password contains "funny" characters and hence is sent as a
literal, then if the user is invalid an error would occur before
the password is parsed.
No such synchronization protection is provided for literals sent
from the server to the client, for performance reasons. Any
synchronization problems in this direction would be due to a bug
in the client or server and not for some operational problem.
Sample IMAP3 session
The following is a transcript of an actual IMAP3 session. Server
output is identified by "S:" and client output by "U:". In cases
where lines were too long to fit within the boundaries of this
document, the line was continued on the next line preceded by a tab.
S: * OK SUMEX-AIM.Stanford.EDU Interactive Mail Access Protocol
III Service 6.1(349) at Mon, 14 May 90 14:58:30 PDT
U: a001 SUPPORTED.VERSIONS
S: * SUPPORTED.VERSIONS ((2 0 ) (3 0 EIGHT.BIT.TRANSPARENT
AUTO.SET.SEEN TAGGED.SOLICITED))
S: A001 Supported Versions returned.
U: a002 SELECT.VERSION (3 0)
S: a002 OK Version 3.0 Selected.
U: a003 SELECT.FEATURES TAGGED.SOLICITED
S: a003 OK Features selected.
U: a004 login crispin secret
S: a004 OK User CRISPIN logged in at Thu, 9 Jun 90 14:58:42 PDT,
job 76
U: a005 select inbox
S: a005 FLAGS (Bugs SF Party Skating Meeting Flames Request AI
Question Note \XXXX \YYYY \Answered \Flagged \Deleted
\Seen)
S: a005 16 EXISTS
S: a005 0 RECENT
S: a006 OK Select complete
U: a006 fetch 16 all
S: a006 16 Fetch (Flags (\Seen) InternalDate " 9-Jun-88 12:55:
RFC822.Size 637 Envelope ("Sat, 4 Jun 88 13:27:11 PDT"
"INFO-MAC Mail Message" (("Larry Fagan" NIL "FAGAN"
"SUMEX-AIM.Stanford.EDU" NIL)) (("Larry Fagan" NIL "FAGAN"
"SUMEX-AIM.Stanford.EDU" NIL)) (("Larry Fagan" NIL "FAGAN"
"SUMEX-AIM.Stanford.EDU" NIL)) ((NIL NIL "rindflEISCH"
"SUMEX-AIM.Stanford.EDU" NIL)) NIL NIL NIL
"<12403828905.13.FAGAN@SUMEX-AIM.Stanford.EDU>"))
S: a006 OK Fetch completed
U: a007 fetch 16 rfc822
S: a007 16 Fetch (RFC822 {637}
S: Mail-From: RINDFLEISCH created at 9-Jun-88 12:55:43
S: Mail-From: FAGAN created at 4-Jun-88 13:27:12
S: Date: Sat, 4 Jun 88 13:27:11 PDT
S: From: Larry Fagan <FAGAN@SUMEX-AIM.Stanford.EDU>
S: To: rindflEISCH@SUMEX-AIM.Stanford.EDU
S: Subject: INFO-MAC Mail Message
S: Message-ID: <12403828905.13.FAGAN@SUMEX-AIM.Stanford.EDU>
S: ReSent-Date: Thu, 9 Jun 88 12:55:43 PDT
S: ReSent-From: TC Rindfleisch <Rindfleisch@SUMEX-AIM.Stanford.EDU>
S: ReSent-To: Yeager@SUMEX-AIM.Stanford.EDU,
Crispin@SUMEX-AIM.Stanford.EDU
S: ReSent-Message-ID:
<12405133897.80.RINDFLEISCH@SUMEX-AIM.Stanford.EDU>
S:
S: The file is <info-mac>usenetv4-55.arc ...
S: Larry
S: -------
S: )
S: a007 OK Fetch completed
U: a008 logout
S: a008 BYE UNIX IMAP III server terminating connection
S: a008 OK SUMEX-AIM.Stanford.EDU Interim Mail Access Protocol
Service logout
Implementation Discussion
As of this writing, SUMEX has completed an IMAP2 client for Xerox
Lisp machines written in hybrid Interlisp/CommonLisp and is beginning
distribution of a client for TI Explorer Lisp machines. SUMEX has
also completed a portable IMAP2 client protocol library module
written in C. This library, with the addition of a small main
program (primarily user interface) and a TCP/IP driver, became a
rudimentary remote system mail-reading program under Unix. The first
production use of this library is as a part of a MacII client which
has now been under daily use (by real users) at Stanford for quite
some time.
As of this writing, SUMEX has completed IMAP2 servers for TOPS-20
written in DEC-20 assembly language and 4.2/3 BSD Unix written in C.
The TOPS-20 server is fully compatible with MM-20, the standard
TOPS-20 mailsystem, and requires no special action or setup on the
part of the user. The INBOX under TOPS-20 is the user's MAIL.TXT.
The TOPS-20 server also supports multiple simultaneous access to the
same mailbox, including simultaneous access between the IMAP3 server
and MM-20. The 4.2/3 BSD Unix server requires that the user use
either Unix Mail format or mail.txt format which is compatible with
SRI MM-32 or Columbia MM-C. The 4.2/3 BSD Unix server allows
simultaneous read access; write access must be exclusive. There is
also an experimental IMAP3 server running on the TI Explorer class of
machine, which uses MM mailbox format and which can communicate over
both TCP and Chaos.
The Xerox Lisp client and DEC-20 server have been in production use
for over two years; the Unix server was been in production use for
over a year. IMAP3 has been used to access mailboxes at remote sites
from a local workstation via the Internet. For example, from the
Stanford local network one of the authors has read his mailbox at a
Milnet site.
A number of IMAP clients have now been developed or are being
developed. Amongst these are versions that run on the following
machines:
. Xerox Lisp machines
. Apple Macintosh
. NeXT
. IBM PC
. TI Explorer Lisp machines
. "Glass teletype" version that runs under Unix
. GNU Emacs
. X Windows
. NTT ELIS
Each of these client programs is carefully tuned to optimize the
performance and user interface in a manner that is consistent with
the the user interface model of the native machine. For example, the
Macintosh client features a "messy-desk" interface that allows the
cutting and pasting of text with the use of the clipboard with a menu
driven interface with keyboard accelerators.
This specification does not make any formal definition of size
restrictions, but some of the existing servers have the following
limitations:
DEC-20
. length of a mailbox: 7,077,888 characters
. maximum number of messages: 18,432 messages
. length of a command line: 10,000 characters
. length of the local host name: 64 characters
. length of a "short" argument: 39 characters
. length of a "long" argument: 491,520 characters
. maximum amount of data output in a single fetch:
655,360 characters
TI-Explorer
. length of a mailbox: limited by the Minimum of the size of the
virtual address space and the size of the file system
. maximum number of messages: limited by the the size of the
virtual address space
. length of a command line: limited by the the size of the
virtual address space
. length of the local host name: limited by the the size of the
virtual address space
. length of a "short" argument: limited by the the size of the
virtual address space
. length of a "long" argument: limited by the the size of the
virtual address space
. maximum amount of data output in a single fetch: not limited
Typical values for these limits are 30Mb for file systems and 128Mb
for virtual address space.
To date, nobody has run up against any of these limitations, many of
which are substantially larger than most current user mail reading
programs.
There are several advantages to the scheme of tags and solicited
responses and unsolicited data. First, the infamous synchronization
problems of SMTP and similar protocols do not happen with tagged
commands; a command is not considered satisfied until a completion
acknowledgement with the same tag is seen. Tagging allows an
arbitrary amount of other responses ("solicited" data) to be sent by
the server with no possibility of the client losing synchronization.
Compare this with the problems that FTP or SMTP clients have with
continuation, partial completion, and commentary reply codes.
Another advantage is that a non-lockstep client implementation is
possible. The client could send a command, and entrust the handling
of the server responses to a different process which would signal the
client when the tagged response comes in. Some clients might be
implemented in a thoroughly asynchronous manner, having, perhaps,
multiple outstanding commands at any given time. Note: this does
not require that the server process these commands in anything other
than a lock-step manner. It simply allows clients to take advantage
of servers that are able to do such asynchronous operations.
It was observed that synchronization problems can occur with literals
if the literal is not recognized as such. Fortunately, the cases in
which this can happen are relatively rare; a mechanism (the special
"+" tag response) was introduced to handle those few cases which
could happen. The proper way to address this problem in all cases is
probably to move towards a record-oriented architecture instead of
the text stream model provided by TCP.
Unsolicited data needs some discussion. Unlike most protocols, in
which the server merely does the client's bidding, an IMAP3 server
has a semi-autonomous role. By means of sending "unsolicited data",
the server is in effect sending a command to the client -- to update
and/or extend its (incomplete) model of the mailbox with new
information from the server. In this viewpoint, although a "fetch"
command is a request for specific information from the client, the
server is always at liberty to include more than the desired data as
"unsolicited". A server acknowledgement to the "fetch" is a
statement that at least all the requested data has been sent.
In terms of implementation, a simple lock-step client may have a
local cache of data from the mailbox. This cache is incomplete in
general, and at select time is empty. A listener on the IMAP
connection in the client processes all solicited and unsolicited data
symmetrically, and updates the cache based on this data, i.e., the
client faults on a cache miss and asks the server to fill that cache
slot synchronously. If a tagged completion response arrives, the
listener unblocks the process which sent the tagged request.
Clearly, given this model it is not strictly necessary to distinguish
most solicited from unsolicited data. Doing so, however, apart from
being clearer, also allows such simplistic, lock-step client
implementations that extract the specific value of the response to
command by trapping the tagged response. This allows the client not
to have to block on some complex predicate that involves watching to
see an update in a cache cell.
For example, perhaps as a result of opening a mailbox, solicited data
from the server arrives. The first piece of data is the number of
messages. This is used to size the cache; note that, if new mail
arrives, by sending a new "number of messages" unsolicited data
message server will cause the cache to be re-sized. If the client
attempts to access information from the cache, it will encounter
empty spots which will trigger "fetch" requests. The request would
be sent, some solicited data including the answer to the fetch will
flow back, and then the "fetch" response will unblock the client.
People familiar with demand-paged virtual memory design will
recognize this model as being very similar to page-fault handling on
a demand-paged system.
Formal Syntax
The following syntax specification uses the augmented Backus-Naur
Form (BNF) notation as specified in RFC822 with one exception; the
delimiter used with the "#" construct is a single space (SP) and not
a comma.
address ::= "(" addr_name SP addr_adl SP addr_mailbox SP
addr_host addr_comment ")"
addr_adl ::= nil / string
addr_comment ::= nil / string
addr_host ::= nil / string
addr_mailbox ::= nil / string
addr_name ::= nil / string
bboard ::= "BBOARD" SP bboard_name
bboard_name ::= string
bboard_notify ::= "BBOARD" sp bboard_name
canonical_key ::= "$CC" / "$FROM" / "$SUBJECT" / "$TO"
check ::= "CHECK"
concrete_key ::= string
copy ::= "COPY" SP sequence SP mailbox
criterion ::= "ALL" / "ANSWERED" /
"BCC" SP string / "BEFORE" SP string /
"BODY" SP string / "CC" SP string / "DELETED" /
"FLAGGED" / "KEYWORD" SP atom / "NEW" / "OLD" /
"ON" SP string / "RECENT" / "SEEN" /
"SINCE" SP string / "TEXT" SP string /
"TO" SP string / "UNANSWERED" / "UNDELETED" /
"UNFLAGGED" / "UNKEYWORD" / "UNSEEN" / key SP string
criteria ::= 1#criterion
data ::= ("FLAGS" SP flag_list /
search_notify / bboard_notify / mailbox_notify /
supported_versions_notify / "READONLY" / "READWRITE" /
"BYE" SP text_line / "OK" SP text_line /
"NO" SP text_line / "BAD" SP text_line)
date ::= string in form "dd-mmm-yy hh:mm:ss-zzz"
envelope ::= "(" env_date SP env_subject SP env_from SP
env_sender SP env_reply-to SP env_to SP
env_cc SP env_bcc SP env_in-reply-to SP
env_message-id ")"
env_bcc ::= nil / "(" 1*address ")"
env_cc ::= nil / "(" 1*address ")"
env_date ::= string
env_from ::= nil / "(" 1*address ")"
env_in-reply-to ::= nil / string
env_length ::= NUMBER
env_message-id ::= nil / string
env_reply-to ::= nil / "(" 1*address ")"
env_sender ::= nil / "(" 1*address ")"
env_subject ::= nil / string
env_to ::= nil / "(" 1*address ")"
expunge ::= "EXPUNGE"
feature ::= ATOM
fetch ::= "FETCH" SP sequence SP ("ALL" / "FAST" /
fetch_att / "(" 1#fetch_att ")")
fetch_att ::= "ENVELOPE" / "FLAGS" / "INTERNALDATE" /
"RFC822" / "RFC822.HEADER" / "RFC822.SIZE" /
"RFC822.TEXT" / key
find ::= "FIND" ("BBOARDS" / "MAILBOXES") pattern
flag_list ::= ATOM / "(" 1#ATOM ")"
flags ::= "FLAGS"
generic_key ::= "BCC" / "BODY" / "CC" / "FROM" / "HEADER" / "SIZE" /
"SUBJECT" / "TEXT" / "TO"
key ::= generic_key / canonical_key / concrete_key
literal ::= "{" NUMBER "}" CRLF ASCII-STRING
login ::= "LOGIN" SP userid SP password
logout ::= "LOGOUT"
mailbox ::= "INBOX" / string
mailbox_notify ::= MAILBOX non_inbox_mailbox_name
msg_copy ::= "COPY"
msg_data ::= (msg_exists / msg_recent / msg_expunge /
msg_fetch / msg_copy)
msg_exists ::= "EXISTS"
msg_expunge ::= "EXPUNGE"
msg_fetch ::= ("FETCH" / "STORE") SP "(" 1#("ENVELOPE" SP
env_length envelope / "FLAGS" SP "(" 1#(recent_flag
flag_list) ")" / "INTERNALDATE" SP date /
"RFC822" SP string / "RFC822.HEADER" SP string /
"RFC822.SIZE" SP NUMBER / "RFC822.TEXT" SP
string / key SP string_list) ")"
msg_recent ::= "RECENT"
msg_num ::= NUMBER
nil ::= "NIL"
non_inbox_mailbox_name ::= string
noop ::= "NOOP"
numbers ::= 1#NUMBER
password ::= string
pattern ::= string
recent_flag ::= "\RECENT"
read_only ::= "READONLY"
read_write ::= "READWRITE"
ready ::= "+" SP text_line
request ::= tag SP (noop / login / logout / select / check /
expunge / copy / fetch / store / search /
select_version / select_features /
supported_versions / bboard / find /
read_only / read_write / flags / set_flags ) CRLF
response ::= tag SP ("OK" / "NO" / "BAD") SP text_line CRLF
search ::= "SEARCH" SP criteria
search_notify ::= "SEARCH" SP (numbers) SP (criteria)
select ::= "SELECT" SP mailbox
select_features ::= "SELECT.FEATURES" 1#feature
select_version ::= "SELECT.VERSION" SP "(" NUMBER SP NUMBER ")"
sequence ::= NUMBER / (NUMBER "," sequence) / (NUMBER ":"
sequence)
set_flags ::= "SET.FLAGS" SP flag_list
solicited ::= tag SP (msg_num SP msg_data / data /
solicited_only) CRLF
solicited_only ::= {None currently defined}
store ::= "STORE" SP sequence SP store_att
store_att ::= ("+FLAGS" SP flag_list / "-FLAGS" SP flag_list /
"FLAGS" SP flag_list / RFC822.TEXT SP string
/ RFC822.HEADER SP string / key SP string)
string ::= atom / """" 1*character """" / literal
string_list ::= string / ("(" 1#string ")")
supported_versions ::= "SUPPORTED.VERSIONS"
supported_versions_notify ::= "SUPPORTED.VERSIONS" "(" 1#version_spec
")"
system_flags ::= "\ANSWERED" SP "\FLAGGED" SP "\DELETED" SP
"\SEEN"
tag ::= atom
unsolicited ::= "*" SP (msg_num SP msg_data / data) CRLF
userid ::= string
version_spec ::= "(" NUMBER SP NUMBER SP 1#feature ")"
Appendix: Features.
In this section we outline the standard features that are supported
by all IMAP3 servers and identify those features which are
recommended or experimental. For each of these features the default
setting is specified. This means that it is required of any server
that supports a given feature to make the default enabledness of that
feature as is specified below. It is required that for each feature
supported by a server the inverse feature should also be supported.
The inverse feature name shall always be defined as the feature name
preceded by the "~" character. Thus, the AUTO.SET.SEEN feature is
disabled by the ~AUTO.SET.SEEN feature.
Required Features:
AUTO.SET.SEEN - When this features is enabled (default is disabled),
the \\SEEN flag is set for all appropriate messages as a side
effect of any of the following:
FETCH of RFC822
FETCH of RFC822.TEXT
COPY
Justification: This feature is provided for the use of clients
that are unable to pipeline their commands effectively and
communicate over high latency connections. When disabled,
the server will not perform any such side effects. This feature
is also provided so as to smooth the transition from IMAP2 to
IMAP3.
TAGGED.SOLICITED - When this feature is enabled (default is enabled
for IMAP3, disabled for IMAP2 mode), solicited responses from
the server will have the tag specified by the client.
When this feature is disabled, solicited responses from the
server will have the IMAP2 compatible tag "*", not the
tag specified by the client.
Justification: This feature is provided so as to smooth the
transition from IMAP2 to IMAP3.
Recommended Features.
EIGHT.BIT.TRANSPARENT - When this feature is enabled
(default is disabled), the server allows the transparent
transmission of eight bit characters. When this feature is
disabled, the value of any bit other than the least significant
7 bits transmitted by the server is unspecified. If this
feature is enabled, the characters that compose all command
keywords specified in the IMAP3 grammar and all feature names
use only their 7 least significant bits.
Justification: This feature is provided for the purpose of
supporting national character sets within messages, encoded
languages such as Japanese Kanji characters and also of binary
data, such as programs, graphics and sound.
NEW.MAIL.NOTIFY - When this feature is enabled (default is
disabled for compatibility with the majority of existing
IMAP2 servers), the server will notify the client of the
arrival of new mail in the currently selected mailbox
using the appropriate RECENT and EXISTS unsolicited messages
without the client needing to send periodic CHECK commands.
Justification: This feature is provided to allow clients to
switch off any periodic polling strategy that they may use
to look for new mail. Such polling unnecessarily uses bandwidth
and can cause the interactive performance to degrade because
the user can be kept waiting while some background process
is doing a CHECK.
SEND - When this feature is enabled (default is disabled) a new
"SEND" command becomes available to the client. The SEND
command instructs the server to send a message, rather
than requiring the client to use its own, local message
sending capability, for example. An example of of the
send command might be as follows:
tag42 SEND RFC822 {2083}
From: James Rice <Rice@Sumex-Aim.Stanford.Edu>
To:.....
If the server is unable to parse the message being sent then
it is required to issue a suitable NO notification to the client.
If the message cannot be delivered for some reason then the
server should send a suitable message to the FROM: address
of the message detailing the delivery failure.
When the SEND feature is enabled, the "send" production in
the grammar is added and as defined below. The "send"
request is added to the list of requests in the request
production also as shown below:
message_format ::= RFC822
request ::= tag SP (noop / login / logout / select / check /
expunge / copy / fetch / store / search /
select_version / select_features /
supported_versions / bboard / find /
read_only / read_write / flags /
set_flags / send) CRLF
send ::= SEND SP message_format SP string
Justification: This feature is provided so that mail can be
sent by the same reliable server that is used for the storage
of mail. This has, amongst others, the following benefits:
- Single process clients need not be delayed by mail
transmission.
- Mail sent by the client will have the server named as the
message's sender. This can be important because there are
a lot of mailers that erroneously cause reply mail to be
sent to the Sender, not the From or Reply-To address. Since
the client in general is not listening for mail being sent
to it directly this can cause mail to be lost.