< draft-leiba-imap-implement-guide-09.txt   draft-leiba-imap-implement-guide-10.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-10.txt July 1999
Expires October 1999 Expires January 2000
IMAP4 Implementation Recommendations IMAP4 Implementation Recommendations
Status of this Document Status of this Document
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. Internet-Drafts are working all provisions of Section 10 of RFC2026. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas, documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups may also distribute and its working groups. Note that other groups may also distribute
working documents as Internet-Drafts. working documents as Internet-Drafts.
skipping to change at page 2, line 10 skipping to change at page 2, line 10
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.
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 words "must", "must not", "should", "should not", and "may" are
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this used with specific meaning in this document; since their meaning is
document are to be interpreted as described in [RFC-2119]. somewhat different from that specified in RFC 2119, we do not put
them in all caps here. Their meaning is as follows:
must -- This word means that the action described is necessary to ensure
interoperability. The recommendation should not be ignored.
must not -- This phrase means that the action described will be almost
certain to hurt interoperability. The recommendation should not
be ignored.
should -- This word means that the action described is strongly
recommended and will enhance interoperability or usability. The
recommendation should not be ignored without careful
consideration.
should not -- This phrase means that the action described is strongly
recommended against, and might hurt interoperability or
usability. The recommendation should not be ignored without
careful consideration.
may -- This word means that the action described is an acceptable
implementation choice. No specific recommendation is implied;
this word is used to point out a choice that might not be
obvious, or to let implementors know what choices have been made
by existing implementations.
3. Interoperability Issues and Recommendations 3. Interoperability Issues and Recommendations
3.1. Accessibility 3.1. Accessibility
This section describes the issues related to access to servers and This section describes the issues related to access to servers and
server resources. Concerns here include data sharing and maintenance server resources. Concerns here include data sharing and maintenance
of client/server connections. of client/server connections.
3.1.1. Multiple Accesses of the Same Mailbox 3.1.1. Multiple Accesses of the Same Mailbox
skipping to change at page 2, line 34 skipping to change at page 3, line 8
One strong point of IMAP4 is that, unlike POP3, it allows for One strong point of IMAP4 is that, unlike POP3, it allows for
multiple simultaneous access to a single mailbox. A user can, thus, multiple simultaneous access to a single mailbox. A user can, thus,
read mail from a client at home while the client in the office is read mail from a client at home while the client in the office is
still connected; or the help desk staff can all work out of the same still connected; or the help desk staff can all work out of the same
inbox, all seeing the same pool of questions. An important point inbox, all seeing the same pool of questions. An important point
about this capability, though is that NO SERVER IS GUARANTEED TO about this capability, though is that NO SERVER IS GUARANTEED TO
SUPPORT THIS. If you are selecting an IMAP server and this facility SUPPORT THIS. If you are selecting an IMAP server and this facility
is important to you, be sure that the server you choose to install, is important to you, be sure that the server you choose to install,
in the configuration you choose to use, supports it. in the configuration you choose to use, supports it.
If you are designing a client, you MUST NOT assume that you can If you are designing a client, you must not assume that you can
access the same mailbox more than once at a time. That means access the same mailbox more than once at a time. That means
1. you MUST handle gracefully the failure of a SELECT command if 1. you must handle gracefully the failure of a SELECT command if
the server refuses the second SELECT, the server refuses the second SELECT,
2. you MUST handle reasonably the severing of your connection (see 2. you must handle reasonably the severing of your connection (see
"Severed Connections", below) if the server chooses to allow the "Severed Connections", below) if the server chooses to allow the
second SELECT by forcing the first off, second SELECT by forcing the first off,
3. you MUST avoid making multiple connections to the same mailbox 3. you must avoid making multiple connections to the same mailbox
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
[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,
or the connection is severed by outside forces beyond the control of or the connection is severed by outside forces beyond the control of
the client and the server (a telephone line drops, for example). the client and the server (a telephone line drops, for example).
Clients and servers must both deal with these situations. Clients and servers must both deal with these situations.
When the client wants to sever a connection, it's usually because it When the client wants to sever a connection, it's usually because it
has finished the work it needed to do on that connection. The client has finished the work it needed to do on that connection. The client
SHOULD send a LOGOUT command, wait for the tagged response, and then should send a LOGOUT command, wait for the tagged response, and then
close the socket. But note that, while this is what's intended in close the socket. But note that, while this is what's intended in
the protocol design, there isn't universal agreement here. Some the protocol design, there isn't universal agreement here. Some
contend that sending the LOGOUT and waiting for the two responses contend that sending the LOGOUT and waiting for the two responses
(untagged BYE and tagged OK) is wasteful and unnecessary, and that (untagged BYE and tagged OK) is wasteful and unnecessary, and that
the client can simply close the socket. The server should interpret the client can simply close the socket. The server should interpret
the closed socket as a log out by the client. The counterargument is the closed socket as a log out by the client. The counterargument is
that it's useful from the standpoint of cleanup, problem that it's useful from the standpoint of cleanup, problem
determination, and the like, to have an explicit client log out, determination, and the like, to have an explicit client log out,
because otherwise there is no way for the server to tell the because otherwise there is no way for the server to tell the
difference between "closed socket because of log out" and "closed difference between "closed socket because of log out" and "closed
socket because communication was disrupted". If there is a socket because communication was disrupted". If there is a
client/server interaction problem, a client which routinely client/server interaction problem, a client which routinely
terminates a session by breaking the connection without a LOGOUT will terminates a session by breaking the connection without a LOGOUT will
make it much more difficult to determine the problem. make it much more difficult to determine the problem.
Because of this disagreement, server designers must be aware that Because of this disagreement, server designers must be aware that
some clients might close the socket without sending a LOGOUT. In any some clients might close the socket without sending a LOGOUT. In any
case, whether or not a LOGOUT was sent, the server SHOULD NOT case, whether or not a LOGOUT was sent, the server should not
implicitly expunge any messages from the selected mailbox. If a implicitly expunge any messages from the selected mailbox. If a
client wants the server to do so, it MUST send a CLOSE or EXPUNGE client wants the server to do so, it must send a CLOSE or EXPUNGE
command explicitly. command explicitly.
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]).
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'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
this. As specified in [RFC-2060], if such a timeout is done it MUST this. As specified in [RFC-2060], if such a timeout is done it must
NOT be until at least 30 minutes of inactivity. The reason for this not be until at least 30 minutes of inactivity. The reason for this
specification is to prevent clients from sending commands (such as specification is to prevent clients from sending commands (such as
NOOP) to the server at frequent intervals simply to avert a too-early NOOP) to the server at frequent intervals simply to avert a too-early
timeout. If the client knows that the server may not time out the timeout. If the client knows that the server may not time out the
session for at least 30 minutes, then the client need not poll at session for at least 30 minutes, then the client need not poll at
intervals more frequent than, say, 25 minutes. intervals more frequent than, say, 25 minutes.
3.2. Scaling 3.2. Scaling
IMAP4 has many features that allow for scalability, as mail stores IMAP4 has many features that allow for scalability, as mail stores
become larger and more numerous. Large numbers of users, mailboxes, become larger and more numerous. Large numbers of users, mailboxes,
skipping to change at page 5, line 18 skipping to change at page 5, line 34
and other such hierarchical mailbox structures, can be very numerous and other such hierarchical mailbox structures, can be very numerous
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
use an unqualified "*" that way in the LIST command. A safer use an unqualified "*" that way in the LIST command. A safer
approach is to list each level of hierarchy individually, allowing approach is to list each level of hierarchy individually, allowing
the user to traverse the tree one limb at a time, thus: the user to traverse the tree one limb at a time, thus:
C: 001 LIST "" % C: 001 LIST "" %
S: * LIST () "/" Banana S: * LIST () "/" Banana
S: * LIST ...etc... S: * LIST ...etc...
S: 001 OK done S: 001 OK done
and then and then
C: 002 LIST "" Banana/% C: 002 LIST "" Banana/%
skipping to change at page 5, line 35 skipping to change at page 6, line 4
S: * LIST ...etc... S: * LIST ...etc...
S: 001 OK done S: 001 OK done
and then and then
C: 002 LIST "" Banana/% C: 002 LIST "" Banana/%
S: * LIST () "/" Banana/Apple S: * LIST () "/" Banana/Apple
S: * LIST ...etc... S: * LIST ...etc...
S: 002 OK done S: 002 OK done
Using this technique the client's user interface can give the user Using this technique the client's user interface can give the user
full flexibility without choking on the voluminous reply to "LIST *". full flexibility without choking on the voluminous reply to "LIST *".
Of course, it is still possible that the reply to Of course, it is still possible that the reply to
C: 005 LIST "" alt.fan.celebrity.% C: 005 LIST "" alt.fan.celebrity.%
may be thousands of entries long, and there is, unfortunately, may be thousands of entries long, and there is, unfortunately,
nothing the client can do to protect itself from that. This has not nothing the client can do to protect itself from that. This has not
yet been a notable problem. yet been a notable problem.
Servers that may export circular hierarchies (any server that Servers that may export circular hierarchies (any server that
directly presents a UNIX file system, for instance) SHOULD limit the directly presents a UNIX file system, for instance) should limit the
hierarchy depth to prevent unlimited LIST responses. A suggested hierarchy depth to prevent unlimited LIST responses. A suggested
depth limit is 20 hierarchy levels. depth limit is 20 hierarchy levels.
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
skipping to change at page 6, line 47 skipping to change at page 7, line 23
... etc... ... etc...
If the server does not return an OK [UNSEEN] response, the client may If the server does not return an OK [UNSEEN] response, the client may
use SEARCH UNSEEN to obtain that value. use SEARCH UNSEEN to obtain that value.
This mechanism is good as a default presentation method, but only This mechanism is good as a default presentation method, but only
works well if the default message order is acceptable. A client may works well if the default message order is acceptable. A client may
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
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:
skipping to change at page 7, line 49 skipping to change at page 8, line 23
Some clients, rather than using FETCH BODYSTRUCTURE, use FETCH BODY[] Some clients, rather than using FETCH BODYSTRUCTURE, use FETCH BODY[]
(or the equivalent FETCH RFC822) to retrieve the entire message. (or the equivalent FETCH RFC822) to retrieve the entire message.
They then do the MIME parsing in the client. This may give the They then do the MIME parsing in the client. This may give the
client slightly more flexibility in some areas (access, for instance, client slightly more flexibility in some areas (access, for instance,
to header fields that aren't returned in the BODYSTRUCTURE and to header fields that aren't returned in the BODYSTRUCTURE and
ENVELOPE responses), but it can cause severe performance problems by ENVELOPE responses), but it can cause severe performance problems by
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
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
that's even longer. that's even longer.
A client SHOULD limit the length of the command lines it generates to A client should limit the length of the command lines it generates to
approximately 1000 octets (including all quoted strings but not approximately 1000 octets (including all quoted strings but not
including literals). If the client is unable to group things into including literals). If the client is unable to group things into
ranges so that the command line is within that length, it SHOULD ranges so that the command line is within that length, it should
split the request into multiple commands. The client SHOULD use split the request into multiple commands. The client should use
literals instead of long quoted strings, in order to keep the command literals instead of long quoted strings, in order to keep the command
length down. length down.
For its part, a server SHOULD allow for a command line of at least For its part, a server should allow for a command line of at least
8000 octets. This provides plenty of leeway for accepting reasonable 8000 octets. This provides plenty of leeway for accepting reasonable
length commands from clients. The server SHOULD send a BAD response length commands from clients. The server should send a BAD response
to a command that does not end within the server's maximum accepted to a command that does not end within the server's maximum accepted
command length. command length.
3.2.2. Subscriptions 3.2.2. Subscriptions
The client isn't the only entity that can get flooded: the end user, The client isn't the only entity that can get flooded: the end user,
too, may need some flood control. The IMAP4 protocol provides such too, may need some flood control. The IMAP4 protocol provides such
control in the form of subscriptions. Most servers support the control in the form of subscriptions. Most servers support the
SUBSCRIBE, UNSUBSCRIBE, and LSUB commands, and many users choose to SUBSCRIBE, UNSUBSCRIBE, and LSUB commands, and many users choose to
narrow down a large list of available mailboxes by subscribing to the narrow down a large list of available mailboxes by subscribing to the
ones that they usually want to see. Clients, with this in mind, ones that they usually want to see. Clients, with this in mind,
SHOULD give the user a way to see only subscribed mailboxes. A should give the user a way to see only subscribed mailboxes. A
client that never uses the LSUB command takes a significant usability client that never uses the LSUB command takes a significant usability
feature away from the user. Of course, the client would not want to feature away from the user. Of course, the client would not want to
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.
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
time-consuming). A smart server might use dynamic indexing to speed time-consuming). A smart server might use dynamic indexing to speed
commonly used text searches. commonly used text searches.
The client MAY allow other commands to be sent to the server while a The client may allow other commands to be sent to the server while a
SEARCH is in progress, but at the time of this writing there is SEARCH is in progress, but at the time of this writing there is
little or no server support for parallel processing of multiple little or no server support for parallel processing of multiple
commands in the same session (and see "Multiple Accesses of the Same commands in the same session (and see "Multiple Accesses of the Same
Mailbox" above for a description of the dangers of trying to work Mailbox" above for a description of the dangers of trying to work
around this by doing your SEARCH in another session). around this by doing your SEARCH in another session).
Another word about text searches: some servers, built on database Another word about text searches: some servers, built on database
back-ends with indexed search capabilities, may return search results back-ends with indexed search capabilities, may return search results
that do not match the IMAP spec's "case-insensitive substring" that do not match the IMAP spec's "case-insensitive substring"
requirements. While these servers are in violation of the protocol, requirements. While these servers are in violation of the protocol,
there is little harm in the violation as long as the search results there is little harm in the violation as long as the search results
are used only in response to a user's request. Still, developers of are used only in response to a user's request. Still, developers of
such servers should be aware that they ARE violating the protocol, such servers should be aware that they ARE violating the protocol,
should think carefully about that behaviour, and MUST be certain that should think carefully about that behaviour, and must be certain that
their servers respond accurately to the flag searches for the reasons their servers respond accurately to the flag searches for the reasons
outlined above. outlined above.
In addition, servers SHOULD support CHARSET UTF-8 [UTF-8] in In addition, servers should support CHARSET UTF-8 [UTF-8] in
searches. searches.
3.3 Avoiding Invalid Requests 3.3 Avoiding Invalid Requests
IMAP4 provides ways for a server to tell a client in advance what is IMAP4 provides ways for a server to tell a client in advance what is
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.
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
experimental extensions SHOULD do the same, and clients that take experimental extensions should do the same, and clients that take
advantage of them SHOULD use the CAPABILITY response to determine advantage of them should use the CAPABILITY response to determine
whether they may be used or not. whether they may be used or not.
3.3.2. Don't Do What the Server Says You Can't 3.3.2. Don't Do What the Server Says You Can't
In many cases, the server, in response to a command, will tell the In many cases, the server, in response to a command, will tell the
client something about what can and can't be done with a particular client something about what can and can't be done with a particular
mailbox. The client SHOULD pay attention to this information and mailbox. The client should pay attention to this information and
SHOULD NOT try to do things that it's been told it can't do. should not try to do things that it's been told it can't do.
Examples: Examples:
* Do not try to SELECT a mailbox that has the \Noselect flag set. * Do not try to SELECT a mailbox that has the \Noselect flag set.
* Do not try to CREATE a sub-mailbox in a mailbox that has the * Do not try to CREATE a sub-mailbox in a mailbox that has the
\Noinferiors flag set. \Noinferiors flag set.
* Do not respond to a failing COPY or APPEND command by trying to * Do not respond to a failing COPY or APPEND command by trying to
CREATE the target mailbox if the server does not respond with a CREATE the target mailbox if the server does not respond with a
[TRYCREATE] response code. [TRYCREATE] response code.
* Do not try to expunge a mailbox that has been selected with the * Do not try to expunge a mailbox that has been selected with the
[READ-ONLY] response code. [READ-ONLY] response code.
3.4. Miscellaneous Protocol Considerations 3.4. Miscellaneous Protocol Considerations
skipping to change at page 11, line 23 skipping to change at page 11, line 45
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
cause a problem with some client, so be sure to generate the correct cause a problem with some client, so be sure to generate the correct
string for this field. string for this field.
3.4.2. Special Characters 3.4.2. Special Characters
Certain characters, currently the double-quote and the backslash, may Certain characters, currently the double-quote and the backslash, may
not be sent as-is inside a quoted string. These characters MUST be not be sent as-is inside a quoted string. These characters must be
preceded by the escape character if they are in a quoted string, or preceded by the escape character if they are in a quoted string, or
else the string MUST be sent as a literal. Both clients and servers else the string must be sent as a literal. Both clients and servers
MUST handle this, both on output (they MUST send these characters must handle this, both on output (they must send these characters
properly) and on input (they MUST be able to receive escaped properly) and on input (they must be able to receive escaped
characters in quoted strings). Example: characters in quoted strings). Example:
C: 001 LIST "" % C: 001 LIST "" %
S: * LIST () "" INBOX S: * LIST () "" INBOX
S: * LIST () "\\" TEST S: * LIST () "\\" TEST
S: * LIST () "\\" {12} S: * LIST () "\\" {12}
S: "My" mailbox S: "My" mailbox
S: 001 OK done S: 001 OK done
C: 002 LIST "" "\"My\" mailbox\\%" C: 002 LIST "" "\"My\" mailbox\\%"
S: * LIST () "\\" {17} S: * LIST () "\\" {17}
skipping to change at page 12, line 5 skipping to change at page 12, line 29
containing imbedded double-quotes as a literal. The client used only containing imbedded double-quotes as a literal. The client used only
quoted strings, escaping both the backslash and the double-quote quoted strings, escaping both the backslash and the double-quote
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
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 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 restrict what a user may type in for a userid or a password. The
formal grammar specifies that these are "astrings", and an astring formal grammar specifies that these are "astrings", and an astring
can be a literal. A literal, in turn can contain any 8-bit 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 character, and clients must allow users to enter all 8-bit characters
here, and MUST pass them, unchanged, to the server (being careful to here, and must pass them, unchanged, to the server (being careful to
send them as literals when necessary). In particular, some server send them as literals when necessary). In particular, some server
configurations use "@" in user names, and some clients do not allow configurations use "@" in user names, and some clients do not allow
that character to be entered; this creates a severe interoperability that character to be entered; this creates a severe interoperability
problem. 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.
The server SHOULD maintain UIDs permanently for all messages if it The server should maintain UIDs permanently for all messages if it
can. If that's not possible, the server MUST change the UIDVALIDITY can. If that's not possible, the server must change the UIDVALIDITY
value for the mailbox whenever any of the UIDs may have become value for the mailbox whenever any of the UIDs may have become
invalid. Clients MUST recognize that the UIDVALIDITY has changed and invalid. Clients must recognize that the UIDVALIDITY has changed and
MUST respond to that condition by throwing away any information that must respond to that condition by throwing away any information that
they have saved about UIDs in that mailbox. There have been many they have saved about UIDs in that mailbox. There have been many
problems in this area when clients have failed to do this; in the problems in this area when clients have failed to do this; in the
worst case it will result in loss of mail when a client deletes the worst case it will result in loss of mail when a client deletes the
wrong piece of mail by using a stale UID. wrong piece of mail by using a stale UID.
It seems to be a common misunderstanding that "the UIDVALIDITY and It seems to be a common misunderstanding that "the UIDVALIDITY and
the UID, taken together, form a 64-bit identifier that uniquely the UID, taken together, form a 64-bit identifier that uniquely
identifies a message on a server". This is absolutely NOT TRUE. identifies a message on a server". This is absolutely NOT TRUE.
There is no assurance that the UIDVALIDITY values of two mailboxes be There is no assurance that the UIDVALIDITY values of two mailboxes be
different, so the UIDVALIDITY in no way identifies a mailbox. The different, so the UIDVALIDITY in no way identifies a mailbox. The
skipping to change at page 13, line 30 skipping to change at page 14, line 5
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
may have to invalidate UIDs while a mailbox is in use by a client - may have to invalidate UIDs while a mailbox is in use by a client -
that is, the UIDs that the client knows about in its active mailbox that is, the UIDs that the client knows about in its active mailbox
are no longer valid. In that case, the server MUST immediately are no longer valid. In that case, the server must immediately
change the UIDVALIDITY and MUST communicate this to the client. The change the UIDVALIDITY and must communicate this to the client. The
server MAY do this by sending an unsolicited UIDVALIDITY message, in server may do this by sending an unsolicited UIDVALIDITY message, in
the same form as in response to the SELECT command. Clients MUST be the same form as in response to the SELECT command. Clients must be
prepared to handle such a message and the possibly coincident failure prepared to handle such a message and the possibly coincident failure
of the command in process. For example: of the command in process. For example:
C: 032 UID STORE 382 +Flags.silent \Deleted C: 032 UID STORE 382 +Flags.silent \Deleted
S: * OK [UIDVALIDITY 12345] New UIDVALIDITY value! S: * OK [UIDVALIDITY 12345] New UIDVALIDITY value!
S: 032 NO UID command rejected because UIDVALIDITY changed! S: 032 NO UID command rejected because UIDVALIDITY changed!
C: ...invalidates local information and re-fetches... C: ...invalidates local information and re-fetches...
C: 033 FETCH 1:* UID C: 033 FETCH 1:* UID
...etc... ...etc...
skipping to change at page 14, line 10 skipping to change at page 14, line 34
is delivered to the user, which creates the real INBOX file and is delivered to the user, which creates the real INBOX file and
assigns a permanent UIDVALIDITY (that is likely not to be 1). The assigns a permanent UIDVALIDITY (that is likely not to be 1). The
server reports the change of UIDVALIDITY, but as there were no server reports the change of UIDVALIDITY, but as there were no
messages before, so no UIDs have actually changed, all the client messages before, so no UIDs have actually changed, all the client
must do is accept the change in UIDVALIDITY. must do is accept the change in UIDVALIDITY.
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.
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:
C: 001 FETCH 1 UID FLAGS INTERNALDATE C: 001 FETCH 1 UID FLAGS INTERNALDATE
S: * 5 FETCH (FLAGS (\Deleted)) S: * 5 FETCH (FLAGS (\Deleted))
S: * 1 FETCH (FLAGS (\Seen) INTERNALDATE "..." UID 345) S: * 1 FETCH (FLAGS (\Seen) INTERNALDATE "..." UID 345)
S: 001 OK done S: 001 OK done
(In this case, the responses are in a different order. Also, the (In this case, the responses are in a different order. Also, the
server returned a flag update for message 5, which wasn't part of the server returned a flag update for message 5, which wasn't part of the
skipping to change at page 14, line 50 skipping to change at page 15, line 29
returned in separate responses.) returned in separate responses.)
C: 003 FETCH 2 BODY[1] C: 003 FETCH 2 BODY[1]
S: * 2 FETCH (FLAGS (\Seen) BODY[1] {14} S: * 2 FETCH (FLAGS (\Seen) BODY[1] {14}
S: Hello world! S: Hello world!
S: ) S: )
S: 003 OK done S: 003 OK done
(In this case, the FLAGS response was added by the server, since (In this case, the FLAGS response was added by the server, since
fetching the body part caused the server to set the \Seen flag.) fetching the body part caused the server to set the \Seen flag.)
Because of this characteristic a client MUST be ready to receive any Because of this characteristic a client must be ready to receive any
FETCH response at any time and should use that information to update FETCH response at any time and should use that information to update
its local information about the message to which the FETCH response its local information about the message to which the FETCH response
refers. A client MUST NOT assume that any FETCH responses will come refers. A client must not assume that any FETCH responses will come
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
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
client to display an approximate size to the user and to use the client to display an approximate size to the user and to use the
estimate in flood control considerations (q.v.), but requires that estimate in flood control considerations (q.v.), but requires that
the client not use the size for things such as allocation of buffers, the client not use the size for things such as allocation of buffers,
because those buffers might then be too small to hold the actual MIME because those buffers might then be too small to hold the actual MIME
stream. Instead, a client SHOULD use the size that's returned in the stream. Instead, a client should use the size that's returned in the
literal when you fetch the data. literal when you fetch the data.
The protocol requires that the RFC822.SIZE value returned by the The protocol requires that the RFC822.SIZE value returned by the
server be EXACT. Estimating the size is a protocol violation, and server be EXACT. Estimating the size is a protocol violation, and
server designers must be aware that, despite the performance savings server designers must be aware that, despite the performance savings
they might realize in using an estimate, this practice will cause they might realize in using an estimate, this practice will cause
some clients to fail in various ways. If possible, the server SHOULD some clients to fail in various ways. If possible, the server should
compute the RFC822.SIZE for a particular message once, and then save compute the RFC822.SIZE for a particular message once, and then save
it for later retrieval. If that's not possible, the server MUST it for later retrieval. If that's not possible, the server must
compute the value exactly every time. Incorrect estimates do cause compute the value exactly every time. Incorrect estimates do cause
severe interoperability problems with some clients. severe interoperability problems with some clients.
3.4.6. Expunged Messages 3.4.6. Expunged Messages
If the server allows multiple connections to the same mailbox, it is If the server allows multiple connections to the same mailbox, it is
often possible for messages to be expunged in one client unbeknownst often possible for messages to be expunged in one client unbeknownst
to another client. Since the server is not allowed to tell the to another client. Since the server is not allowed to tell the
client about these expunged messages in response to a FETCH command, client about these expunged messages in response to a FETCH command,
the server may have to deal with the issue of how to return the server may have to deal with the issue of how to return
skipping to change at page 16, line 16 skipping to change at page 16, line 41
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
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 16, line 44 skipping to change at page 17, line 24
interoperability problems with this practice: interoperability problems with this practice:
1. different clients may use different names for mailboxes with 1. different clients may use different names for mailboxes with
similar functions (such as "Trash" and "Deleted"), or may manage the similar functions (such as "Trash" and "Deleted"), or may manage the
same mailboxes in different ways, causing problems if a user switches same mailboxes in different ways, causing problems if a user switches
between clients and between clients and
2. there is no guarantee that the server will allow the creation of 2. there is no guarantee that the server will allow the creation of
the desired mailbox. the desired mailbox.
The client developer is, therefore, well advised to consider The client developer is, therefore, well advised to consider
carefully the creation of any special-use mailboxes on the server, carefully the creation of any special-use mailboxes on the server,
and, further, the client MUST NOT require such mailbox creation - and, further, the client must not require such mailbox creation -
that is, if you do decide to do this, you MUST handle gracefully the that is, if you do decide to do this, you must handle gracefully the
failure of the CREATE command and behave reasonably when your failure of the CREATE command and behave reasonably when your
special-use mailboxes do not exist and can not be created. special-use mailboxes do not exist and can not be created.
In addition, the client developer SHOULD provide a convenient way for In addition, the client developer should provide a convenient way for
the user to select the names for any special-use mailboxes, allowing the user to select the names for any special-use mailboxes, allowing
the user to make these names the same in all clients used and to put the user to make these names the same in all clients used and to put
them where the user wants them. them where the user wants them.
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
skipping to change at page 17, line 37 skipping to change at page 18, line 15
only to the user's personal mailboxes, or to some other limited set only to the user's personal mailboxes, or to some other limited set
of files, making such file-system-like semantics less meaningful. of files, making such file-system-like semantics less meaningful.
Third, because the IMAP spec leaves the interpretation of the Third, because the IMAP spec leaves the interpretation of the
reference name as "implementation-dependent", in the past the various reference name as "implementation-dependent", in the past the various
server implementations handled it in vastly differing ways. server implementations handled it in vastly differing ways.
The following recommendations are the result of significant The following recommendations are the result of significant
operational experience, and are intended to maximize operational experience, and are intended to maximize
interoperability. interoperability.
Server implementations MUST implement the reference argument in a way Server implementations must implement the reference argument in a way
that matches the intended "change directory" operation as closely as that matches the intended "change directory" operation as closely as
possible. As a minimum implementation, the reference argument may be possible. As a minimum implementation, the reference argument may be
prepended to the mailbox name (while suppressing double delimiters; prepended to the mailbox name (while suppressing double delimiters;
see the next paragraph). Even servers that do not provide a way to see the next paragraph). Even servers that do not provide a way to
break out of the current hierarchy (see "breakout facility" below) break out of the current hierarchy (see "breakout facility" below)
MUST provide a reasonable implementation of the reference argument, must provide a reasonable implementation of the reference argument,
as described here, so that they will interoperate with clients that as described here, so that they will interoperate with clients that
use it. use it.
Server implementations that prepend the reference argument to the Server implementations that prepend the reference argument to the
mailbox name SHOULD insert a hierarchy delimiter between them, and mailbox name should insert a hierarchy delimiter between them, and
MUST NOT insert a second if one is already present: must not insert a second if one is already present:
C: A001 LIST ABC DEF C: A001 LIST ABC DEF
S: * LIST () "/" ABC/DEF <=== SHOULD do this S: * LIST () "/" ABC/DEF <=== should do this
S: A001 OK done S: A001 OK done
C: A002 LIST ABC/ /DEF C: A002 LIST ABC/ /DEF
S: * LIST () "/" ABC//DEF <=== MUST NOT do this S: * LIST () "/" ABC//DEF <=== must not do this
S: A002 OK done S: A002 OK done
On clients, the reference argument is chiefly used to implement a On clients, the reference argument is chiefly used to implement a
"breakout facility", wherein the user may directly access a mailbox "breakout facility", wherein the user may directly access a mailbox
outside the "current directory" hierarchy. Client implementations outside the "current directory" hierarchy. Client implementations
SHOULD have an operational mode that does not use the reference should have an operational mode that does not use the reference
argument. This is to interoperate with older servers that did not argument. This is to interoperate with older servers that did not
implement the reference argument properly. While it's a good idea to implement the reference argument properly. While it's a good idea to
give the user access to a breakout facility, clients that do not give the user access to a breakout facility, clients that do not
intend to do so SHOULD NOT use the reference argument at all. intend to do so should not use the reference argument at all.
Client implementations SHOULD always place a trailing hierarchy Client implementations should always place a trailing hierarchy
delimiter on the reference argument. This is because some servers delimiter on the reference argument. This is because some servers
prepend the reference argument to the mailbox name without inserting prepend the reference argument to the mailbox name without inserting
a hierarchy delimiter, while others do insert a hierarchy delimiter a hierarchy delimiter, while others do insert a hierarchy delimiter
if one is not already present. A client that puts the delimiter in if one is not already present. A client that puts the delimiter in
will work with both varieties of server. will work with both varieties of server.
Client implementations that implement a breakout facility SHOULD Client implementations that implement a breakout facility should
allow the user to choose whether or not to use a leading hierarchy 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 delimiter on the mailbox argument. This is because the handling of a
leading mailbox hierarchy delimiter also varies from server to leading mailbox hierarchy delimiter also varies from server to
server, and even between different mailstores on the same server. In server, and even between different mailstores on the same server. In
some cases, a leading hierarchy delimiter means "discard the some cases, a leading hierarchy delimiter means "discard the
reference argument" (implementing the intended breakout facility), reference argument" (implementing the intended breakout facility),
thus: thus:
C: A001 LIST ABC/ /DEF C: A001 LIST ABC/ /DEF
S: * LIST () "/" /DEF S: * LIST () "/" /DEF
S: A001 OK done S: A001 OK done
In other cases, however, the two are catenated and the extra In other cases, however, the two are catenated and the extra
hierarchy delimiter is discarded, thus: hierarchy delimiter is discarded, thus:
C: A001 LIST ABC/ /DEF C: A001 LIST ABC/ /DEF
S: * LIST () "/" ABC/DEF S: * LIST () "/" ABC/DEF
S: A001 OK done S: A001 OK done
Client implementations MUST NOT assume that the server supports a Client implementations must not assume that the server supports a
breakout facility, but MAY provide a way for the user to use one if 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 it is available. Any breakout facility should be exported to the
user interface. Note that there may be other "breakout" characters user interface. Note that there may be other "breakout" characters
besides the hierarchy delimiter (for instance, UNIX filesystem besides the hierarchy delimiter (for instance, UNIX filesystem
servers are likely to use a leading "~" as well), and that their servers are likely to use a leading "~" as well), and that their
interpretation is server-dependent. 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
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
as of the effect on URLs and other external specifications (since as of the effect on URLs and other external specifications (since
some of these characters have special meanings there). Also, a some of these characters have special meanings there). Also, a
server that uses "\" (and clients of such a server) MUST remember to server that uses "\" (and clients of such a server) must remember to
escape that character in quoted strings or to send literals instead. escape that character in quoted strings or to send literals instead.
Literals are recommended over escaped characters in quoted strings in Literals are recommended over escaped characters in quoted strings in
order to maintain compatibility with older IMAP versions that did not order to maintain compatibility with older IMAP versions that did not
allow escaped characters in quoted strings (but check the grammar to allow escaped characters in quoted strings (but check the grammar to
see where literals are allowed): see where literals are allowed):
C: 001 LIST "" {13} C: 001 LIST "" {13}
S: + send literal S: + send literal
C: this\%\%\%\h* C: this\%\%\%\h*
S: * LIST () "\\" {27} S: * LIST () "\\" {27}
S: this\is\a\mailbox\hierarchy S: this\is\a\mailbox\hierarchy
S: 001 OK LIST complete S: 001 OK LIST complete
In any case, a server SHOULD NOT use normal alpha-numeric characters In any case, a server should not use normal alpha-numeric characters
(such as "X" or "0") as delimiters; a user would be very surprised to (such as "X" or "0") as delimiters; a user would be very surprised to
find that "EXPENDITURES" actually represented a two-level hierarchy. find that "EXPENDITURES" actually represented a two-level hierarchy.
And a server SHOULD NOT use characters that are non-printable or And a server should not use characters that are non-printable or
difficult or impossible to enter on a standard US keyboard. Control difficult or impossible to enter on a standard US keyboard. Control
characters, box-drawing characters, and characters from non-US characters, box-drawing characters, and characters from non-US
alphabets fit into this category. Their use presents alphabets fit into this category. Their use presents
interoperability problems that are best avoided. interoperability problems that are best avoided.
The UTF-7 encoding of mailbox names also raises questions about what The UTF-7 encoding of mailbox names also raises questions about what
to do with the hierarchy delimiters in encoded names: do we encode to do with the hierarchy delimiters in encoded names: do we encode
each hierarchy level and separate them with delimiters, or do we each hierarchy level and separate them with delimiters, or do we
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.
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.
3.4.12. Deleting Mailboxes 3.4.12. Deleting Mailboxes
The protocol does not guarantee that a client may delete a mailbox The protocol does not guarantee that a client may delete a mailbox
that is not empty, though on some servers it is permissible and is, that is not empty, though on some servers it is permissible and is,
in fact, much faster than the alternative or deleting all the in fact, much faster than the alternative or deleting all the
messages from the client. If the client chooses to try to take messages from the client. If the client chooses to try to take
advantage of this possibility it MUST be prepared to use the other advantage of this possibility it must be prepared to use the other
method in the even that the more convenient one fails. Further, a method in the even that the more convenient one fails. Further, a
client SHOULD NOT try to delete the mailbox that it has selected, but client should not try to delete the mailbox that it has selected, but
should first close that mailbox; some servers do not permit the should first close that mailbox; some servers do not permit the
deletion of the selected mailbox. deletion of the selected mailbox.
That said, a server SHOULD permit the deletion of a non-empty That said, a server should permit the deletion of a non-empty
mailbox; there's little reason to pass this work on to the client. mailbox; there's little reason to pass this work on to the client.
Moreover, forbidding this prevents the deletion of a mailbox that for Moreover, forbidding this prevents the deletion of a mailbox that for
some reason can not be opened or expunged, leading to possible some reason can not be opened or expunged, leading to possible
denial-of-service problems. denial-of-service problems.
Example: Example:
[User tells the client to delete mailbox BANANA, which is [User tells the client to delete mailbox BANANA, which is
currently selected...] currently selected...]
C: 008 CLOSE C: 008 CLOSE
S: 008 OK done S: 008 OK done
skipping to change at page 22, line 37 skipping to change at page 23, line 15
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. This document will expire at the end of January 2000.
 End of changes. 80 change blocks. 
98 lines changed or deleted 121 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/