< draft-leiba-imap-implement-guide-08.txt   draft-leiba-imap-implement-guide-09.txt >
Network Working Group B. Leiba
Network Working Group B. Leiba Internet Draft IBM T.J. Watson Research Center
Internet Draft IBM T.J. Watson Research Center Document: draft-leiba-imap-implement-guide-09.txt May 1999
Document: draft-leiba-imap-implement-guide-08.txt December 1998 Expires October 1999
Expires June 1999
IMAP4 Implementation Recommendations IMAP4 Implementation Recommendations
Status of this Document Status of this Document
This document provides information for the Internet community. This This document is an Internet-Draft and is in full conformance with
document does not specify an Internet standard of any kind. all provisions of Section 10 of RFC2026. Internet-Drafts are working
Distribution of this document is unlimited. 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.
This document is an Internet Draft. Internet Drafts are working Internet-Drafts are draft documents valid for a maximum of six months
documents of the Internet Engineering Task Force (IETF), its Areas, and may be updated, replaced, or obsoleted by other documents at any
and its Working Groups. Note that other groups may also distribute time. It is inappropriate to use Internet-Drafts as reference
working documents as Internet Drafts. material or to cite them other than as "work in progress."
Internet Drafts are draft documents valid for a maximum of six The list of current Internet-Drafts can be accessed at
months. Internet Drafts may be updated, replaced, or obsoleted by http://www.ietf.org/ietf/1id-abstracts.txt
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".
To view the entire list of current Internet-Drafts, please check the The list of Internet-Draft Shadow Directories can be accessed at
"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow http://www.ietf.org/shadow.html.
Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern
Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific
Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast).
A revised version of this draft document will be submitted to the RFC This document provides information for the Internet community. This
editor. Discussion and suggestions for improvement are requested. document does not specify an Internet standard of any kind.
This document will expire by the end of June 1999. Distribution of this document is unlimited. A revised version of
this draft document will be submitted to the RFC editor. Discussion
and suggestions for improvement are requested; discussion should be
held on the IMAP mailing list, "imap@u.washington.edu" (subscription
requests go to "imap-request@u.washington.edu").
1. Abstract 1. Abstract
The IMAP4 specification [RFC-2060] describes a rich protocol for use The IMAP4 specification [RFC-2060] describes a rich protocol for use
in building clients and servers for storage, retrieval, and in building clients and servers for storage, retrieval, and
manipulation of electronic mail. Because the protocol is so rich and manipulation of electronic mail. Because the protocol is so rich and
has so many implementation choices, there are often trade-offs that has so many implementation choices, there are often trade-offs that
must be made and issues that must be considered when designing such must be made and issues that must be considered when designing such
clients and servers. This document attempts to outline these issues clients and servers. This document attempts to outline these issues
and to make recommendations in order to make the end products as and to make recommendations in order to make the end products as
interoperable as possible. interoperable as possible.
Internet DRAFT Implementation Recommendations December 1998
2. Conventions used in this document 2. Conventions used in this document
In examples, "C:" indicates lines sent by a client that is connected In examples, "C:" indicates lines sent by a client that is connected
to a server. "S:" indicates lines sent by the server to the client. to a server. "S:" indicates lines sent by the server to the client.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC-2119]. document are to be interpreted as described in [RFC-2119].
3. Interoperability Issues and Recommendations 3. Interoperability Issues and Recommendations
skipping to change at page 3, line 4 skipping to change at page 3, line 6
in your own client (for load balancing or other such reasons), in your own client (for load balancing or other such reasons),
and and
4. you MUST avoid using the STATUS command on a mailbox that you 4. you MUST avoid using the STATUS command on a mailbox that you
have selected (with some server implementations the STATUS have selected (with some server implementations the STATUS
command has the same problems with multiple access as do the command has the same problems with multiple access as do the
SELECT and EXAMINE commands). SELECT and EXAMINE commands).
A further note about STATUS: The STATUS command is sometimes used to A further note about STATUS: The STATUS command is sometimes used to
check a non-selected mailbox for new mail. This mechanism MUST NOT check a non-selected mailbox for new mail. This mechanism MUST NOT
be used to check for new mail in the selected mailbox; section 5.2 of be used to check for new mail in the selected mailbox; section 5.2 of
Internet DRAFT Implementation Recommendations December 1998
[RFC-2060] specifically forbids this in its last paragraph. Further, [RFC-2060] specifically forbids this in its last paragraph. Further,
since STATUS takes a mailbox name it is an independent operation, not since STATUS takes a mailbox name it is an independent operation, not
operating on the selected mailbox. Because of this, the information operating on the selected mailbox. Because of this, the information
it returns is not necessarily in synchronization with the selected it returns is not necessarily in synchronization with the selected
mailbox state. mailbox state.
3.1.2. Severed Connections 3.1.2. Severed Connections
The client/server connection may be severed for one of three reasons: The client/server connection may be severed for one of three reasons:
the client severs the connection, the server severs the connection, the client severs the connection, the server severs the connection,
skipping to change at page 4, line 4 skipping to change at page 4, line 6
When the server wants to sever a connection it's usually due to an When the server wants to sever a connection it's usually due to an
inactivity timeout or is because a situation has arisen that has inactivity timeout or is because a situation has arisen that has
changed the state of the mail store in a way that the server can not changed the state of the mail store in a way that the server can not
communicate to the client. The server SHOULD send an untagged BYE communicate to the client. The server SHOULD send an untagged BYE
response to the client and then close the socket. Sending an response to the client and then close the socket. Sending an
untagged BYE response before severing allows the server to send a untagged BYE response before severing allows the server to send a
human-readable explanation of the problem to the client, which the human-readable explanation of the problem to the client, which the
client may then log, display to the user, or both (see section 7.1.5 client may then log, display to the user, or both (see section 7.1.5
of [RFC-2060]). of [RFC-2060]).
Internet DRAFT Implementation Recommendations December 1998
Regarding inactivity timeouts, there is some controversy. Unlike Regarding inactivity timeouts, there is some controversy. Unlike
POP, for which the design is for a client to connect, retrieve mail, POP, for which the design is for a client to connect, retrieve mail,
and log out, IMAP<RIGHT SINGLE QUOTATION MARK>s design encourages long-lived (and mostly and log out, IMAP<RIGHT SINGLE QUOTATION MARK>s design encourages long-lived (and mostly
inactive) client/server sessions. As the number of users grows, this inactive) client/server sessions. As the number of users grows, this
can use up a lot of server resources, especially with clients that can use up a lot of server resources, especially with clients that
are designed to maintain sessions for mailboxes that the user has are designed to maintain sessions for mailboxes that the user has
finished accessing. To alleviate this, a server MAY implement an finished accessing. To alleviate this, a server MAY implement an
inactivity timeout, unilaterally closing a session (after first inactivity timeout, unilaterally closing a session (after first
sending an untagged BYE, as noted above). Some server operators have sending an untagged BYE, as noted above). Some server operators have
reported dramatic improvements in server performance after doing reported dramatic improvements in server performance after doing
skipping to change at page 5, line 4 skipping to change at page 5, line 9
reduce that danger. reduce that danger.
There is also the case where a client can flood a server, by sending There is also the case where a client can flood a server, by sending
an arbitratily long command. We'll discuss that issue, too, in this an arbitratily long command. We'll discuss that issue, too, in this
section. section.
3.2.1.1. Listing Mailboxes 3.2.1.1. Listing Mailboxes
Some servers present Usenet newsgroups to IMAP users. Newsgroups, Some servers present Usenet newsgroups to IMAP users. Newsgroups,
and other such hierarchical mailbox structures, can be very numerous and other such hierarchical mailbox structures, can be very numerous
Internet DRAFT Implementation Recommendations December 1998
but may have only a few entries at the top level of hierarchy. Also, but may have only a few entries at the top level of hierarchy. Also,
some servers are built against mail stores that can, unbeknownst to some servers are built against mail stores that can, unbeknownst to
the server, have circular hierarchies - that is, it's possible for the server, have circular hierarchies - that is, it's possible for
"a/b/c/d" to resolve to the same file structure as "a", which would "a/b/c/d" to resolve to the same file structure as "a", which would
then mean that "a/b/c/d/b" is the same as "a/b", and the hierarchy then mean that "a/b/c/d/b" is the same as "a/b", and the hierarchy
will never end. The LIST response in this case will be unlimited. will never end. The LIST response in this case will be unlimited.
Clients that will have trouble with this are those that use Clients that will have trouble with this are those that use
C: 001 LIST "" * C: 001 LIST "" *
to determine the mailbox list. Because of this, clients SHOULD NOT to determine the mailbox list. Because of this, clients SHOULD NOT
skipping to change at page 6, line 5 skipping to change at page 6, line 6
3.2.1.2. Fetching the List of Messages 3.2.1.2. Fetching the List of Messages
When a client selects a mailbox, it is given a count, in the untagged When a client selects a mailbox, it is given a count, in the untagged
EXISTS response, of the messages in the mailbox. This number can be EXISTS response, of the messages in the mailbox. This number can be
very large. In such a case it might be unwise to use very large. In such a case it might be unwise to use
C: 004 FETCH 1:* ALL C: 004 FETCH 1:* ALL
to populate the user's view of the mailbox. One good method to avoid to populate the user's view of the mailbox. One good method to avoid
problems with this is to batch the requests, thus: problems with this is to batch the requests, thus:
Internet DRAFT Implementation Recommendations December 1998
C: 004 FETCH 1:50 ALL C: 004 FETCH 1:50 ALL
S: * 1 FETCH ...etc... S: * 1 FETCH ...etc...
S: 004 OK done S: 004 OK done
C: 005 FETCH 51:100 ALL C: 005 FETCH 51:100 ALL
S: * 51 FETCH ...etc... S: * 51 FETCH ...etc...
S: 005 OK done S: 005 OK done
C: 006 FETCH 101:150 ALL C: 006 FETCH 101:150 ALL
...etc... ...etc...
Using this method, another command, such as "FETCH 6 BODY[1]" can be Using this method, another command, such as "FETCH 6 BODY[1]" can be
skipping to change at page 7, line 4 skipping to change at page 7, line 8
want to present various sort orders to the user (by subject, by date want to present various sort orders to the user (by subject, by date
sent, by sender, and so on) and in that case (lacking a SORT sent, by sender, and so on) and in that case (lacking a SORT
extension on the server side) the client WILL have to retrieve all extension on the server side) the client WILL have to retrieve all
message descriptors. A client that provides this service SHOULD NOT message descriptors. A client that provides this service SHOULD NOT
do it by default and SHOULD inform the user of the costs of choosing do it by default and SHOULD inform the user of the costs of choosing
this option for large mailboxes. this option for large mailboxes.
3.2.1.3. Fetching a Large Body Part 3.2.1.3. Fetching a Large Body Part
The issue here is similar to the one for a list of messages. In the The issue here is similar to the one for a list of messages. In the
Internet DRAFT Implementation Recommendations December 1998
BODYSTRUCTURE response the client knows the size, in bytes, of the BODYSTRUCTURE response the client knows the size, in bytes, of the
body part it plans to fetch. Suppose this is a 70 MB video clip. body part it plans to fetch. Suppose this is a 70 MB video clip.
The client can use partial fetches to retrieve the body part in The client can use partial fetches to retrieve the body part in
pieces, avoiding the problem of an uninterruptible 70 MB literal pieces, avoiding the problem of an uninterruptible 70 MB literal
coming back from the server: coming back from the server:
C: 022 FETCH 3 BODY[1]<0.20000> C: 022 FETCH 3 BODY[1]<0.20000>
S: * 3 FETCH (FLAGS(\Seen) BODY[1]<0> {20000} S: * 3 FETCH (FLAGS(\Seen) BODY[1]<0> {20000}
S: ...data...) S: ...data...)
S: 022 OK done S: 022 OK done
skipping to change at page 8, line 4 skipping to change at page 8, line 8
forcing the transfer of all body parts when the user might only want forcing the transfer of all body parts when the user might only want
to see some of them - a user logged on by modem and reading a small to see some of them - a user logged on by modem and reading a small
text message with a large ZIP file attached may prefer to read the text message with a large ZIP file attached may prefer to read the
text only and save the ZIP file for later. Therefore, a client text only and save the ZIP file for later. Therefore, a client
SHOULD NOT normally retrieve entire messages and SHOULD retrieve SHOULD NOT normally retrieve entire messages and SHOULD retrieve
message body parts selectively. message body parts selectively.
3.2.1.5. Long Command Lines 3.2.1.5. Long Command Lines
A client can wind up building a very long command line in an effort A client can wind up building a very long command line in an effort
Internet DRAFT Implementation Recommendations December 1998
to try to be efficient about requesting information from a server. to try to be efficient about requesting information from a server.
This can typically happen when a client builds a message set from This can typically happen when a client builds a message set from
selected messages and doesn't recognise that contiguous blocks of selected messages and doesn't recognise that contiguous blocks of
messages may be group in a range. Suppose a user selects all 10,000 messages may be group in a range. Suppose a user selects all 10,000
messages in a large mailbox and then unselects message 287. The messages in a large mailbox and then unselects message 287. The
client could build that message set as "1:286,288:10000", but a client could build that message set as "1:286,288:10000", but a
client that doesn't handle that might try to enumerate each message client that doesn't handle that might try to enumerate each message
individually and build "1,2,3,4, [and so on] ,9999,10000". Adding individually and build "1,2,3,4, [and so on] ,9999,10000". Adding
that to the fetch command results in a command line that's almost that to the fetch command results in a command line that's almost
49,000 octets long, and, clearly, one can construct a command line 49,000 octets long, and, clearly, one can construct a command line
skipping to change at page 9, line 5 skipping to change at page 9, line 7
hide the LIST command completely; the user needs to have a way to hide the LIST command completely; the user needs to have a way to
choose between LIST and LSUB. The usual way to do this is to provide choose between LIST and LSUB. The usual way to do this is to provide
a setting like "show which mailboxes?: [] all [] subscribed only". a setting like "show which mailboxes?: [] all [] subscribed only".
3.2.3. Searching 3.2.3. Searching
IMAP SEARCH commands can become particularly troublesome (that is, IMAP SEARCH commands can become particularly troublesome (that is,
slow) on mailboxes containing a large number of messages. So let's slow) on mailboxes containing a large number of messages. So let's
put a few things in perspective in that regard. put a few things in perspective in that regard.
Internet DRAFT Implementation Recommendations December 1998
The flag searches SHOULD be fast. The flag searches (ALL, [UN]SEEN, The flag searches SHOULD be fast. The flag searches (ALL, [UN]SEEN,
[UN]ANSWERED, [UN]DELETED, [UN]DRAFT, [UN]FLAGGED, NEW, OLD, RECENT) [UN]ANSWERED, [UN]DELETED, [UN]DRAFT, [UN]FLAGGED, NEW, OLD, RECENT)
are known to be used by clients for the client's own use (for are known to be used by clients for the client's own use (for
instance, some clients use "SEARCH UNSEEN" to find unseen mail and instance, some clients use "SEARCH UNSEEN" to find unseen mail and
"SEARCH DELETED" to warn the user before expunging messages). "SEARCH DELETED" to warn the user before expunging messages).
Other searches, particularly the text searches (HEADER, TEXT, BODY) Other searches, particularly the text searches (HEADER, TEXT, BODY)
are initiated by the user, rather than by the client itself, and are initiated by the user, rather than by the client itself, and
somewhat slower performance can be tolerated, since the user is aware somewhat slower performance can be tolerated, since the user is aware
that the search is being done (and is probably aware that it might be that the search is being done (and is probably aware that it might be
skipping to change at page 10, line 4 skipping to change at page 10, line 7
and isn't permitted in some circumstances. Clients SHOULD use these and isn't permitted in some circumstances. Clients SHOULD use these
features to avoid sending requests that a well designed client would features to avoid sending requests that a well designed client would
know to be invalid. This section explains this in more detail. know to be invalid. This section explains this in more detail.
3.3.1. The CAPABILITY Command 3.3.1. The CAPABILITY Command
All IMAP4 clients SHOULD use the CAPABILITY command to determine what All IMAP4 clients SHOULD use the CAPABILITY command to determine what
version of IMAP and what optional features a server supports. The version of IMAP and what optional features a server supports. The
client SHOULD NOT send IMAP4rev1 commands and arguments to a server client SHOULD NOT send IMAP4rev1 commands and arguments to a server
that does not advertize IMAP4rev1 in its CAPABILITY response. that does not advertize IMAP4rev1 in its CAPABILITY response.
Internet DRAFT Implementation Recommendations December 1998
Similarly, the client SHOULD NOT send IMAP4 commands that no longer Similarly, the client SHOULD NOT send IMAP4 commands that no longer
exist in IMAP4rev1 to a server that does not advertize IMAP4 in its exist in IMAP4rev1 to a server that does not advertize IMAP4 in its
CAPABILITY response. An IMAP4rev1 server is NOT required to support CAPABILITY response. An IMAP4rev1 server is NOT required to support
obsolete IMAP4 or IMAP2bis commands (though some do; do not let this obsolete IMAP4 or IMAP2bis commands (though some do; do not let this
fact lull you into thinking that it's valid to send such commands to fact lull you into thinking that it's valid to send such commands to
an IMAP4rev1 server). an IMAP4rev1 server).
A client SHOULD NOT send commands to probe for the existance of A client SHOULD NOT send commands to probe for the existance of
certain extensions. All standard and standards-track extensions certain extensions. All standard and standards-track extensions
include CAPABILITY tokens indicating their presense. All private and include CAPABILITY tokens indicating their presense. All private and
skipping to change at page 11, line 4 skipping to change at page 11, line 7
section 2.2.2 and the preamble to section 7 of the IMAP4rev1 spec section 2.2.2 and the preamble to section 7 of the IMAP4rev1 spec
[RFC-2060]. [RFC-2060].
3.4.1. Well Formed Protocol 3.4.1. Well Formed Protocol
We cannot stress enough the importance of adhering strictly to the We cannot stress enough the importance of adhering strictly to the
protocol grammar. The specification of the protocol is quite rigid; protocol grammar. The specification of the protocol is quite rigid;
do not assume that you can insert blank space for "readability" if do not assume that you can insert blank space for "readability" if
none is called for. Keep in mind that there are parsers out there none is called for. Keep in mind that there are parsers out there
that will crash if there are protocol errors. There are clients that that will crash if there are protocol errors. There are clients that
Internet DRAFT Implementation Recommendations December 1998
will report every parser burp to the user. And in any case, will report every parser burp to the user. And in any case,
information that cannot be parsed is information that is lost. Be information that cannot be parsed is information that is lost. Be
careful in your protocol generation. And see "A Word About Testing", careful in your protocol generation. And see "A Word About Testing",
below. below.
In particular, note that the string in the INTERNALDATE response is In particular, note that the string in the INTERNALDATE response is
NOT an RFC-822 date string - that is, it is not in the same format as NOT an RFC-822 date string - that is, it is not in the same format as
the first string in the ENVELOPE response. Since most clients will, the first string in the ENVELOPE response. Since most clients will,
in fact, accept an RFC-822 date string in the INTERNALDATE response, in fact, accept an RFC-822 date string in the INTERNALDATE response,
it's easy to miss this in your interoperability testing. But it will it's easy to miss this in your interoperability testing. But it will
skipping to change at page 12, line 4 skipping to change at page 12, line 7
characters. characters.
The CR and LF characters may be sent ONLY in literals; they are not The CR and LF characters may be sent ONLY in literals; they are not
allowed, even if escaped, inside quoted strings. allowed, even if escaped, inside quoted strings.
And while we're talking about special characters: the IMAP spec, in And while we're talking about special characters: the IMAP spec, in
the section titled "Mailbox International Naming Convention", the section titled "Mailbox International Naming Convention",
describes how to encode mailbox names in modified UTF-7 [UTF-7 and describes how to encode mailbox names in modified UTF-7 [UTF-7 and
RFC-2060]. Implementations MUST adhere to this in order to be RFC-2060]. Implementations MUST adhere to this in order to be
interoperable in the international market, and servers SHOULD interoperable in the international market, and servers SHOULD
Internet DRAFT Implementation Recommendations December 1998
validate mailbox names sent by client and reject names that do not validate mailbox names sent by client and reject names that do not
conform. conform.
As to special characters in userids and passwords: clients MUST NOT
restrict what a user may type in for a userid or a password. The
formal grammar specifies that these are "astrings", and an astring
can be a literal. A literal, in turn can contain any 8-bit
character, and clients MUST allow users to enter all 8-bit characters
here, and MUST pass them, unchanged, to the server (being careful to
send them as literals when necessary). In particular, some server
configurations use "@" in user names, and some clients do not allow
that character to be entered; this creates a severe interoperability
problem.
3.4.3. UIDs and UIDVALIDITY 3.4.3. UIDs and UIDVALIDITY
Servers that support existing back-end mail stores often have no good Servers that support existing back-end mail stores often have no good
place to save UIDs for messages. Often the existing mail store will place to save UIDs for messages. Often the existing mail store will
not have the concept of UIDs in the sense that IMAP has: strictly not have the concept of UIDs in the sense that IMAP has: strictly
increasing, never re-issued, 32-bit integers. Some servers solve increasing, never re-issued, 32-bit integers. Some servers solve
this by storing the UIDs in a place that's accessible to end users, this by storing the UIDs in a place that's accessible to end users,
allowing for the possibility that the users will delete them. Others allowing for the possibility that the users will delete them. Others
solve it by re-assigning UIDs every time a mailbox is selected. solve it by re-assigning UIDs every time a mailbox is selected.
skipping to change at page 13, line 4 skipping to change at page 13, line 18
in reasonably finite time if it's global across the server. If you in reasonably finite time if it's global across the server. If you
assign UIDs sequentially in one mailbox, you will not have to start assign UIDs sequentially in one mailbox, you will not have to start
re-using them until you have had, at one time or another, 2**32 re-using them until you have had, at one time or another, 2**32
different messages in that mailbox. In the global case, you will different messages in that mailbox. In the global case, you will
have to reuse them once you have had, at one time or another, 2**32 have to reuse them once you have had, at one time or another, 2**32
different messages in the entire mail store. Suppose your server has different messages in the entire mail store. Suppose your server has
around 8000 users registered (2**13). That gives an average of 2**19 around 8000 users registered (2**13). That gives an average of 2**19
UIDs per user. Suppose each user gets 32 messages (2**5) per day. UIDs per user. Suppose each user gets 32 messages (2**5) per day.
That gives you 2**14 days (16000+ days = about 45 years) before you That gives you 2**14 days (16000+ days = about 45 years) before you
run out. That may seem like enough, but multiply the usage just a run out. That may seem like enough, but multiply the usage just a
Internet DRAFT Implementation Recommendations December 1998
little (a lot of spam, a lot of mailing list subscriptions, more little (a lot of spam, a lot of mailing list subscriptions, more
users) and you limit yourself too much. users) and you limit yourself too much.
What's worse is that if you have to wrap the UIDs, and, thus, you What's worse is that if you have to wrap the UIDs, and, thus, you
have to change UIDVALIDITY and invalidate the UIDs in the mailbox, have to change UIDVALIDITY and invalidate the UIDs in the mailbox,
you have to do it for EVERY mailbox in the system, since they all you have to do it for EVERY mailbox in the system, since they all
share the same UID pool. If you assign UIDs per mailbox and you have share the same UID pool. If you assign UIDs per mailbox and you have
a problem, you only have to kill the UIDs for that one mailbox. a problem, you only have to kill the UIDs for that one mailbox.
Under extreme circumstances (and this is extreme, indeed), the server Under extreme circumstances (and this is extreme, indeed), the server
skipping to change at page 14, line 5 skipping to change at page 14, line 16
Alternatively, a server may force the client to re-select the Alternatively, a server may force the client to re-select the
mailbox, at which time it will obtain a new UIDVALIDITY value. To do mailbox, at which time it will obtain a new UIDVALIDITY value. To do
this, the server closes this client session (see "Severed this, the server closes this client session (see "Severed
Connections" above) and the client then reconnects and gets back in Connections" above) and the client then reconnects and gets back in
synch. Clients MUST be prepared for either of these behaviours. synch. Clients MUST be prepared for either of these behaviours.
We do not know of, nor do we anticipate the future existance of, a We do not know of, nor do we anticipate the future existance of, a
server that changes UIDVALIDITY while there are existing messages, server that changes UIDVALIDITY while there are existing messages,
but clients MUST be prepared to handle this eventuality. but clients MUST be prepared to handle this eventuality.
Internet DRAFT Implementation Recommendations December 1998
3.4.4. FETCH Responses 3.4.4. FETCH Responses
When a client asks for certain information in a FETCH command, the When a client asks for certain information in a FETCH command, the
server MAY return the requested information in any order, not server MAY return the requested information in any order, not
necessarily in the order that it was requested. Further, the server necessarily in the order that it was requested. Further, the server
MAY return the information in separate FETCH responses and MAY also MAY return the information in separate FETCH responses and MAY also
return information that was not explicitly requested (to reflect to return information that was not explicitly requested (to reflect to
the client changes in the state of the subject message). Some the client changes in the state of the subject message). Some
examples: examples:
skipping to change at page 15, line 4 skipping to change at page 15, line 16
in any particular order, or even that any will come at all. If after in any particular order, or even that any will come at all. If after
receiving the tagged response for a FETCH command the client finds receiving the tagged response for a FETCH command the client finds
that it did not get all of the information requested, the client that it did not get all of the information requested, the client
SHOULD send a NOOP command to the server to ensure that the server SHOULD send a NOOP command to the server to ensure that the server
has an opportunity to send any pending EXPUNGE responses to the has an opportunity to send any pending EXPUNGE responses to the
client (see [RFC-2180]). client (see [RFC-2180]).
3.4.5. RFC822.SIZE 3.4.5. RFC822.SIZE
Some back-end mail stores keep the mail in a canonical form, rather Some back-end mail stores keep the mail in a canonical form, rather
Internet DRAFT Implementation Recommendations December 1998
than retaining the original MIME format of the messages. This means than retaining the original MIME format of the messages. This means
that the server must reassemble the message to produce a MIME stream that the server must reassemble the message to produce a MIME stream
when a client does a fetch such as RFC822 or BODY[], requesting the when a client does a fetch such as RFC822 or BODY[], requesting the
entire message. It also may mean that the server has no convenient entire message. It also may mean that the server has no convenient
way to know the RFC822.SIZE of the message. Often, such a server way to know the RFC822.SIZE of the message. Often, such a server
will actually have to build the MIME stream to compute the size, only will actually have to build the MIME stream to compute the size, only
to throw the stream away and report the size to the client. to throw the stream away and report the size to the client.
When this is the case, some servers have chosen to estimate the size, When this is the case, some servers have chosen to estimate the size,
rather than to compute it precisely. Such an estimate allows the rather than to compute it precisely. Such an estimate allows the
skipping to change at page 16, line 4 skipping to change at page 16, line 16
explanation and for recommendations. explanation and for recommendations.
3.4.7. The Namespace Issue 3.4.7. The Namespace Issue
Namespaces are a very muddy area in IMAP4 implementation right now Namespaces are a very muddy area in IMAP4 implementation right now
(see [NAMESPACE] for a proposal to clear the water a bit). Until the (see [NAMESPACE] for a proposal to clear the water a bit). Until the
issue is resolved, the important thing for client developers to issue is resolved, the important thing for client developers to
understand is that some servers provide access through IMAP to more understand is that some servers provide access through IMAP to more
than just the user's personal mailboxes, and, in fact, the user's than just the user's personal mailboxes, and, in fact, the user's
personal mailboxes may be "hidden" somewhere in the user's default personal mailboxes may be "hidden" somewhere in the user's default
Internet DRAFT Implementation Recommendations December 1998
hierarchy. The client, therefore, SHOULD provide a setting wherein hierarchy. The client, therefore, SHOULD provide a setting wherein
the user can specify a prefix to be used when accessing mailboxes. the user can specify a prefix to be used when accessing mailboxes.
If the user's mailboxes are all in "~/mail/", for instance, then the If the user's mailboxes are all in "~/mail/", for instance, then the
user can put that string in the prefix. The client would then put user can put that string in the prefix. The client would then put
the prefix in front of any name pattern in the LIST and LSUB the prefix in front of any name pattern in the LIST and LSUB
commands: commands:
C: 001 LIST "" ~/mail/% C: 001 LIST "" ~/mail/%
(See also "Reference Names in the LIST Command" below.) (See also "Reference Names in the LIST Command" below.)
3.4.8. Creating Special-Use Mailboxes 3.4.8. Creating Special-Use Mailboxes
skipping to change at page 17, line 5 skipping to change at page 17, line 17
3.4.9. Reference Names in the LIST Command 3.4.9. Reference Names in the LIST Command
Many implementers of both clients and servers are confused by the Many implementers of both clients and servers are confused by the
"reference name" on the LIST command. The reference name is intended "reference name" on the LIST command. The reference name is intended
to be used in much the way a "cd" (change directory) command is used to be used in much the way a "cd" (change directory) command is used
on Unix, PC DOS, Windows, and OS/2 systems. That is, the mailbox on Unix, PC DOS, Windows, and OS/2 systems. That is, the mailbox
name is interpreted in much the same way as a file of that name would name is interpreted in much the same way as a file of that name would
be found if one had done a "cd" command into the directory specified be found if one had done a "cd" command into the directory specified
by the reference name. For example, in Unix we have the following: by the reference name. For example, in Unix we have the following:
Internet DRAFT Implementation Recommendations December 1998
> cd /u/jones/junk > cd /u/jones/junk
> vi banana [file is "/u/jones/junk/banana"] > vi banana [file is "/u/jones/junk/banana"]
> vi stuff/banana [file is "/u/jones/junk/stuff/banana"] > vi stuff/banana [file is "/u/jones/junk/stuff/banana"]
> vi /etc/hosts [file is "/etc/hosts"] > vi /etc/hosts [file is "/etc/hosts"]
The interoperability problems with this, in practice, are several. In the past, there have been several interoperability problems with
First, while some IMAP servers are built on Unix or PC file systems, this. First, while some IMAP servers are built on Unix or PC file
many others are not, and the file system semantics do not make sense systems, many others are not, and the file system semantics do not
in those configurations. Second, while some IMAP servers expose the make sense in those configurations. Second, while some IMAP servers
underlying file system to the clients, others allow access only to expose the underlying file system to the clients, others allow access
the user's personal mailboxes, or to some other limited set of files, only to the user's personal mailboxes, or to some other limited set
making such file-system-like semantics less meaningful. Third, of files, making such file-system-like semantics less meaningful.
because the IMAP spec leaves the interpretation of the reference name Third, because the IMAP spec leaves the interpretation of the
as "implementation-dependent", the various server implementations reference name as "implementation-dependent", in the past the various
handle it in vastly differing ways, and fourth, many implementers server implementations handled it in vastly differing ways.
simply do not understand it and misuse it, do not use it, or ignore
it as a result.
The following statement gets somewhat into the religious issues that The following recommendations are the result of significant
we've tried to avoid scrupulously here: because of the confusion operational experience, and are intended to maximize
around the reference name, its use by a client is a dangerous thing, interoperability.
prone to result in interoperability problems. There are servers that
interpret it as originally intended; there are servers that ignore it
completely; there are servers that simply prepend it to the mailbox
name (with or without inserting a hierarchy delimiter in between).
Because a client can't know which of these four behaviours to expect,
a client SHOULD NOT use a reference name itself, expecting a
particular server behavior. However, a client SHOULD permit a USER,
by configuration, to use a reference name.
There is in no way universal agreement about the use or non-use of Server implementations MUST implement the reference argument in a way
the reference name. The last words here are, "Be aware." that matches the intended "change directory" operation as closely as
possible. As a minimum implementation, the reference argument may be
prepended to the mailbox name (while suppressing double delimiters;
see the next paragraph). Even servers that do not provide a way to
break out of the current hierarchy (see "breakout facility" below)
MUST provide a reasonable implementation of the reference argument,
as described here, so that they will interoperate with clients that
use it.
Server implementations that prepend the reference argument to the
mailbox name SHOULD insert a hierarchy delimiter between them, and
MUST NOT insert a second if one is already present:
C: A001 LIST ABC DEF
S: * LIST () "/" ABC/DEF <=== SHOULD do this
S: A001 OK done
C: A002 LIST ABC/ /DEF
S: * LIST () "/" ABC//DEF <=== MUST NOT do this
S: A002 OK done
On clients, the reference argument is chiefly used to implement a
"breakout facility", wherein the user may directly access a mailbox
outside the "current directory" hierarchy. Client implementations
SHOULD have an operational mode that does not use the reference
argument. This is to interoperate with older servers that did not
implement the reference argument properly. While it's a good idea to
give the user access to a breakout facility, clients that do not
intend to do so SHOULD NOT use the reference argument at all.
Client implementations SHOULD always place a trailing hierarchy
delimiter on the reference argument. This is because some servers
prepend the reference argument to the mailbox name without inserting
a hierarchy delimiter, while others do insert a hierarchy delimiter
if one is not already present. A client that puts the delimiter in
will work with both varieties of server.
Client implementations that implement a breakout facility SHOULD
allow the user to choose whether or not to use a leading hierarchy
delimiter on the mailbox argument. This is because the handling of a
leading mailbox hierarchy delimiter also varies from server to
server, and even between different mailstores on the same server. In
some cases, a leading hierarchy delimiter means "discard the
reference argument" (implementing the intended breakout facility),
thus:
C: A001 LIST ABC/ /DEF
S: * LIST () "/" /DEF
S: A001 OK done
In other cases, however, the two are catenated and the extra
hierarchy delimiter is discarded, thus:
C: A001 LIST ABC/ /DEF
S: * LIST () "/" ABC/DEF
S: A001 OK done
Client implementations MUST NOT assume that the server supports a
breakout facility, but MAY provide a way for the user to use one if
it is available. Any breakout facility should be exported to the
user interface. Note that there may be other "breakout" characters
besides the hierarchy delimiter (for instance, UNIX filesystem
servers are likely to use a leading "~" as well), and that their
interpretation is server-dependent.
3.4.12. Mailbox Hierarchy Delimiters 3.4.12. Mailbox Hierarchy Delimiters
The server's selection of what to use as a mailbox hierarchy The server's selection of what to use as a mailbox hierarchy
delimiter is a difficult one, involving several issues: What delimiter is a difficult one, involving several issues: What
characters do users expect to see? What characters can they enter characters do users expect to see? What characters can they enter
for a hierarchy delimiter if it is desired (or required) that the for a hierarchy delimiter if it is desired (or required) that the
user enter it? What character can be used for the hierarchy user enter it? What character can be used for the hierarchy
delimiter, noting that the chosen character can not otherwise be used delimiter, noting that the chosen character can not otherwise be used
in the mailbox name? in the mailbox name?
Because some interfaces show users the hierarchy delimiters or allow Because some interfaces show users the hierarchy delimiters or allow
users to enter qualified mailbox names containing them, server users to enter qualified mailbox names containing them, server
implementations SHOULD use delimiter characters that users generally implementations SHOULD use delimiter characters that users generally
expect to see as name separators. The most common characters used expect to see as name separators. The most common characters used
Internet DRAFT Implementation Recommendations December 1998
for this are "/" (as in Unix file names), "\" (as in OS/2 and Windows for this are "/" (as in Unix file names), "\" (as in OS/2 and Windows
file names), and "." (as in news groups). There is little to choose file names), and "." (as in news groups). There is little to choose
among these apart from what users may expect or what is dictated by among these apart from what users may expect or what is dictated by
the underlying file system, if any. One consideration about using the underlying file system, if any. One consideration about using
"\" is that it's also a special character in the IMAP protocol. "\" is that it's also a special character in the IMAP protocol.
While the use of other hierarchy delimiter characters is permissible, While the use of other hierarchy delimiter characters is permissible,
A DESIGNER IS WELL ADVISED TO STAY WITH ONE FROM THIS SET unless the A DESIGNER IS WELL ADVISED TO STAY WITH ONE FROM THIS SET unless the
server is intended for special purposes only. Implementers might be server is intended for special purposes only. Implementers might be
thinking about using characters such as "-", "_", ";", "&", "#", "@", thinking about using characters such as "-", "_", ";", "&", "#", "@",
and "!", but they should be aware of the surprise to the user as well and "!", but they should be aware of the surprise to the user as well
skipping to change at page 19, line 5 skipping to change at page 20, line 20
encode the fully qualified name, delimiters and all? The answer for encode the fully qualified name, delimiters and all? The answer for
IMAP is the former: encode each hierarchy level separately, and IMAP is the former: encode each hierarchy level separately, and
insert delimiters between. This makes it particularly important not insert delimiters between. This makes it particularly important not
to use as a hierarchy delimiter a character that might cause to use as a hierarchy delimiter a character that might cause
confusion with IMAP's modified UTF-7 [UTF-7 and RFC-2060] encoding. confusion with IMAP's modified UTF-7 [UTF-7 and RFC-2060] encoding.
To repeat: a server SHOULD use "/", "\", or "." as its hierarchy To repeat: a server SHOULD use "/", "\", or "." as its hierarchy
delimiter. The use of any other character is likely to cause delimiter. The use of any other character is likely to cause
problems and is STRONGLY DISCOURAGED. problems and is STRONGLY DISCOURAGED.
Internet DRAFT Implementation Recommendations December 1998
3.4.11. ALERT Response Codes 3.4.11. ALERT Response Codes
The protocol spec is very clear on the matter of what to do with The protocol spec is very clear on the matter of what to do with
ALERT response codes, and yet there are many clients that violate it ALERT response codes, and yet there are many clients that violate it
so it needs to be said anyway: "The human-readable text contains a so it needs to be said anyway: "The human-readable text contains a
special alert that MUST be presented to the user in a fashion that special alert that MUST be presented to the user in a fashion that
calls the user's attention to the message." That should be clear calls the user's attention to the message." That should be clear
enough, but I'll repeat it here: Clients MUST present ALERT text enough, but I'll repeat it here: Clients MUST present ALERT text
clearly to the user. clearly to the user.
skipping to change at page 20, line 5 skipping to change at page 21, line 22
C: 010 SELECT BANANA C: 010 SELECT BANANA
S: * ... untagged SELECT responses S: * ... untagged SELECT responses
S: 010 OK done S: 010 OK done
C: 011 STORE 1:* +FLAGS.SILENT \DELETED C: 011 STORE 1:* +FLAGS.SILENT \DELETED
S: 011 OK done S: 011 OK done
C: 012 CLOSE C: 012 CLOSE
S: 012 OK done S: 012 OK done
C: 013 DELETE BANANA C: 013 DELETE BANANA
S: 013 OK done S: 013 OK done
Internet DRAFT Implementation Recommendations December 1998
3.5. A Word About Testing 3.5. A Word About Testing
Since the whole point of IMAP is interoperability, and since Since the whole point of IMAP is interoperability, and since
interoperability can not be tested in a vacuum, the final interoperability can not be tested in a vacuum, the final
recommendation of this treatise is, "Test against EVERYTHING." Test recommendation of this treatise is, "Test against EVERYTHING." Test
your client against every server you can get an account on. Test your client against every server you can get an account on. Test
your server with every client you can get your hands on. Many your server with every client you can get your hands on. Many
clients make limited test versions available on the Web for the clients make limited test versions available on the Web for the
downloading. Many server owners will give serious client developers downloading. Many server owners will give serious client developers
guest accounts for testing. Contact them and ask. NEVER assume that guest accounts for testing. Contact them and ask. NEVER assume that
skipping to change at page 21, line 4 skipping to change at page 22, line 24
2180; Microsoft; July 1997. 2180; Microsoft; July 1997.
[UTF-8]; Yergeau, F.; " UTF-8, a transformation format of Unicode and [UTF-8]; Yergeau, F.; " UTF-8, a transformation format of Unicode and
ISO 10646"; RFC 2044; Alis Technilogies; October 1996. ISO 10646"; RFC 2044; Alis Technilogies; October 1996.
[UTF-7]; Goldsmith, D. & Davis, M.; "UTF-7, a Mail-Safe [UTF-7]; Goldsmith, D. & Davis, M.; "UTF-7, a Mail-Safe
Transformation Format of Unicode"; RFC 2152; Apple Computer, Inc. & Transformation Format of Unicode"; RFC 2152; Apple Computer, Inc. &
Taligent, Inc.; May 1997. Taligent, Inc.; May 1997.
[NAMESPACE]; Gahrns, M. & Newman, C.; "IMAP4 Namespace"; draft [NAMESPACE]; Gahrns, M. & Newman, C.; "IMAP4 Namespace"; draft
Internet DRAFT Implementation Recommendations December 1998
document <draft-gahrns-imap-namespace-01.txt>; Microsoft & Innosoft; document <draft-gahrns-imap-namespace-01.txt>; Microsoft & Innosoft;
June 1997. June 1997.
6. Author's Address 6. Author's Address
Barry Leiba Barry Leiba
IBM T.J. Watson Research Center IBM T.J. Watson Research Center
30 Saw Mill River Road 30 Saw Mill River Road
Hawthorne, NY 10532 Hawthorne, NY 10532
Phone: 1-914-784-7941 Phone: 1-914-784-7941
Email: leiba@watson.ibm.com Email: leiba@watson.ibm.com
This document will expire at the end of October 1999.
 End of changes. 31 change blocks. 
103 lines changed or deleted 113 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/