1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/rfc/rfc2683.txt	Mon Sep 14 15:17:45 2009 +0900
     1.3 @@ -0,0 +1,1291 @@
     1.4 +
     1.5 +
     1.6 +
     1.7 +
     1.8 +
     1.9 +
    1.10 +Network Working Group                                           B. Leiba
    1.11 +Request for Comments: 2683               IBM T.J. Watson Research Center
    1.12 +Category: Informational                                   September 1999
    1.13 +
    1.14 +
    1.15 +                  IMAP4 Implementation Recommendations
    1.16 +
    1.17 +Status of this Memo
    1.18 +
    1.19 +   This memo provides information for the Internet community.  It does
    1.20 +   not specify an Internet standard of any kind.  Distribution of this
    1.21 +   memo is unlimited.
    1.22 +
    1.23 +Copyright Notice
    1.24 +
    1.25 +   Copyright (C) The Internet Society (1999).  All Rights Reserved.
    1.26 +
    1.27 +1. Abstract
    1.28 +
    1.29 +   The IMAP4 specification [RFC-2060] describes a rich protocol for use
    1.30 +   in building clients and servers for storage, retrieval, and
    1.31 +   manipulation of electronic mail.  Because the protocol is so rich and
    1.32 +   has so many implementation choices, there are often trade-offs that
    1.33 +   must be made and issues that must be considered when designing such
    1.34 +   clients and servers.  This document attempts to outline these issues
    1.35 +   and to make recommendations in order to make the end products as
    1.36 +   interoperable as possible.
    1.37 +
    1.38 +2. Conventions used in this document
    1.39 +
    1.40 +   In examples, "C:" indicates lines sent by a client that is connected
    1.41 +   to a server.  "S:" indicates lines sent by the server to the client.
    1.42 +
    1.43 +   The words "must", "must not", "should", "should not", and "may" are
    1.44 +   used with specific meaning in this document; since their meaning is
    1.45 +   somewhat different from that specified in RFC 2119, we do not put
    1.46 +   them in all caps here.  Their meaning is as follows:
    1.47 +
    1.48 +   must --       This word means that the action described is necessary
    1.49 +                 to ensure interoperability.  The recommendation should
    1.50 +                 not be ignored.
    1.51 +   must not --   This phrase means that the action described will be
    1.52 +                 almost certain to hurt interoperability.  The
    1.53 +                 recommendation should not be ignored.
    1.54 +
    1.55 +
    1.56 +
    1.57 +
    1.58 +
    1.59 +
    1.60 +
    1.61 +Leiba                        Informational                      [Page 1]
    1.62 +
    1.63 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
    1.64 +
    1.65 +
    1.66 +   should --     This word means that the action described is strongly
    1.67 +                 recommended and will enhance interoperability or
    1.68 +                 usability.  The recommendation should not be ignored
    1.69 +                 without careful consideration.
    1.70 +   should not -- This phrase means that the action described is strongly
    1.71 +                 recommended against, and might hurt interoperability or
    1.72 +                 usability.  The recommendation should not be ignored
    1.73 +                 without careful consideration.
    1.74 +   may --        This word means that the action described is an
    1.75 +                 acceptable implementation choice.  No specific
    1.76 +                 recommendation is implied; this word is used to point
    1.77 +                 out a choice that might not be obvious, or to let
    1.78 +                 implementors know what choices have been made by
    1.79 +                 existing implementations.
    1.80 +
    1.81 +3. Interoperability Issues and Recommendations
    1.82 +
    1.83 +3.1.   Accessibility
    1.84 +
    1.85 +   This section describes the issues related to access to servers and
    1.86 +   server resources.  Concerns here include data sharing and maintenance
    1.87 +   of client/server connections.
    1.88 +
    1.89 +3.1.1. Multiple Accesses of the Same Mailbox
    1.90 +
    1.91 +   One strong point of IMAP4 is that, unlike POP3, it allows for
    1.92 +   multiple simultaneous access to a single mailbox.  A user can, thus,
    1.93 +   read mail from a client at home while the client in the office is
    1.94 +   still connected; or the help desk staff can all work out of the same
    1.95 +   inbox, all seeing the same pool of questions.  An important point
    1.96 +   about this capability, though is that NO SERVER IS GUARANTEED TO
    1.97 +   SUPPORT THIS.  If you are selecting an IMAP server and this facility
    1.98 +   is important to you, be sure that the server you choose to install,
    1.99 +   in the configuration you choose to use, supports it.
   1.100 +
   1.101 +   If you are designing a client, you must not assume that you can
   1.102 +   access the same mailbox more than once at a time.  That means
   1.103 +
   1.104 +   1. you must handle gracefully the failure of a SELECT command if the
   1.105 +      server refuses the second SELECT,
   1.106 +   2. you must handle reasonably the severing of your connection (see
   1.107 +      "Severed Connections", below) if the server chooses to allow the
   1.108 +      second SELECT by forcing the first off,
   1.109 +   3. you must avoid making multiple connections to the same mailbox in
   1.110 +      your own client (for load balancing or other such reasons), and
   1.111 +   4. you must avoid using the STATUS command on a mailbox that you have
   1.112 +      selected (with some server implementations the STATUS command has
   1.113 +      the same problems with multiple access as do the SELECT and
   1.114 +
   1.115 +
   1.116 +
   1.117 +Leiba                        Informational                      [Page 2]
   1.118 +
   1.119 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.120 +
   1.121 +
   1.122 +      EXAMINE commands).
   1.123 +
   1.124 +   A further note about STATUS: The STATUS command is sometimes used to
   1.125 +   check a non-selected mailbox for new mail.  This mechanism must not
   1.126 +   be used to check for new mail in the selected mailbox; section 5.2 of
   1.127 +   [RFC-2060] specifically forbids this in its last paragraph.  Further,
   1.128 +   since STATUS takes a mailbox name it is an independent operation, not
   1.129 +   operating on the selected mailbox.  Because of this, the information
   1.130 +   it returns is not necessarily in synchronization with the selected
   1.131 +   mailbox state.
   1.132 +
   1.133 +3.1.2. Severed Connections
   1.134 +
   1.135 +   The client/server connection may be severed for one of three reasons:
   1.136 +   the client severs the connection, the server severs the connection,
   1.137 +   or the connection is severed by outside forces beyond the control of
   1.138 +   the client and the server (a telephone line drops, for example).
   1.139 +   Clients and servers must both deal with these situations.
   1.140 +
   1.141 +   When the client wants to sever a connection, it's usually because it
   1.142 +   has finished the work it needed to do on that connection.  The client
   1.143 +   should send a LOGOUT command, wait for the tagged response, and then
   1.144 +   close the socket.  But note that, while this is what's intended in
   1.145 +   the protocol design, there isn't universal agreement here.  Some
   1.146 +   contend that sending the LOGOUT and waiting for the two responses
   1.147 +   (untagged BYE and tagged OK) is wasteful and unnecessary, and that
   1.148 +   the client can simply close the socket.  The server should interpret
   1.149 +   the closed socket as a log out by the client.  The counterargument is
   1.150 +   that it's useful from the standpoint of cleanup, problem
   1.151 +   determination, and the like, to have an explicit client log out,
   1.152 +   because otherwise there is no way for the server to tell the
   1.153 +   difference between "closed socket because of log out" and "closed
   1.154 +   socket because communication was disrupted".  If there is a
   1.155 +   client/server interaction problem, a client which routinely
   1.156 +   terminates a session by breaking the connection without a LOGOUT will
   1.157 +   make it much more difficult to determine the problem.
   1.158 +
   1.159 +   Because of this disagreement, server designers must be aware that
   1.160 +   some clients might close the socket without sending a LOGOUT.  In any
   1.161 +   case, whether or not a LOGOUT was sent, the server should not
   1.162 +   implicitly expunge any messages from the selected mailbox.  If a
   1.163 +   client wants the server to do so, it must send a CLOSE or EXPUNGE
   1.164 +   command explicitly.
   1.165 +
   1.166 +   When the server wants to sever a connection it's usually due to an
   1.167 +   inactivity timeout or is because a situation has arisen that has
   1.168 +   changed the state of the mail store in a way that the server can not
   1.169 +   communicate to the client.  The server should send an untagged BYE
   1.170 +
   1.171 +
   1.172 +
   1.173 +Leiba                        Informational                      [Page 3]
   1.174 +
   1.175 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.176 +
   1.177 +
   1.178 +   response to the client and then close the socket.  Sending an
   1.179 +   untagged BYE response before severing allows the server to send a
   1.180 +   human-readable explanation of the problem to the client, which the
   1.181 +   client may then log, display to the user, or both (see section 7.1.5
   1.182 +   of [RFC-2060]).
   1.183 +
   1.184 +   Regarding inactivity timeouts, there is some controversy.  Unlike
   1.185 +   POP, for which the design is for a client to connect, retrieve mail,
   1.186 +   and log out, IMAP's design encourages long-lived (and mostly
   1.187 +   inactive) client/server sessions.  As the number of users grows, this
   1.188 +   can use up a lot of server resources, especially with clients that
   1.189 +   are designed to maintain sessions for mailboxes that the user has
   1.190 +   finished accessing.  To alleviate this, a server may implement an
   1.191 +   inactivity timeout, unilaterally closing a session (after first
   1.192 +   sending an untagged BYE, as noted above).  Some server operators have
   1.193 +   reported dramatic improvements in server performance after doing
   1.194 +   this.  As specified in [RFC-2060], if such a timeout is done it must
   1.195 +   not be until at least 30 minutes of inactivity.  The reason for this
   1.196 +   specification is to prevent clients from sending commands (such as
   1.197 +   NOOP) to the server at frequent intervals simply to avert a too-early
   1.198 +   timeout.  If the client knows that the server may not time out the
   1.199 +   session for at least 30 minutes, then the client need not poll at
   1.200 +   intervals more frequent than, say, 25 minutes.
   1.201 +
   1.202 +3.2.   Scaling
   1.203 +
   1.204 +   IMAP4 has many features that allow for scalability, as mail stores
   1.205 +   become larger and more numerous.  Large numbers of users, mailboxes,
   1.206 +   and messages, and very large messages require thought to handle
   1.207 +   efficiently.  This document will not address the administrative
   1.208 +   issues involved in large numbers of users, but we will look at the
   1.209 +   other items.
   1.210 +
   1.211 +3.2.1. Flood Control
   1.212 +
   1.213 +   There are three situations when a client can make a request that will
   1.214 +   result in a very large response - too large for the client reasonably
   1.215 +   to deal with: there are a great many mailboxes available, there are a
   1.216 +   great many messages in the selected mailbox, or there is a very large
   1.217 +   message part.  The danger here is that the end user will be stuck
   1.218 +   waiting while the server sends (and the client processes) an enormous
   1.219 +   response.  In all of these cases there are things a client can do to
   1.220 +   reduce that danger.
   1.221 +
   1.222 +   There is also the case where a client can flood a server, by sending
   1.223 +   an arbitratily long command.  We'll discuss that issue, too, in this
   1.224 +   section.
   1.225 +
   1.226 +
   1.227 +
   1.228 +
   1.229 +Leiba                        Informational                      [Page 4]
   1.230 +
   1.231 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.232 +
   1.233 +
   1.234 +3.2.1.1.  Listing Mailboxes
   1.235 +
   1.236 +   Some servers present Usenet newsgroups to IMAP users.  Newsgroups,
   1.237 +   and other such hierarchical mailbox structures, can be very numerous
   1.238 +   but may have only a few entries at the top level of hierarchy.  Also,
   1.239 +   some servers are built against mail stores that can, unbeknownst to
   1.240 +   the server, have circular hierarchies - that is, it's possible for
   1.241 +   "a/b/c/d" to resolve to the same file structure as "a", which would
   1.242 +   then mean that "a/b/c/d/b" is the same as "a/b", and the hierarchy
   1.243 +   will never end.  The LIST response in this case will be unlimited.
   1.244 +
   1.245 +   Clients that will have trouble with this are those that use
   1.246 +
   1.247 +       C: 001 LIST "" *
   1.248 +
   1.249 +   to determine the mailbox list.  Because of this, clients should not
   1.250 +   use an unqualified "*" that way in the LIST command.  A safer
   1.251 +   approach is to list each level of hierarchy individually, allowing
   1.252 +   the user to traverse the tree one limb at a time, thus:
   1.253 +
   1.254 +       C: 001 LIST "" %
   1.255 +       S: * LIST () "/" Banana
   1.256 +       S: * LIST ...etc...
   1.257 +       S: 001 OK done
   1.258 +
   1.259 +   and then
   1.260 +
   1.261 +       C: 002 LIST "" Banana/%
   1.262 +       S: * LIST () "/" Banana/Apple
   1.263 +       S: * LIST ...etc...
   1.264 +       S: 002 OK done
   1.265 +
   1.266 +   Using this technique the client's user interface can give the user
   1.267 +   full flexibility without choking on the voluminous reply to "LIST *".
   1.268 +
   1.269 +   Of course, it is still possible that the reply to
   1.270 +
   1.271 +       C: 005 LIST "" alt.fan.celebrity.%
   1.272 +
   1.273 +   may be thousands of entries long, and there is, unfortunately,
   1.274 +   nothing the client can do to protect itself from that.  This has not
   1.275 +   yet been a notable problem.
   1.276 +
   1.277 +   Servers that may export circular hierarchies (any server that
   1.278 +   directly presents a UNIX file system, for instance) should limit the
   1.279 +   hierarchy depth to prevent unlimited LIST responses.  A suggested
   1.280 +   depth limit is 20 hierarchy levels.
   1.281 +
   1.282 +
   1.283 +
   1.284 +
   1.285 +Leiba                        Informational                      [Page 5]
   1.286 +
   1.287 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.288 +
   1.289 +
   1.290 +3.2.1.2.  Fetching the List of Messages
   1.291 +
   1.292 +   When a client selects a mailbox, it is given a count, in the untagged
   1.293 +   EXISTS response, of the messages in the mailbox.  This number can be
   1.294 +   very large.  In such a case it might be unwise to use
   1.295 +
   1.296 +       C: 004 FETCH 1:* ALL
   1.297 +
   1.298 +   to populate the user's view of the mailbox.  One good method to avoid
   1.299 +   problems with this is to batch the requests, thus:
   1.300 +
   1.301 +       C: 004 FETCH 1:50 ALL
   1.302 +       S: * 1 FETCH ...etc...
   1.303 +       S: 004 OK done
   1.304 +       C: 005 FETCH 51:100 ALL
   1.305 +       S: * 51 FETCH ...etc...
   1.306 +       S: 005 OK done
   1.307 +       C: 006 FETCH 101:150 ALL
   1.308 +       ...etc...
   1.309 +
   1.310 +   Using this method, another command, such as "FETCH 6 BODY[1]" can be
   1.311 +   inserted as necessary, and the client will not have its access to the
   1.312 +   server blocked by a storm of FETCH replies.  (Such a method could be
   1.313 +   reversed to fetch the LAST 50 messages first, then the 50 prior to
   1.314 +   that, and so on.)
   1.315 +
   1.316 +   As a smart extension of this, a well designed client, prepared for
   1.317 +   very large mailboxes, will not automatically fetch data for all
   1.318 +   messages AT ALL.  Rather, the client will populate the user's view
   1.319 +   only as the user sees it, possibly pre-fetching selected information,
   1.320 +   and only fetching other information as the user scrolls to it.  For
   1.321 +   example, to select only those messages beginning with the first
   1.322 +   unseen one:
   1.323 +
   1.324 +       C: 003 SELECT INBOX
   1.325 +       S: * 10000 EXISTS
   1.326 +       S: * 80 RECENT
   1.327 +       S: * FLAGS (\Answered \Flagged \Deleted \Draft \Seen)
   1.328 +       S: * OK [UIDVALIDITY 824708485] UID validity status
   1.329 +       S: * OK [UNSEEN 9921] First unseen message
   1.330 +       S: 003 OK [READ-WRITE] SELECT completed
   1.331 +       C: 004 FETCH 9921:* ALL
   1.332 +       ... etc...
   1.333 +
   1.334 +   If the server does not return an OK [UNSEEN] response, the client may
   1.335 +   use SEARCH UNSEEN to obtain that value.
   1.336 +
   1.337 +
   1.338 +
   1.339 +
   1.340 +
   1.341 +Leiba                        Informational                      [Page 6]
   1.342 +
   1.343 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.344 +
   1.345 +
   1.346 +   This mechanism is good as a default presentation method, but only
   1.347 +   works well if the default message order is acceptable.  A client may
   1.348 +   want to present various sort orders to the user (by subject, by date
   1.349 +   sent, by sender, and so on) and in that case (lacking a SORT
   1.350 +   extension on the server side) the client WILL have to retrieve all
   1.351 +   message descriptors.  A client that provides this service should not
   1.352 +   do it by default and should inform the user of the costs of choosing
   1.353 +   this option for large mailboxes.
   1.354 +
   1.355 +3.2.1.3.  Fetching a Large Body Part
   1.356 +
   1.357 +   The issue here is similar to the one for a list of messages.  In the
   1.358 +   BODYSTRUCTURE response the client knows the size, in bytes, of the
   1.359 +   body part it plans to fetch.  Suppose this is a 70 MB video clip. The
   1.360 +   client can use partial fetches to retrieve the body part in pieces,
   1.361 +   avoiding the problem of an uninterruptible 70 MB literal coming back
   1.362 +   from the server:
   1.363 +
   1.364 +       C: 022 FETCH 3 BODY[1]<0.20000>
   1.365 +       S: * 3 FETCH (FLAGS(\Seen) BODY[1]<0> {20000}
   1.366 +       S: ...data...)
   1.367 +       S: 022 OK done
   1.368 +       C: 023 FETCH 3 BODY[1]<20001.20000>
   1.369 +       S: * 3 FETCH (BODY[1]<20001> {20000}
   1.370 +       S: ...data...)
   1.371 +       S: 023 OK done
   1.372 +       C: 024 FETCH 3 BODY[1]<40001.20000>
   1.373 +       ...etc...
   1.374 +
   1.375 +3.2.1.4.  BODYSTRUCTURE vs. Entire Messages
   1.376 +
   1.377 +   Because FETCH BODYSTRUCTURE is necessary in order to determine the
   1.378 +   number of body parts, and, thus, whether a message has "attachments",
   1.379 +   clients often use FETCH FULL as their normal method of populating the
   1.380 +   user's view of a mailbox.  The benefit is that the client can display
   1.381 +   a paperclip icon or some such indication along with the normal
   1.382 +   message summary.  However, this comes at a significant cost with some
   1.383 +   server configurations.  The parsing needed to generate the FETCH
   1.384 +   BODYSTRUCTURE response may be time-consuming compared with that
   1.385 +   needed for FETCH ENVELOPE.  The client developer should consider this
   1.386 +   issue when deciding whether the ability to add a paperclip icon is
   1.387 +   worth the tradeoff in performance, especially with large mailboxes.
   1.388 +
   1.389 +   Some clients, rather than using FETCH BODYSTRUCTURE, use FETCH BODY[]
   1.390 +   (or the equivalent FETCH RFC822) to retrieve the entire message.
   1.391 +   They then do the MIME parsing in the client.  This may give the
   1.392 +   client slightly more flexibility in some areas (access, for instance,
   1.393 +   to header fields that aren't returned in the BODYSTRUCTURE and
   1.394 +
   1.395 +
   1.396 +
   1.397 +Leiba                        Informational                      [Page 7]
   1.398 +
   1.399 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.400 +
   1.401 +
   1.402 +   ENVELOPE responses), but it can cause severe performance problems by
   1.403 +   forcing the transfer of all body parts when the user might only want
   1.404 +   to see some of them - a user logged on by modem and reading a small
   1.405 +   text message with a large ZIP file attached may prefer to read the
   1.406 +   text only and save the ZIP file for later.  Therefore, a client
   1.407 +   should not normally retrieve entire messages and should retrieve
   1.408 +   message body parts selectively.
   1.409 +
   1.410 +3.2.1.5.  Long Command Lines
   1.411 +
   1.412 +   A client can wind up building a very long command line in an effort to
   1.413 +   try to be efficient about requesting information from a server.  This
   1.414 +   can typically happen when a client builds a message set from selected
   1.415 +   messages and doesn't recognise that contiguous blocks of messages may
   1.416 +   be group in a range.  Suppose a user selects all 10,000 messages in a
   1.417 +   large mailbox and then unselects message 287.  The client could build
   1.418 +   that message set as "1:286,288:10000", but a client that doesn't
   1.419 +   handle that might try to enumerate each message individually and build
   1.420 +   "1,2,3,4, [and so on] ,9999,10000".  Adding that to the fetch command
   1.421 +   results in a command line that's almost 49,000 octets long, and,
   1.422 +   clearly, one can construct a command line that's even longer.
   1.423 +
   1.424 +   A client should limit the length of the command lines it generates to
   1.425 +   approximately 1000 octets (including all quoted strings but not
   1.426 +   including literals).  If the client is unable to group things into
   1.427 +   ranges so that the command line is within that length, it should
   1.428 +   split the request into multiple commands.  The client should use
   1.429 +   literals instead of long quoted strings, in order to keep the command
   1.430 +   length down.
   1.431 +
   1.432 +   For its part, a server should allow for a command line of at least
   1.433 +   8000 octets.  This provides plenty of leeway for accepting reasonable
   1.434 +   length commands from clients.  The server should send a BAD response
   1.435 +   to a command that does not end within the server's maximum accepted
   1.436 +   command length.
   1.437 +
   1.438 +3.2.2. Subscriptions
   1.439 +
   1.440 +   The client isn't the only entity that can get flooded: the end user,
   1.441 +   too, may need some flood control.  The IMAP4 protocol provides such
   1.442 +   control in the form of subscriptions.  Most servers support the
   1.443 +   SUBSCRIBE, UNSUBSCRIBE, and LSUB commands, and many users choose to
   1.444 +   narrow down a large list of available mailboxes by subscribing to the
   1.445 +   ones that they usually want to see.  Clients, with this in mind,
   1.446 +   should give the user a way to see only subscribed mailboxes.  A
   1.447 +   client that never uses the LSUB command takes a significant usability
   1.448 +   feature away from the user.  Of course, the client would not want to
   1.449 +   hide the LIST command completely; the user needs to have a way to
   1.450 +
   1.451 +
   1.452 +
   1.453 +Leiba                        Informational                      [Page 8]
   1.454 +
   1.455 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.456 +
   1.457 +
   1.458 +   choose between LIST and LSUB.  The usual way to do this is to provide
   1.459 +   a setting like "show which mailboxes?:  [] all  [] subscribed only".
   1.460 +
   1.461 +3.2.3. Searching
   1.462 +
   1.463 +   IMAP SEARCH commands can become particularly troublesome (that is,
   1.464 +   slow) on mailboxes containing a large number of messages.  So let's
   1.465 +   put a few things in perspective in that regard.
   1.466 +
   1.467 +   The flag searches should be fast.  The flag searches (ALL, [UN]SEEN,
   1.468 +   [UN]ANSWERED, [UN]DELETED, [UN]DRAFT, [UN]FLAGGED, NEW, OLD, RECENT)
   1.469 +   are known to be used by clients for the client's own use (for
   1.470 +   instance, some clients use "SEARCH UNSEEN" to find unseen mail and
   1.471 +   "SEARCH DELETED" to warn the user before expunging messages).
   1.472 +
   1.473 +   Other searches, particularly the text searches (HEADER, TEXT, BODY)
   1.474 +   are initiated by the user, rather than by the client itself, and
   1.475 +   somewhat slower performance can be tolerated, since the user is aware
   1.476 +   that the search is being done (and is probably aware that it might be
   1.477 +   time-consuming).  A smart server might use dynamic indexing to speed
   1.478 +   commonly used text searches.
   1.479 +
   1.480 +   The client may allow other commands to be sent to the server while a
   1.481 +   SEARCH is in progress, but at the time of this writing there is
   1.482 +   little or no server support for parallel processing of multiple
   1.483 +   commands in the same session (and see "Multiple Accesses of the Same
   1.484 +   Mailbox" above for a description of the dangers of trying to work
   1.485 +   around this by doing your SEARCH in another session).
   1.486 +
   1.487 +   Another word about text searches: some servers, built on database
   1.488 +   back-ends with indexed search capabilities, may return search results
   1.489 +   that do not match the IMAP spec's "case-insensitive substring"
   1.490 +   requirements.  While these servers are in violation of the protocol,
   1.491 +   there is little harm in the violation as long as the search results
   1.492 +   are used only in response to a user's request.  Still, developers of
   1.493 +   such servers should be aware that they ARE violating the protocol,
   1.494 +   should think carefully about that behaviour, and must be certain that
   1.495 +   their servers respond accurately to the flag searches for the reasons
   1.496 +   outlined above.
   1.497 +
   1.498 +   In addition, servers should support CHARSET UTF-8 [UTF-8] in
   1.499 +   searches.
   1.500 +
   1.501 +
   1.502 +
   1.503 +
   1.504 +
   1.505 +
   1.506 +
   1.507 +
   1.508 +
   1.509 +Leiba                        Informational                      [Page 9]
   1.510 +
   1.511 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.512 +
   1.513 +
   1.514 +3.3    Avoiding Invalid Requests
   1.515 +
   1.516 +   IMAP4 provides ways for a server to tell a client in advance what is
   1.517 +   and isn't permitted in some circumstances.  Clients should use these
   1.518 +   features to avoid sending requests that a well designed client would
   1.519 +   know to be invalid.  This section explains this in more detail.
   1.520 +
   1.521 +3.3.1. The CAPABILITY Command
   1.522 +
   1.523 +   All IMAP4 clients should use the CAPABILITY command to determine what
   1.524 +   version of IMAP and what optional features a server supports.  The
   1.525 +   client should not send IMAP4rev1 commands and arguments to a server
   1.526 +   that does not advertize IMAP4rev1 in its CAPABILITY response.
   1.527 +   Similarly, the client should not send IMAP4 commands that no longer
   1.528 +   exist in IMAP4rev1 to a server that does not advertize IMAP4 in its
   1.529 +   CAPABILITY response.  An IMAP4rev1 server is NOT required to support
   1.530 +   obsolete IMAP4 or IMAP2bis commands (though some do; do not let this
   1.531 +   fact lull you into thinking that it's valid to send such commands to
   1.532 +   an IMAP4rev1 server).
   1.533 +
   1.534 +   A client should not send commands to probe for the existance of
   1.535 +   certain extensions.  All standard and standards-track extensions
   1.536 +   include CAPABILITY tokens indicating their presense.  All private and
   1.537 +   experimental extensions should do the same, and clients that take
   1.538 +   advantage of them should use the CAPABILITY response to determine
   1.539 +   whether they may be used or not.
   1.540 +
   1.541 +3.3.2. Don't Do What the Server Says You Can't
   1.542 +
   1.543 +   In many cases, the server, in response to a command, will tell the
   1.544 +   client something about what can and can't be done with a particular
   1.545 +   mailbox.  The client should pay attention to this information and
   1.546 +   should not try to do things that it's been told it can't do.
   1.547 +
   1.548 +   Examples:
   1.549 +
   1.550 +   *  Do not try to SELECT a mailbox that has the \Noselect flag set.
   1.551 +   *  Do not try to CREATE a sub-mailbox in a mailbox that has the
   1.552 +      \Noinferiors flag set.
   1.553 +   *  Do not respond to a failing COPY or APPEND command by trying to
   1.554 +      CREATE the target mailbox if the server does not respond with a
   1.555 +      [TRYCREATE] response code.
   1.556 +   *  Do not try to expunge a mailbox that has been selected with the
   1.557 +      [READ-ONLY] response code.
   1.558 +
   1.559 +
   1.560 +
   1.561 +
   1.562 +
   1.563 +
   1.564 +
   1.565 +Leiba                        Informational                     [Page 10]
   1.566 +
   1.567 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.568 +
   1.569 +
   1.570 +3.4.   Miscellaneous Protocol Considerations
   1.571 +
   1.572 +   We describe here a number of important protocol-related issues, the
   1.573 +   misunderstanding of which has caused significant interoperability
   1.574 +   problems in IMAP4 implementations.  One general item is that every
   1.575 +   implementer should be certain to take note of and to understand
   1.576 +   section 2.2.2 and the preamble to section 7 of the IMAP4rev1 spec
   1.577 +   [RFC-2060].
   1.578 +
   1.579 +3.4.1. Well Formed Protocol
   1.580 +
   1.581 +   We cannot stress enough the importance of adhering strictly to the
   1.582 +   protocol grammar.  The specification of the protocol is quite rigid;
   1.583 +   do not assume that you can insert blank space for "readability" if
   1.584 +   none is called for.  Keep in mind that there are parsers out there
   1.585 +   that will crash if there are protocol errors.  There are clients that
   1.586 +   will report every parser burp to the user.  And in any case,
   1.587 +   information that cannot be parsed is information that is lost.  Be
   1.588 +   careful in your protocol generation.  And see "A Word About Testing",
   1.589 +   below.
   1.590 +
   1.591 +   In particular, note that the string in the INTERNALDATE response is
   1.592 +   NOT an RFC-822 date string - that is, it is not in the same format as
   1.593 +   the first string in the ENVELOPE response.  Since most clients will,
   1.594 +   in fact, accept an RFC-822 date string in the INTERNALDATE response,
   1.595 +   it's easy to miss this in your interoperability testing.  But it will
   1.596 +   cause a problem with some client, so be sure to generate the correct
   1.597 +   string for this field.
   1.598 +
   1.599 +3.4.2. Special Characters
   1.600 +
   1.601 +   Certain characters, currently the double-quote and the backslash, may
   1.602 +   not be sent as-is inside a quoted string.  These characters must be
   1.603 +   preceded by the escape character if they are in a quoted string, or
   1.604 +   else the string must be sent as a literal.  Both clients and servers
   1.605 +   must handle this, both on output (they must send these characters
   1.606 +   properly) and on input (they must be able to receive escaped
   1.607 +   characters in quoted strings).  Example:
   1.608 +
   1.609 +       C: 001 LIST "" %
   1.610 +       S: * LIST () "" INBOX
   1.611 +       S: * LIST () "\\" TEST
   1.612 +       S: * LIST () "\\" {12}
   1.613 +       S: "My" mailbox
   1.614 +       S: 001 OK done
   1.615 +       C: 002 LIST "" "\"My\" mailbox\\%"
   1.616 +       S: * LIST () "\\" {17}
   1.617 +       S: "My" mailbox\Junk
   1.618 +
   1.619 +
   1.620 +
   1.621 +Leiba                        Informational                     [Page 11]
   1.622 +
   1.623 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.624 +
   1.625 +
   1.626 +       S: 002 OK done
   1.627 +
   1.628 +   Note that in the example the server sent the hierarchy delimiter as
   1.629 +   an escaped character in the quoted string and sent the mailbox name
   1.630 +   containing imbedded double-quotes as a literal.  The client used only
   1.631 +   quoted strings, escaping both the backslash and the double-quote
   1.632 +   characters.
   1.633 +
   1.634 +   The CR and LF characters may be sent ONLY in literals; they are not
   1.635 +   allowed, even if escaped, inside quoted strings.
   1.636 +
   1.637 +   And while we're talking about special characters: the IMAP spec, in
   1.638 +   the section titled "Mailbox International Naming Convention",
   1.639 +   describes how to encode mailbox names in modified UTF-7 [UTF-7 and
   1.640 +   RFC-2060].  Implementations must adhere to this in order to be
   1.641 +   interoperable in the international market, and servers should
   1.642 +   validate mailbox names sent by client and reject names that do not
   1.643 +   conform.
   1.644 +
   1.645 +   As to special characters in userids and passwords: clients must not
   1.646 +   restrict what a user may type in for a userid or a password.  The
   1.647 +   formal grammar specifies that these are "astrings", and an astring
   1.648 +   can be a literal.  A literal, in turn can contain any 8-bit
   1.649 +   character, and clients must allow users to enter all 8-bit characters
   1.650 +   here, and must pass them, unchanged, to the server (being careful to
   1.651 +   send them as literals when necessary).  In particular, some server
   1.652 +   configurations use "@" in user names, and some clients do not allow
   1.653 +   that character to be entered; this creates a severe interoperability
   1.654 +   problem.
   1.655 +
   1.656 +3.4.3. UIDs and UIDVALIDITY
   1.657 +
   1.658 +   Servers that support existing back-end mail stores often have no good
   1.659 +   place to save UIDs for messages.  Often the existing mail store will
   1.660 +   not have the concept of UIDs in the sense that IMAP has: strictly
   1.661 +   increasing, never re-issued, 32-bit integers.  Some servers solve
   1.662 +   this by storing the UIDs in a place that's accessible to end users,
   1.663 +   allowing for the possibility that the users will delete them.  Others
   1.664 +   solve it by re-assigning UIDs every time a mailbox is selected.
   1.665 +
   1.666 +   The server should maintain UIDs permanently for all messages if it
   1.667 +   can.  If that's not possible, the server must change the UIDVALIDITY
   1.668 +   value for the mailbox whenever any of the UIDs may have become
   1.669 +   invalid.  Clients must recognize that the UIDVALIDITY has changed and
   1.670 +   must respond to that condition by throwing away any information that
   1.671 +   they have saved about UIDs in that mailbox.  There have been many
   1.672 +   problems in this area when clients have failed to do this; in the
   1.673 +   worst case it will result in loss of mail when a client deletes the
   1.674 +
   1.675 +
   1.676 +
   1.677 +Leiba                        Informational                     [Page 12]
   1.678 +
   1.679 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.680 +
   1.681 +
   1.682 +   wrong piece of mail by using a stale UID.
   1.683 +
   1.684 +   It seems to be a common misunderstanding that "the UIDVALIDITY and
   1.685 +   the UID, taken together, form a 64-bit identifier that uniquely
   1.686 +   identifies a message on a server".  This is absolutely NOT TRUE.
   1.687 +   There is no assurance that the UIDVALIDITY values of two mailboxes be
   1.688 +   different, so the UIDVALIDITY in no way identifies a mailbox.  The
   1.689 +   ONLY purpose of UIDVALIDITY is, as its name indicates, to give the
   1.690 +   client a way to check the validity of the UIDs it has cached.  While
   1.691 +   it is a valid implementation choice to put these values together to
   1.692 +   make a 64-bit identifier for the message, the important concept here
   1.693 +   is that UIDs are not unique between mailboxes; they are only unique
   1.694 +   WITHIN a given mailbox.
   1.695 +
   1.696 +   Some server implementations have attempted to make UIDs unique across
   1.697 +   the entire server.  This is inadvisable, in that it limits the life
   1.698 +   of UIDs unnecessarily.  The UID is a 32-bit number and will run out
   1.699 +   in reasonably finite time if it's global across the server.  If you
   1.700 +   assign UIDs sequentially in one mailbox, you will not have to start
   1.701 +   re-using them until you have had, at one time or another, 2**32
   1.702 +   different messages in that mailbox.  In the global case, you will
   1.703 +   have to reuse them once you have had, at one time or another, 2**32
   1.704 +   different messages in the entire mail store.  Suppose your server has
   1.705 +   around 8000 users registered (2**13).  That gives an average of 2**19
   1.706 +   UIDs per user.  Suppose each user gets 32 messages (2**5) per day.
   1.707 +   That gives you 2**14 days (16000+ days = about 45 years) before you
   1.708 +   run out.  That may seem like enough, but multiply the usage just a
   1.709 +   little (a lot of spam, a lot of mailing list subscriptions, more
   1.710 +   users) and you limit yourself too much.
   1.711 +
   1.712 +   What's worse is that if you have to wrap the UIDs, and, thus, you
   1.713 +   have to change UIDVALIDITY and invalidate the UIDs in the mailbox,
   1.714 +   you have to do it for EVERY mailbox in the system, since they all
   1.715 +   share the same UID pool.  If you assign UIDs per mailbox and you have
   1.716 +   a problem, you only have to kill the UIDs for that one mailbox.
   1.717 +
   1.718 +   Under extreme circumstances (and this is extreme, indeed), the server
   1.719 +   may have to invalidate UIDs while a mailbox is in use by a client -
   1.720 +   that is, the UIDs that the client knows about in its active mailbox
   1.721 +   are no longer valid.  In that case, the server must immediately
   1.722 +   change the UIDVALIDITY and must communicate this to the client.  The
   1.723 +   server may do this by sending an unsolicited UIDVALIDITY message, in
   1.724 +   the same form as in response to the SELECT command.  Clients must be
   1.725 +   prepared to handle such a message and the possibly coincident failure
   1.726 +   of the command in process.  For example:
   1.727 +
   1.728 +
   1.729 +
   1.730 +
   1.731 +
   1.732 +
   1.733 +Leiba                        Informational                     [Page 13]
   1.734 +
   1.735 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.736 +
   1.737 +
   1.738 +       C: 032 UID STORE 382 +Flags.silent \Deleted
   1.739 +       S: * OK [UIDVALIDITY 12345] New UIDVALIDITY value!
   1.740 +       S: 032 NO UID command rejected because UIDVALIDITY changed!
   1.741 +       C: ...invalidates local information and re-fetches...
   1.742 +       C: 033 FETCH 1:* UID
   1.743 +       ...etc...
   1.744 +
   1.745 +   At the time of the writing of this document, the only server known to
   1.746 +   do this does so only under the following condition: the client
   1.747 +   selects INBOX, but there is not yet a physical INBOX file created.
   1.748 +   Nonetheless, the SELECT succeeds, exporting an empty INBOX with a
   1.749 +   temporary UIDVALIDITY of 1.  While the INBOX remains selected, mail
   1.750 +   is delivered to the user, which creates the real INBOX file and
   1.751 +   assigns a permanent UIDVALIDITY (that is likely not to be 1).  The
   1.752 +   server reports the change of UIDVALIDITY, but as there were no
   1.753 +   messages before, so no UIDs have actually changed, all the client
   1.754 +   must do is accept the change in UIDVALIDITY.
   1.755 +
   1.756 +   Alternatively, a server may force the client to re-select the
   1.757 +   mailbox, at which time it will obtain a new UIDVALIDITY value.  To do
   1.758 +   this, the server closes this client session (see "Severed
   1.759 +   Connections" above) and the client then reconnects and gets back in
   1.760 +   synch.  Clients must be prepared for either of these behaviours.
   1.761 +
   1.762 +   We do not know of, nor do we anticipate the future existance of, a
   1.763 +   server that changes UIDVALIDITY while there are existing messages,
   1.764 +   but clients must be prepared to handle this eventuality.
   1.765 +
   1.766 +3.4.4. FETCH Responses
   1.767 +
   1.768 +   When a client asks for certain information in a FETCH command, the
   1.769 +   server may return the requested information in any order, not
   1.770 +   necessarily in the order that it was requested.  Further, the server
   1.771 +   may return the information in separate FETCH responses and may also
   1.772 +   return information that was not explicitly requested (to reflect to
   1.773 +   the client changes in the state of the subject message).  Some
   1.774 +   examples:
   1.775 +
   1.776 +       C: 001 FETCH 1 UID FLAGS INTERNALDATE
   1.777 +       S: * 5 FETCH (FLAGS (\Deleted))
   1.778 +       S: * 1 FETCH (FLAGS (\Seen) INTERNALDATE "..." UID 345)
   1.779 +       S: 001 OK done
   1.780 +
   1.781 +   (In this case, the responses are in a different order.  Also, the
   1.782 +   server returned a flag update for message 5, which wasn't part of the
   1.783 +   client's request.)
   1.784 +
   1.785 +
   1.786 +
   1.787 +
   1.788 +
   1.789 +Leiba                        Informational                     [Page 14]
   1.790 +
   1.791 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.792 +
   1.793 +
   1.794 +       C: 002 FETCH 2 UID FLAGS INTERNALDATE
   1.795 +       S: * 2 FETCH (INTERNALDATE "...")
   1.796 +       S: * 2 FETCH (UID 399)
   1.797 +       S: * 2 FETCH (FLAGS ())
   1.798 +       S: 002 OK done
   1.799 +
   1.800 +   (In this case, the responses are in a different order and were
   1.801 +   returned in separate responses.)
   1.802 +
   1.803 +       C: 003 FETCH 2 BODY[1]
   1.804 +       S: * 2 FETCH (FLAGS (\Seen) BODY[1] {14}
   1.805 +       S: Hello world!
   1.806 +       S: )
   1.807 +       S: 003 OK done
   1.808 +
   1.809 +   (In this case, the FLAGS response was added by the server, since
   1.810 +   fetching the body part caused the server to set the \Seen flag.)
   1.811 +
   1.812 +   Because of this characteristic a client must be ready to receive any
   1.813 +   FETCH response at any time and should use that information to update
   1.814 +   its local information about the message to which the FETCH response
   1.815 +   refers.  A client must not assume that any FETCH responses will come
   1.816 +   in any particular order, or even that any will come at all.  If after
   1.817 +   receiving the tagged response for a FETCH command the client finds
   1.818 +   that it did not get all of the information requested, the client
   1.819 +   should send a NOOP command to the server to ensure that the server
   1.820 +   has an opportunity to send any pending EXPUNGE responses to the
   1.821 +   client (see [RFC-2180]).
   1.822 +
   1.823 +3.4.5. RFC822.SIZE
   1.824 +
   1.825 +   Some back-end mail stores keep the mail in a canonical form, rather
   1.826 +   than retaining the original MIME format of the messages.  This means
   1.827 +   that the server must reassemble the message to produce a MIME stream
   1.828 +   when a client does a fetch such as RFC822 or BODY[], requesting the
   1.829 +   entire message.  It also may mean that the server has no convenient
   1.830 +   way to know the RFC822.SIZE of the message.  Often, such a server
   1.831 +   will actually have to build the MIME stream to compute the size, only
   1.832 +   to throw the stream away and report the size to the client.
   1.833 +
   1.834 +   When this is the case, some servers have chosen to estimate the size,
   1.835 +   rather than to compute it precisely.  Such an estimate allows the
   1.836 +   client to display an approximate size to the user and to use the
   1.837 +   estimate in flood control considerations (q.v.), but requires that
   1.838 +   the client not use the size for things such as allocation of buffers,
   1.839 +   because those buffers might then be too small to hold the actual MIME
   1.840 +   stream.  Instead, a client should use the size that's returned in the
   1.841 +   literal when you fetch the data.
   1.842 +
   1.843 +
   1.844 +
   1.845 +Leiba                        Informational                     [Page 15]
   1.846 +
   1.847 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.848 +
   1.849 +
   1.850 +   The protocol requires that the RFC822.SIZE value returned by the
   1.851 +   server be EXACT.  Estimating the size is a protocol violation, and
   1.852 +   server designers must be aware that, despite the performance savings
   1.853 +   they might realize in using an estimate, this practice will cause
   1.854 +   some clients to fail in various ways.  If possible, the server should
   1.855 +   compute the RFC822.SIZE for a particular message once, and then save
   1.856 +   it for later retrieval.  If that's not possible, the server must
   1.857 +   compute the value exactly every time.  Incorrect estimates do cause
   1.858 +   severe interoperability problems with some clients.
   1.859 +
   1.860 +3.4.6. Expunged Messages
   1.861 +
   1.862 +   If the server allows multiple connections to the same mailbox, it is
   1.863 +   often possible for messages to be expunged in one client unbeknownst
   1.864 +   to another client.  Since the server is not allowed to tell the
   1.865 +   client about these expunged messages in response to a FETCH command,
   1.866 +   the server may have to deal with the issue of how to return
   1.867 +   information about an expunged message.  There was extensive
   1.868 +   discussion about this issue, and the results of that discussion are
   1.869 +   summarized in [RFC-2180].  See that reference for a detailed
   1.870 +   explanation and for recommendations.
   1.871 +
   1.872 +3.4.7. The Namespace Issue
   1.873 +
   1.874 +   Namespaces are a very muddy area in IMAP4 implementation right now
   1.875 +   (see [NAMESPACE] for a proposal to clear the water a bit).  Until the
   1.876 +   issue is resolved, the important thing for client developers to
   1.877 +   understand is that some servers provide access through IMAP to more
   1.878 +   than just the user's personal mailboxes, and, in fact, the user's
   1.879 +   personal mailboxes may be "hidden" somewhere in the user's default
   1.880 +   hierarchy.  The client, therefore, should provide a setting wherein
   1.881 +   the user can specify a prefix to be used when accessing mailboxes. If
   1.882 +   the user's mailboxes are all in "~/mail/", for instance, then the
   1.883 +   user can put that string in the prefix.  The client would then put
   1.884 +   the prefix in front of any name pattern in the LIST and LSUB
   1.885 +   commands:
   1.886 +
   1.887 +       C: 001 LIST "" ~/mail/%
   1.888 +
   1.889 +   (See also "Reference Names in the LIST Command" below.)
   1.890 +
   1.891 +3.4.8. Creating Special-Use Mailboxes
   1.892 +
   1.893 +   It may seem at first that this is part of the namespace issue; it is
   1.894 +   not, and is only indirectly related to it.  A number of clients like
   1.895 +   to create special-use mailboxes with particular names.  Most
   1.896 +   commonly, clients with a "trash folder" model of message deletion
   1.897 +   want to create a mailbox with the name "Trash" or "Deleted".  Some
   1.898 +
   1.899 +
   1.900 +
   1.901 +Leiba                        Informational                     [Page 16]
   1.902 +
   1.903 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.904 +
   1.905 +
   1.906 +   clients want to create a "Drafts" mailbox, an "Outbox" mailbox, or a
   1.907 +   "Sent Mail" mailbox.  And so on.  There are two major
   1.908 +   interoperability problems with this practice:
   1.909 +
   1.910 +   1. different clients may use different names for mailboxes with
   1.911 +      similar functions (such as "Trash" and "Deleted"), or may manage
   1.912 +      the same mailboxes in different ways, causing problems if a user
   1.913 +      switches between clients and
   1.914 +   2. there is no guarantee that the server will allow the creation of
   1.915 +      the desired mailbox.
   1.916 +
   1.917 +   The client developer is, therefore, well advised to consider
   1.918 +   carefully the creation of any special-use mailboxes on the server,
   1.919 +   and, further, the client must not require such mailbox creation -
   1.920 +   that is, if you do decide to do this, you must handle gracefully the
   1.921 +   failure of the CREATE command and behave reasonably when your
   1.922 +   special-use mailboxes do not exist and can not be created.
   1.923 +
   1.924 +   In addition, the client developer should provide a convenient way for
   1.925 +   the user to select the names for any special-use mailboxes, allowing
   1.926 +   the user to make these names the same in all clients used and to put
   1.927 +   them where the user wants them.
   1.928 +
   1.929 +3.4.9. Reference Names in the LIST Command
   1.930 +
   1.931 +   Many implementers of both clients and servers are confused by the
   1.932 +   "reference name" on the LIST command.  The reference name is intended
   1.933 +   to be used in much the way a "cd" (change directory) command is used
   1.934 +   on Unix, PC DOS, Windows, and OS/2 systems.  That is, the mailbox
   1.935 +   name is interpreted in much the same way as a file of that name would
   1.936 +   be found if one had done a "cd" command into the directory specified
   1.937 +   by the reference name.  For example, in Unix we have the following:
   1.938 +
   1.939 +       > cd /u/jones/junk
   1.940 +       > vi banana        [file is "/u/jones/junk/banana"]
   1.941 +       > vi stuff/banana  [file is "/u/jones/junk/stuff/banana"]
   1.942 +       > vi /etc/hosts    [file is "/etc/hosts"]
   1.943 +
   1.944 +   In the past, there have been several interoperability problems with
   1.945 +   this.  First, while some IMAP servers are built on Unix or PC file
   1.946 +   systems, many others are not, and the file system semantics do not
   1.947 +   make sense in those configurations.  Second, while some IMAP servers
   1.948 +   expose the underlying file system to the clients, others allow access
   1.949 +   only to the user's personal mailboxes, or to some other limited set
   1.950 +   of files, making such file-system-like semantics less meaningful.
   1.951 +   Third, because the IMAP spec leaves the interpretation of the
   1.952 +   reference name as "implementation-dependent", in the past the various
   1.953 +   server implementations handled it in vastly differing ways.
   1.954 +
   1.955 +
   1.956 +
   1.957 +Leiba                        Informational                     [Page 17]
   1.958 +
   1.959 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
   1.960 +
   1.961 +
   1.962 +   The following recommendations are the result of significant
   1.963 +   operational experience, and are intended to maximize
   1.964 +   interoperability.
   1.965 +
   1.966 +   Server implementations must implement the reference argument in a way
   1.967 +   that matches the intended "change directory" operation as closely as
   1.968 +   possible.  As a minimum implementation, the reference argument may be
   1.969 +   prepended to the mailbox name (while suppressing double delimiters;
   1.970 +   see the next paragraph).  Even servers that do not provide a way to
   1.971 +   break out of the current hierarchy (see "breakout facility" below)
   1.972 +   must provide a reasonable implementation of the reference argument,
   1.973 +   as described here, so that they will interoperate with clients that
   1.974 +   use it.
   1.975 +
   1.976 +   Server implementations that prepend the reference argument to the
   1.977 +   mailbox name should insert a hierarchy delimiter between them, and
   1.978 +   must not insert a second if one is already present:
   1.979 +
   1.980 +       C: A001 LIST ABC DEF
   1.981 +       S: * LIST () "/" ABC/DEF   <=== should do this
   1.982 +       S: A001 OK done
   1.983 +
   1.984 +       C: A002 LIST ABC/ /DEF
   1.985 +       S: * LIST () "/" ABC//DEF     <=== must not do this
   1.986 +       S: A002 OK done
   1.987 +
   1.988 +   On clients, the reference argument is chiefly used to implement a
   1.989 +   "breakout facility", wherein the user may directly access a mailbox
   1.990 +   outside the "current directory" hierarchy.  Client implementations
   1.991 +   should have an operational mode that does not use the reference
   1.992 +   argument.  This is to interoperate with older servers that did not
   1.993 +   implement the reference argument properly.  While it's a good idea to
   1.994 +   give the user access to a breakout facility, clients that do not
   1.995 +   intend to do so should not use the reference argument at all.
   1.996 +
   1.997 +   Client implementations should always place a trailing hierarchy
   1.998 +   delimiter on the reference argument.  This is because some servers
   1.999 +   prepend the reference argument to the mailbox name without inserting
  1.1000 +   a hierarchy delimiter, while others do insert a hierarchy delimiter
  1.1001 +   if one is not already present.  A client that puts the delimiter in
  1.1002 +   will work with both varieties of server.
  1.1003 +
  1.1004 +   Client implementations that implement a breakout facility should
  1.1005 +   allow the user to choose whether or not to use a leading hierarchy
  1.1006 +   delimiter on the mailbox argument.  This is because the handling of a
  1.1007 +   leading mailbox hierarchy delimiter also varies from server to
  1.1008 +   server, and even between different mailstores on the same server.  In
  1.1009 +   some cases, a leading hierarchy delimiter means "discard the
  1.1010 +
  1.1011 +
  1.1012 +
  1.1013 +Leiba                        Informational                     [Page 18]
  1.1014 +
  1.1015 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
  1.1016 +
  1.1017 +
  1.1018 +   reference argument" (implementing the intended breakout facility),
  1.1019 +   thus:
  1.1020 +
  1.1021 +       C: A001 LIST ABC/ /DEF
  1.1022 +       S: * LIST () "/" /DEF
  1.1023 +       S: A001 OK done
  1.1024 +
  1.1025 +   In other cases, however, the two are catenated and the extra
  1.1026 +   hierarchy delimiter is discarded, thus:
  1.1027 +
  1.1028 +       C: A001 LIST ABC/ /DEF
  1.1029 +       S: * LIST () "/" ABC/DEF
  1.1030 +       S: A001 OK done
  1.1031 +
  1.1032 +   Client implementations must not assume that the server supports a
  1.1033 +   breakout facility, but may provide a way for the user to use one if
  1.1034 +   it is available.  Any breakout facility should be exported to the
  1.1035 +   user interface.  Note that there may be other "breakout" characters
  1.1036 +   besides the hierarchy delimiter (for instance, UNIX filesystem
  1.1037 +   servers are likely to use a leading "~" as well), and that their
  1.1038 +   interpretation is server-dependent.
  1.1039 +
  1.1040 +3.4.10.   Mailbox Hierarchy Delimiters
  1.1041 +
  1.1042 +   The server's selection of what to use as a mailbox hierarchy
  1.1043 +   delimiter is a difficult one, involving several issues: What
  1.1044 +   characters do users expect to see?  What characters can they enter
  1.1045 +   for a hierarchy delimiter if it is desired (or required) that the
  1.1046 +   user enter it?  What character can be used for the hierarchy
  1.1047 +   delimiter, noting that the chosen character can not otherwise be used
  1.1048 +   in the mailbox name?
  1.1049 +
  1.1050 +   Because some interfaces show users the hierarchy delimiters or allow
  1.1051 +   users to enter qualified mailbox names containing them, server
  1.1052 +   implementations should use delimiter characters that users generally
  1.1053 +   expect to see as name separators.  The most common characters used
  1.1054 +   for this are "/" (as in Unix file names), "\" (as in OS/2 and Windows
  1.1055 +   file names), and "." (as in news groups).  There is little to choose
  1.1056 +   among these apart from what users may expect or what is dictated by
  1.1057 +   the underlying file system, if any.  One consideration about using
  1.1058 +   "\" is that it's also a special character in the IMAP protocol. While
  1.1059 +   the use of other hierarchy delimiter characters is permissible, A
  1.1060 +   DESIGNER IS WELL ADVISED TO STAY WITH ONE FROM THIS SET unless the
  1.1061 +   server is intended for special purposes only.  Implementers might be
  1.1062 +   thinking about using characters such as "-", "_", ";", "&", "#", "@",
  1.1063 +   and "!", but they should be aware of the surprise to the user as well
  1.1064 +   as of the effect on URLs and other external specifications (since
  1.1065 +   some of these characters have special meanings there).  Also, a
  1.1066 +
  1.1067 +
  1.1068 +
  1.1069 +Leiba                        Informational                     [Page 19]
  1.1070 +
  1.1071 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
  1.1072 +
  1.1073 +
  1.1074 +   server that uses "\" (and clients of such a server) must remember to
  1.1075 +   escape that character in quoted strings or to send literals instead.
  1.1076 +   Literals are recommended over escaped characters in quoted strings in
  1.1077 +   order to maintain compatibility with older IMAP versions that did not
  1.1078 +   allow escaped characters in quoted strings (but check the grammar to
  1.1079 +   see where literals are allowed):
  1.1080 +
  1.1081 +       C: 001 LIST "" {13}
  1.1082 +       S: + send literal
  1.1083 +       C: this\%\%\%\h*
  1.1084 +       S: * LIST () "\\" {27}
  1.1085 +       S: this\is\a\mailbox\hierarchy
  1.1086 +       S: 001 OK LIST complete
  1.1087 +
  1.1088 +   In any case, a server should not use normal alpha-numeric characters
  1.1089 +   (such as "X" or "0") as delimiters; a user would be very surprised to
  1.1090 +   find that "EXPENDITURES" actually represented a two-level hierarchy.
  1.1091 +   And a server should not use characters that are non-printable or
  1.1092 +   difficult or impossible to enter on a standard US keyboard.  Control
  1.1093 +   characters, box-drawing characters, and characters from non-US
  1.1094 +   alphabets fit into this category.  Their use presents
  1.1095 +   interoperability problems that are best avoided.
  1.1096 +
  1.1097 +   The UTF-7 encoding of mailbox names also raises questions about what
  1.1098 +   to do with the hierarchy delimiters in encoded names: do we encode
  1.1099 +   each hierarchy level and separate them with delimiters, or do we
  1.1100 +   encode the fully qualified name, delimiters and all?  The answer for
  1.1101 +   IMAP is the former: encode each hierarchy level separately, and
  1.1102 +   insert delimiters between.  This makes it particularly important not
  1.1103 +   to use as a hierarchy delimiter a character that might cause
  1.1104 +   confusion with IMAP's modified UTF-7 [UTF-7 and RFC-2060] encoding.
  1.1105 +
  1.1106 +   To repeat: a server should use "/", "\", or "." as its hierarchy
  1.1107 +   delimiter.  The use of any other character is likely to cause
  1.1108 +   problems and is STRONGLY DISCOURAGED.
  1.1109 +
  1.1110 +3.4.11.   ALERT Response Codes
  1.1111 +
  1.1112 +   The protocol spec is very clear on the matter of what to do with
  1.1113 +   ALERT response codes, and yet there are many clients that violate it
  1.1114 +   so it needs to be said anyway: "The human-readable text contains a
  1.1115 +   special alert that must be presented to the user in a fashion that
  1.1116 +   calls the user's attention to the message."  That should be clear
  1.1117 +   enough, but I'll repeat it here: Clients must present ALERT text
  1.1118 +   clearly to the user.
  1.1119 +
  1.1120 +
  1.1121 +
  1.1122 +
  1.1123 +
  1.1124 +
  1.1125 +Leiba                        Informational                     [Page 20]
  1.1126 +
  1.1127 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
  1.1128 +
  1.1129 +
  1.1130 +3.4.12.   Deleting Mailboxes
  1.1131 +
  1.1132 +   The protocol does not guarantee that a client may delete a mailbox
  1.1133 +   that is not empty, though on some servers it is permissible and is,
  1.1134 +   in fact, much faster than the alternative or deleting all the
  1.1135 +   messages from the client.  If the client chooses to try to take
  1.1136 +   advantage of this possibility it must be prepared to use the other
  1.1137 +   method in the even that the more convenient one fails.  Further, a
  1.1138 +   client should not try to delete the mailbox that it has selected, but
  1.1139 +   should first close that mailbox; some servers do not permit the
  1.1140 +   deletion of the selected mailbox.
  1.1141 +
  1.1142 +   That said, a server should permit the deletion of a non-empty
  1.1143 +   mailbox; there's little reason to pass this work on to the client.
  1.1144 +   Moreover, forbidding this prevents the deletion of a mailbox that for
  1.1145 +   some reason can not be opened or expunged, leading to possible
  1.1146 +   denial-of-service problems.
  1.1147 +
  1.1148 +   Example:
  1.1149 +
  1.1150 +       [User tells the client to delete mailbox BANANA, which is
  1.1151 +       currently selected...]
  1.1152 +       C: 008 CLOSE
  1.1153 +       S: 008 OK done
  1.1154 +       C: 009 DELETE BANANA
  1.1155 +       S: 009 NO Delete failed; mailbox is not empty.
  1.1156 +       C: 010 SELECT BANANA
  1.1157 +       S: * ... untagged SELECT responses
  1.1158 +       S: 010 OK done
  1.1159 +       C: 011 STORE 1:* +FLAGS.SILENT \DELETED
  1.1160 +       S: 011 OK done
  1.1161 +       C: 012 CLOSE
  1.1162 +       S: 012 OK done
  1.1163 +       C: 013 DELETE BANANA
  1.1164 +       S: 013 OK done
  1.1165 +
  1.1166 +3.5.   A Word About Testing
  1.1167 +
  1.1168 +   Since the whole point of IMAP is interoperability, and since
  1.1169 +   interoperability can not be tested in a vacuum, the final
  1.1170 +   recommendation of this treatise is, "Test against EVERYTHING."  Test
  1.1171 +   your client against every server you can get an account on.  Test
  1.1172 +   your server with every client you can get your hands on.  Many
  1.1173 +   clients make limited test versions available on the Web for the
  1.1174 +   downloading.  Many server owners will give serious client developers
  1.1175 +   guest accounts for testing.  Contact them and ask.  NEVER assume that
  1.1176 +   because your client works with one or two servers, or because your
  1.1177 +   server does fine with one or two clients, you will interoperate well
  1.1178 +
  1.1179 +
  1.1180 +
  1.1181 +Leiba                        Informational                     [Page 21]
  1.1182 +
  1.1183 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
  1.1184 +
  1.1185 +
  1.1186 +   in general.
  1.1187 +
  1.1188 +   In particular, in addition to everything else, be sure to test
  1.1189 +   against the reference implementations: the PINE client, the
  1.1190 +   University of Washington server, and the Cyrus server.
  1.1191 +
  1.1192 +   See the following URLs on the web for more information here:
  1.1193 +
  1.1194 +       IMAP Products and Sources: http://www.imap.org/products.html
  1.1195 +       IMC MailConnect: http://www.imc.org/imc-mailconnect
  1.1196 +
  1.1197 +4. Security Considerations
  1.1198 +
  1.1199 +   This document describes behaviour of clients and servers that use the
  1.1200 +   IMAP4 protocol, and as such, has the same security considerations as
  1.1201 +   described in [RFC-2060].
  1.1202 +
  1.1203 +5. References
  1.1204 +
  1.1205 +   [RFC-2060]  Crispin, M., "Internet Message Access Protocol - Version
  1.1206 +               4rev1", RFC 2060, December 1996.
  1.1207 +
  1.1208 +   [RFC-2119]  Bradner, S., "Key words for use in RFCs to Indicate
  1.1209 +               Requirement Levels", BCP 14, RFC 2119, March 1997.
  1.1210 +
  1.1211 +   [RFC-2180]  Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC
  1.1212 +               2180, July 1997.
  1.1213 +
  1.1214 +   [UTF-8]     Yergeau, F., " UTF-8, a transformation format of Unicode
  1.1215 +               and ISO 10646", RFC 2044, October 1996.
  1.1216 +
  1.1217 +   [UTF-7]     Goldsmith, D. and M. Davis, "UTF-7, a Mail-Safe
  1.1218 +               Transformation Format of Unicode", RFC 2152, May 1997.
  1.1219 +
  1.1220 +   [NAMESPACE] Gahrns, M. and C. Newman, "IMAP4 Namespace", Work in
  1.1221 +               Progress.
  1.1222 +
  1.1223 +6. Author's Address
  1.1224 +
  1.1225 +   Barry Leiba
  1.1226 +   IBM T.J. Watson Research Center
  1.1227 +   30 Saw Mill River Road
  1.1228 +   Hawthorne, NY  10532
  1.1229 +
  1.1230 +   Phone: 1-914-784-7941
  1.1231 +   EMail: leiba@watson.ibm.com
  1.1232 +
  1.1233 +
  1.1234 +
  1.1235 +
  1.1236 +
  1.1237 +Leiba                        Informational                     [Page 22]
  1.1238 +
  1.1239 +RFC 2683          IMAP4 Implementation Recommendations    September 1999
  1.1240 +
  1.1241 +
  1.1242 +7. Full Copyright Statement
  1.1243 +
  1.1244 +   Copyright (C) The Internet Society (1999).  All Rights Reserved.
  1.1245 +
  1.1246 +   This document and translations of it may be copied and furnished to
  1.1247 +   others, and derivative works that comment on or otherwise explain it
  1.1248 +   or assist in its implementation may be prepared, copied, published
  1.1249 +   and distributed, in whole or in part, without restriction of any
  1.1250 +   kind, provided that the above copyright notice and this paragraph are
  1.1251 +   included on all such copies and derivative works.  However, this
  1.1252 +   document itself may not be modified in any way, such as by removing
  1.1253 +   the copyright notice or references to the Internet Society or other
  1.1254 +   Internet organizations, except as needed for the purpose of
  1.1255 +   developing Internet standards in which case the procedures for
  1.1256 +   copyrights defined in the Internet Standards process must be
  1.1257 +   followed, or as required to translate it into languages other than
  1.1258 +   English.
  1.1259 +
  1.1260 +   The limited permissions granted above are perpetual and will not be
  1.1261 +   revoked by the Internet Society or its successors or assigns.
  1.1262 +
  1.1263 +   This document and the information contained herein is provided on an
  1.1264 +   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
  1.1265 +   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
  1.1266 +   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
  1.1267 +   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
  1.1268 +   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  1.1269 +
  1.1270 +Acknowledgement
  1.1271 +
  1.1272 +   Funding for the RFC Editor function is currently provided by the
  1.1273 +   Internet Society.
  1.1274 +
  1.1275 +
  1.1276 +
  1.1277 +
  1.1278 +
  1.1279 +
  1.1280 +
  1.1281 +
  1.1282 +
  1.1283 +
  1.1284 +
  1.1285 +
  1.1286 +
  1.1287 +
  1.1288 +
  1.1289 +
  1.1290 +
  1.1291 +
  1.1292 +
  1.1293 +Leiba                        Informational                     [Page 23]
  1.1294 +