idnits 2.17.1 draft-leiba-imap-implement-guide-09.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 5 instances of too long lines in the document, the longest one being 19 characters in excess of 72. ** The abstract seems to contain references ([RFC-2060]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 1999) is 8958 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'UIDVALIDITY 824708485' is mentioned on line 260, but not defined == Missing Reference: 'UNSEEN 9921' is mentioned on line 261, but not defined == Missing Reference: 'UNSEEN' is mentioned on line 266, but not defined == Missing Reference: 'TRYCREATE' is mentioned on line 448, but not defined == Missing Reference: 'READ-ONLY' is mentioned on line 450, but not defined == Missing Reference: 'UIDVALIDITY 12345' is mentioned on line 595, but not defined -- Looks like a reference, but probably isn't: '1' on line 649 == Unused Reference: 'UTF-7' is defined on line 999, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2060 (Obsoleted by RFC 3501) ** Downref: Normative reference to an Informational RFC: RFC 2180 ** Obsolete normative reference: RFC 2044 (ref. 'UTF-8') (Obsoleted by RFC 2279) ** Downref: Normative reference to an Informational RFC: RFC 2152 (ref. 'UTF-7') -- Possible downref: Non-RFC (?) normative reference: ref. 'NAMESPACE' Summary: 14 errors (**), 0 flaws (~~), 8 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group B. Leiba 2 Internet Draft IBM T.J. Watson Research Center 3 Document: draft-leiba-imap-implement-guide-09.txt May 1999 4 Expires October 1999 6 IMAP4 Implementation Recommendations 8 Status of this Document 10 This document is an Internet-Draft and is in full conformance with 11 all provisions of Section 10 of RFC2026. Internet-Drafts are working 12 documents of the Internet Engineering Task Force (IETF), its areas, 13 and its working groups. Note that other groups may also distribute 14 working documents as Internet-Drafts. 16 Internet-Drafts are draft documents valid for a maximum of six months 17 and may be updated, replaced, or obsoleted by other documents at any 18 time. It is inappropriate to use Internet-Drafts as reference 19 material or to cite them other than as "work in progress." 21 The list of current Internet-Drafts can be accessed at 22 http://www.ietf.org/ietf/1id-abstracts.txt 24 The list of Internet-Draft Shadow Directories can be accessed at 25 http://www.ietf.org/shadow.html. 27 This document provides information for the Internet community. This 28 document does not specify an Internet standard of any kind. 29 Distribution of this document is unlimited. A revised version of 30 this draft document will be submitted to the RFC editor. Discussion 31 and suggestions for improvement are requested; discussion should be 32 held on the IMAP mailing list, "imap@u.washington.edu" (subscription 33 requests go to "imap-request@u.washington.edu"). 35 1. Abstract 37 The IMAP4 specification [RFC-2060] describes a rich protocol for use 38 in building clients and servers for storage, retrieval, and 39 manipulation of electronic mail. Because the protocol is so rich and 40 has so many implementation choices, there are often trade-offs that 41 must be made and issues that must be considered when designing such 42 clients and servers. This document attempts to outline these issues 43 and to make recommendations in order to make the end products as 44 interoperable as possible. 46 2. Conventions used in this document 48 In examples, "C:" indicates lines sent by a client that is connected 49 to a server. "S:" indicates lines sent by the server to the client. 51 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 52 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 53 document are to be interpreted as described in [RFC-2119]. 55 3. Interoperability Issues and Recommendations 57 3.1. Accessibility 59 This section describes the issues related to access to servers and 60 server resources. Concerns here include data sharing and maintenance 61 of client/server connections. 63 3.1.1. Multiple Accesses of the Same Mailbox 65 One strong point of IMAP4 is that, unlike POP3, it allows for 66 multiple simultaneous access to a single mailbox. A user can, thus, 67 read mail from a client at home while the client in the office is 68 still connected; or the help desk staff can all work out of the same 69 inbox, all seeing the same pool of questions. An important point 70 about this capability, though is that NO SERVER IS GUARANTEED TO 71 SUPPORT THIS. If you are selecting an IMAP server and this facility 72 is important to you, be sure that the server you choose to install, 73 in the configuration you choose to use, supports it. 75 If you are designing a client, you MUST NOT assume that you can 76 access the same mailbox more than once at a time. That means 77 1. you MUST handle gracefully the failure of a SELECT command if 78 the server refuses the second SELECT, 79 2. you MUST handle reasonably the severing of your connection (see 80 "Severed Connections", below) if the server chooses to allow the 81 second SELECT by forcing the first off, 82 3. you MUST avoid making multiple connections to the same mailbox 83 in your own client (for load balancing or other such reasons), 84 and 85 4. you MUST avoid using the STATUS command on a mailbox that you 86 have selected (with some server implementations the STATUS 87 command has the same problems with multiple access as do the 88 SELECT and EXAMINE commands). 90 A further note about STATUS: The STATUS command is sometimes used to 91 check a non-selected mailbox for new mail. This mechanism MUST NOT 92 be used to check for new mail in the selected mailbox; section 5.2 of 93 [RFC-2060] specifically forbids this in its last paragraph. Further, 94 since STATUS takes a mailbox name it is an independent operation, not 95 operating on the selected mailbox. Because of this, the information 96 it returns is not necessarily in synchronization with the selected 97 mailbox state. 99 3.1.2. Severed Connections 101 The client/server connection may be severed for one of three reasons: 102 the client severs the connection, the server severs the connection, 103 or the connection is severed by outside forces beyond the control of 104 the client and the server (a telephone line drops, for example). 105 Clients and servers must both deal with these situations. 107 When the client wants to sever a connection, it's usually because it 108 has finished the work it needed to do on that connection. The client 109 SHOULD send a LOGOUT command, wait for the tagged response, and then 110 close the socket. But note that, while this is what's intended in 111 the protocol design, there isn't universal agreement here. Some 112 contend that sending the LOGOUT and waiting for the two responses 113 (untagged BYE and tagged OK) is wasteful and unnecessary, and that 114 the client can simply close the socket. The server should interpret 115 the closed socket as a log out by the client. The counterargument is 116 that it's useful from the standpoint of cleanup, problem 117 determination, and the like, to have an explicit client log out, 118 because otherwise there is no way for the server to tell the 119 difference between "closed socket because of log out" and "closed 120 socket because communication was disrupted". If there is a 121 client/server interaction problem, a client which routinely 122 terminates a session by breaking the connection without a LOGOUT will 123 make it much more difficult to determine the problem. 125 Because of this disagreement, server designers must be aware that 126 some clients might close the socket without sending a LOGOUT. In any 127 case, whether or not a LOGOUT was sent, the server SHOULD NOT 128 implicitly expunge any messages from the selected mailbox. If a 129 client wants the server to do so, it MUST send a CLOSE or EXPUNGE 130 command explicitly. 132 When the server wants to sever a connection it's usually due to an 133 inactivity timeout or is because a situation has arisen that has 134 changed the state of the mail store in a way that the server can not 135 communicate to the client. The server SHOULD send an untagged BYE 136 response to the client and then close the socket. Sending an 137 untagged BYE response before severing allows the server to send a 138 human-readable explanation of the problem to the client, which the 139 client may then log, display to the user, or both (see section 7.1.5 140 of [RFC-2060]). 141 Regarding inactivity timeouts, there is some controversy. Unlike 142 POP, for which the design is for a client to connect, retrieve mail, 143 and log out, IMAPs design encourages long-lived (and mostly 144 inactive) client/server sessions. As the number of users grows, this 145 can use up a lot of server resources, especially with clients that 146 are designed to maintain sessions for mailboxes that the user has 147 finished accessing. To alleviate this, a server MAY implement an 148 inactivity timeout, unilaterally closing a session (after first 149 sending an untagged BYE, as noted above). Some server operators have 150 reported dramatic improvements in server performance after doing 151 this. As specified in [RFC-2060], if such a timeout is done it MUST 152 NOT be until at least 30 minutes of inactivity. The reason for this 153 specification is to prevent clients from sending commands (such as 154 NOOP) to the server at frequent intervals simply to avert a too-early 155 timeout. If the client knows that the server may not time out the 156 session for at least 30 minutes, then the client need not poll at 157 intervals more frequent than, say, 25 minutes. 159 3.2. Scaling 161 IMAP4 has many features that allow for scalability, as mail stores 162 become larger and more numerous. Large numbers of users, mailboxes, 163 and messages, and very large messages require thought to handle 164 efficiently. This document will not address the administrative 165 issues involved in large numbers of users, but we will look at the 166 other items. 168 3.2.1. Flood Control 170 There are three situations when a client can make a request that will 171 result in a very large response - too large for the client reasonably 172 to deal with: there are a great many mailboxes available, there are a 173 great many messages in the selected mailbox, or there is a very large 174 message part. The danger here is that the end user will be stuck 175 waiting while the server sends (and the client processes) an enormous 176 response. In all of these cases there are things a client can do to 177 reduce that danger. 179 There is also the case where a client can flood a server, by sending 180 an arbitratily long command. We'll discuss that issue, too, in this 181 section. 183 3.2.1.1. Listing Mailboxes 185 Some servers present Usenet newsgroups to IMAP users. Newsgroups, 186 and other such hierarchical mailbox structures, can be very numerous 187 but may have only a few entries at the top level of hierarchy. Also, 188 some servers are built against mail stores that can, unbeknownst to 189 the server, have circular hierarchies - that is, it's possible for 190 "a/b/c/d" to resolve to the same file structure as "a", which would 191 then mean that "a/b/c/d/b" is the same as "a/b", and the hierarchy 192 will never end. The LIST response in this case will be unlimited. 194 Clients that will have trouble with this are those that use 195 C: 001 LIST "" * 196 to determine the mailbox list. Because of this, clients SHOULD NOT 197 use an unqualified "*" that way in the LIST command. A safer 198 approach is to list each level of hierarchy individually, allowing 199 the user to traverse the tree one limb at a time, thus: 201 C: 001 LIST "" % 202 S: * LIST () "/" Banana 203 S: * LIST ...etc... 204 S: 001 OK done 205 and then 206 C: 002 LIST "" Banana/% 207 S: * LIST () "/" Banana/Apple 208 S: * LIST ...etc... 209 S: 002 OK done 211 Using this technique the client's user interface can give the user 212 full flexibility without choking on the voluminous reply to "LIST *". 213 Of course, it is still possible that the reply to 214 C: 005 LIST "" alt.fan.celebrity.% 215 may be thousands of entries long, and there is, unfortunately, 216 nothing the client can do to protect itself from that. This has not 217 yet been a notable problem. 219 Servers that may export circular hierarchies (any server that 220 directly presents a UNIX file system, for instance) SHOULD limit the 221 hierarchy depth to prevent unlimited LIST responses. A suggested 222 depth limit is 20 hierarchy levels. 224 3.2.1.2. Fetching the List of Messages 226 When a client selects a mailbox, it is given a count, in the untagged 227 EXISTS response, of the messages in the mailbox. This number can be 228 very large. In such a case it might be unwise to use 229 C: 004 FETCH 1:* ALL 230 to populate the user's view of the mailbox. One good method to avoid 231 problems with this is to batch the requests, thus: 233 C: 004 FETCH 1:50 ALL 234 S: * 1 FETCH ...etc... 235 S: 004 OK done 236 C: 005 FETCH 51:100 ALL 237 S: * 51 FETCH ...etc... 238 S: 005 OK done 239 C: 006 FETCH 101:150 ALL 240 ...etc... 242 Using this method, another command, such as "FETCH 6 BODY[1]" can be 243 inserted as necessary, and the client will not have its access to the 244 server blocked by a storm of FETCH replies. (Such a method could be 245 reversed to fetch the LAST 50 messages first, then the 50 prior to 246 that, and so on.) 248 As a smart extension of this, a well designed client, prepared for 249 very large mailboxes, will not automatically fetch data for all 250 messages AT ALL. Rather, the client will populate the user's view 251 only as the user sees it, possibly pre-fetching selected information, 252 and only fetching other information as the user scrolls to it. For 253 example, to select only those messages beginning with the first 254 unseen one: 256 C: 003 SELECT INBOX 257 S: * 10000 EXISTS 258 S: * 80 RECENT 259 S: * FLAGS (\Answered \Flagged \Deleted \Draft \Seen) 260 S: * OK [UIDVALIDITY 824708485] UID validity status 261 S: * OK [UNSEEN 9921] First unseen message 262 S: 003 OK [READ-WRITE] SELECT completed 263 C: 004 FETCH 9921:* ALL 264 ... etc... 266 If the server does not return an OK [UNSEEN] response, the client may 267 use SEARCH UNSEEN to obtain that value. 269 This mechanism is good as a default presentation method, but only 270 works well if the default message order is acceptable. A client may 271 want to present various sort orders to the user (by subject, by date 272 sent, by sender, and so on) and in that case (lacking a SORT 273 extension on the server side) the client WILL have to retrieve all 274 message descriptors. A client that provides this service SHOULD NOT 275 do it by default and SHOULD inform the user of the costs of choosing 276 this option for large mailboxes. 278 3.2.1.3. Fetching a Large Body Part 280 The issue here is similar to the one for a list of messages. In the 281 BODYSTRUCTURE response the client knows the size, in bytes, of the 282 body part it plans to fetch. Suppose this is a 70 MB video clip. 283 The client can use partial fetches to retrieve the body part in 284 pieces, avoiding the problem of an uninterruptible 70 MB literal 285 coming back from the server: 287 C: 022 FETCH 3 BODY[1]<0.20000> 288 S: * 3 FETCH (FLAGS(\Seen) BODY[1]<0> {20000} 289 S: ...data...) 290 S: 022 OK done 291 C: 023 FETCH 3 BODY[1]<20001.20000> 292 S: * 3 FETCH (BODY[1]<20001> {20000} 293 S: ...data...) 294 S: 023 OK done 295 C: 024 FETCH 3 BODY[1]<40001.20000> 296 ...etc... 298 3.2.1.4. BODYSTRUCTURE vs. Entire Messages 300 Because FETCH BODYSTRUCTURE is necessary in order to determine the 301 number of body parts, and, thus, whether a message has "attachments", 302 clients often use FETCH FULL as their normal method of populating the 303 user's view of a mailbox. The benefit is that the client can display 304 a paperclip icon or some such indication along with the normal 305 message summary. However, this comes at a significant cost with some 306 server configurations. The parsing needed to generate the FETCH 307 BODYSTRUCTURE response may be time-consuming compared with that 308 needed for FETCH ENVELOPE. The client developer should consider this 309 issue when deciding whether the ability to add a paperclip icon is 310 worth the tradeoff in performance, especially with large mailboxes. 312 Some clients, rather than using FETCH BODYSTRUCTURE, use FETCH BODY[] 313 (or the equivalent FETCH RFC822) to retrieve the entire message. 314 They then do the MIME parsing in the client. This may give the 315 client slightly more flexibility in some areas (access, for instance, 316 to header fields that aren't returned in the BODYSTRUCTURE and 317 ENVELOPE responses), but it can cause severe performance problems by 318 forcing the transfer of all body parts when the user might only want 319 to see some of them - a user logged on by modem and reading a small 320 text message with a large ZIP file attached may prefer to read the 321 text only and save the ZIP file for later. Therefore, a client 322 SHOULD NOT normally retrieve entire messages and SHOULD retrieve 323 message body parts selectively. 325 3.2.1.5. Long Command Lines 327 A client can wind up building a very long command line in an effort 328 to try to be efficient about requesting information from a server. 329 This can typically happen when a client builds a message set from 330 selected messages and doesn't recognise that contiguous blocks of 331 messages may be group in a range. Suppose a user selects all 10,000 332 messages in a large mailbox and then unselects message 287. The 333 client could build that message set as "1:286,288:10000", but a 334 client that doesn't handle that might try to enumerate each message 335 individually and build "1,2,3,4, [and so on] ,9999,10000". Adding 336 that to the fetch command results in a command line that's almost 337 49,000 octets long, and, clearly, one can construct a command line 338 that's even longer. 340 A client SHOULD limit the length of the command lines it generates to 341 approximately 1000 octets (including all quoted strings but not 342 including literals). If the client is unable to group things into 343 ranges so that the command line is within that length, it SHOULD 344 split the request into multiple commands. The client SHOULD use 345 literals instead of long quoted strings, in order to keep the command 346 length down. 348 For its part, a server SHOULD allow for a command line of at least 349 8000 octets. This provides plenty of leeway for accepting reasonable 350 length commands from clients. The server SHOULD send a BAD response 351 to a command that does not end within the server's maximum accepted 352 command length. 354 3.2.2. Subscriptions 356 The client isn't the only entity that can get flooded: the end user, 357 too, may need some flood control. The IMAP4 protocol provides such 358 control in the form of subscriptions. Most servers support the 359 SUBSCRIBE, UNSUBSCRIBE, and LSUB commands, and many users choose to 360 narrow down a large list of available mailboxes by subscribing to the 361 ones that they usually want to see. Clients, with this in mind, 362 SHOULD give the user a way to see only subscribed mailboxes. A 363 client that never uses the LSUB command takes a significant usability 364 feature away from the user. Of course, the client would not want to 365 hide the LIST command completely; the user needs to have a way to 366 choose between LIST and LSUB. The usual way to do this is to provide 367 a setting like "show which mailboxes?: [] all [] subscribed only". 369 3.2.3. Searching 371 IMAP SEARCH commands can become particularly troublesome (that is, 372 slow) on mailboxes containing a large number of messages. So let's 373 put a few things in perspective in that regard. 375 The flag searches SHOULD be fast. The flag searches (ALL, [UN]SEEN, 376 [UN]ANSWERED, [UN]DELETED, [UN]DRAFT, [UN]FLAGGED, NEW, OLD, RECENT) 377 are known to be used by clients for the client's own use (for 378 instance, some clients use "SEARCH UNSEEN" to find unseen mail and 379 "SEARCH DELETED" to warn the user before expunging messages). 381 Other searches, particularly the text searches (HEADER, TEXT, BODY) 382 are initiated by the user, rather than by the client itself, and 383 somewhat slower performance can be tolerated, since the user is aware 384 that the search is being done (and is probably aware that it might be 385 time-consuming). A smart server might use dynamic indexing to speed 386 commonly used text searches. 388 The client MAY allow other commands to be sent to the server while a 389 SEARCH is in progress, but at the time of this writing there is 390 little or no server support for parallel processing of multiple 391 commands in the same session (and see "Multiple Accesses of the Same 392 Mailbox" above for a description of the dangers of trying to work 393 around this by doing your SEARCH in another session). 395 Another word about text searches: some servers, built on database 396 back-ends with indexed search capabilities, may return search results 397 that do not match the IMAP spec's "case-insensitive substring" 398 requirements. While these servers are in violation of the protocol, 399 there is little harm in the violation as long as the search results 400 are used only in response to a user's request. Still, developers of 401 such servers should be aware that they ARE violating the protocol, 402 should think carefully about that behaviour, and MUST be certain that 403 their servers respond accurately to the flag searches for the reasons 404 outlined above. 406 In addition, servers SHOULD support CHARSET UTF-8 [UTF-8] in 407 searches. 409 3.3 Avoiding Invalid Requests 411 IMAP4 provides ways for a server to tell a client in advance what is 412 and isn't permitted in some circumstances. Clients SHOULD use these 413 features to avoid sending requests that a well designed client would 414 know to be invalid. This section explains this in more detail. 416 3.3.1. The CAPABILITY Command 418 All IMAP4 clients SHOULD use the CAPABILITY command to determine what 419 version of IMAP and what optional features a server supports. The 420 client SHOULD NOT send IMAP4rev1 commands and arguments to a server 421 that does not advertize IMAP4rev1 in its CAPABILITY response. 422 Similarly, the client SHOULD NOT send IMAP4 commands that no longer 423 exist in IMAP4rev1 to a server that does not advertize IMAP4 in its 424 CAPABILITY response. An IMAP4rev1 server is NOT required to support 425 obsolete IMAP4 or IMAP2bis commands (though some do; do not let this 426 fact lull you into thinking that it's valid to send such commands to 427 an IMAP4rev1 server). 429 A client SHOULD NOT send commands to probe for the existance of 430 certain extensions. All standard and standards-track extensions 431 include CAPABILITY tokens indicating their presense. All private and 432 experimental extensions SHOULD do the same, and clients that take 433 advantage of them SHOULD use the CAPABILITY response to determine 434 whether they may be used or not. 436 3.3.2. Don't Do What the Server Says You Can't 438 In many cases, the server, in response to a command, will tell the 439 client something about what can and can't be done with a particular 440 mailbox. The client SHOULD pay attention to this information and 441 SHOULD NOT try to do things that it's been told it can't do. 442 Examples: 443 * Do not try to SELECT a mailbox that has the \Noselect flag set. 444 * Do not try to CREATE a sub-mailbox in a mailbox that has the 445 \Noinferiors flag set. 446 * Do not respond to a failing COPY or APPEND command by trying to 447 CREATE the target mailbox if the server does not respond with a 448 [TRYCREATE] response code. 449 * Do not try to expunge a mailbox that has been selected with the 450 [READ-ONLY] response code. 452 3.4. Miscellaneous Protocol Considerations 454 We describe here a number of important protocol-related issues, the 455 misunderstanding of which has caused significant interoperability 456 problems in IMAP4 implementations. One general item is that every 457 implementer should be certain to take note of and to understand 458 section 2.2.2 and the preamble to section 7 of the IMAP4rev1 spec 459 [RFC-2060]. 461 3.4.1. Well Formed Protocol 463 We cannot stress enough the importance of adhering strictly to the 464 protocol grammar. The specification of the protocol is quite rigid; 465 do not assume that you can insert blank space for "readability" if 466 none is called for. Keep in mind that there are parsers out there 467 that will crash if there are protocol errors. There are clients that 468 will report every parser burp to the user. And in any case, 469 information that cannot be parsed is information that is lost. Be 470 careful in your protocol generation. And see "A Word About Testing", 471 below. 473 In particular, note that the string in the INTERNALDATE response is 474 NOT an RFC-822 date string - that is, it is not in the same format as 475 the first string in the ENVELOPE response. Since most clients will, 476 in fact, accept an RFC-822 date string in the INTERNALDATE response, 477 it's easy to miss this in your interoperability testing. But it will 478 cause a problem with some client, so be sure to generate the correct 479 string for this field. 481 3.4.2. Special Characters 483 Certain characters, currently the double-quote and the backslash, may 484 not be sent as-is inside a quoted string. These characters MUST be 485 preceded by the escape character if they are in a quoted string, or 486 else the string MUST be sent as a literal. Both clients and servers 487 MUST handle this, both on output (they MUST send these characters 488 properly) and on input (they MUST be able to receive escaped 489 characters in quoted strings). Example: 491 C: 001 LIST "" % 492 S: * LIST () "" INBOX 493 S: * LIST () "\\" TEST 494 S: * LIST () "\\" {12} 495 S: "My" mailbox 496 S: 001 OK done 497 C: 002 LIST "" "\"My\" mailbox\\%" 498 S: * LIST () "\\" {17} 499 S: "My" mailbox\Junk 500 S: 002 OK done 502 Note that in the example the server sent the hierarchy delimiter as 503 an escaped character in the quoted string and sent the mailbox name 504 containing imbedded double-quotes as a literal. The client used only 505 quoted strings, escaping both the backslash and the double-quote 506 characters. 508 The CR and LF characters may be sent ONLY in literals; they are not 509 allowed, even if escaped, inside quoted strings. 511 And while we're talking about special characters: the IMAP spec, in 512 the section titled "Mailbox International Naming Convention", 513 describes how to encode mailbox names in modified UTF-7 [UTF-7 and 514 RFC-2060]. Implementations MUST adhere to this in order to be 515 interoperable in the international market, and servers SHOULD 516 validate mailbox names sent by client and reject names that do not 517 conform. 519 As to special characters in userids and passwords: clients MUST NOT 520 restrict what a user may type in for a userid or a password. The 521 formal grammar specifies that these are "astrings", and an astring 522 can be a literal. A literal, in turn can contain any 8-bit 523 character, and clients MUST allow users to enter all 8-bit characters 524 here, and MUST pass them, unchanged, to the server (being careful to 525 send them as literals when necessary). In particular, some server 526 configurations use "@" in user names, and some clients do not allow 527 that character to be entered; this creates a severe interoperability 528 problem. 530 3.4.3. UIDs and UIDVALIDITY 532 Servers that support existing back-end mail stores often have no good 533 place to save UIDs for messages. Often the existing mail store will 534 not have the concept of UIDs in the sense that IMAP has: strictly 535 increasing, never re-issued, 32-bit integers. Some servers solve 536 this by storing the UIDs in a place that's accessible to end users, 537 allowing for the possibility that the users will delete them. Others 538 solve it by re-assigning UIDs every time a mailbox is selected. 540 The server SHOULD maintain UIDs permanently for all messages if it 541 can. If that's not possible, the server MUST change the UIDVALIDITY 542 value for the mailbox whenever any of the UIDs may have become 543 invalid. Clients MUST recognize that the UIDVALIDITY has changed and 544 MUST respond to that condition by throwing away any information that 545 they have saved about UIDs in that mailbox. There have been many 546 problems in this area when clients have failed to do this; in the 547 worst case it will result in loss of mail when a client deletes the 548 wrong piece of mail by using a stale UID. 550 It seems to be a common misunderstanding that "the UIDVALIDITY and 551 the UID, taken together, form a 64-bit identifier that uniquely 552 identifies a message on a server". This is absolutely NOT TRUE. 553 There is no assurance that the UIDVALIDITY values of two mailboxes be 554 different, so the UIDVALIDITY in no way identifies a mailbox. The 555 ONLY purpose of UIDVALIDITY is, as its name indicates, to give the 556 client a way to check the validity of the UIDs it has cached. While 557 it is a valid implementation choice to put these values together to 558 make a 64-bit identifier for the message, the important concept here 559 is that UIDs are not unique between mailboxes; they are only unique 560 WITHIN a given mailbox. 562 Some server implementations have attempted to make UIDs unique across 563 the entire server. This is inadvisable, in that it limits the life 564 of UIDs unnecessarily. The UID is a 32-bit number and will run out 565 in reasonably finite time if it's global across the server. If you 566 assign UIDs sequentially in one mailbox, you will not have to start 567 re-using them until you have had, at one time or another, 2**32 568 different messages in that mailbox. In the global case, you will 569 have to reuse them once you have had, at one time or another, 2**32 570 different messages in the entire mail store. Suppose your server has 571 around 8000 users registered (2**13). That gives an average of 2**19 572 UIDs per user. Suppose each user gets 32 messages (2**5) per day. 573 That gives you 2**14 days (16000+ days = about 45 years) before you 574 run out. That may seem like enough, but multiply the usage just a 575 little (a lot of spam, a lot of mailing list subscriptions, more 576 users) and you limit yourself too much. 578 What's worse is that if you have to wrap the UIDs, and, thus, you 579 have to change UIDVALIDITY and invalidate the UIDs in the mailbox, 580 you have to do it for EVERY mailbox in the system, since they all 581 share the same UID pool. If you assign UIDs per mailbox and you have 582 a problem, you only have to kill the UIDs for that one mailbox. 584 Under extreme circumstances (and this is extreme, indeed), the server 585 may have to invalidate UIDs while a mailbox is in use by a client - 586 that is, the UIDs that the client knows about in its active mailbox 587 are no longer valid. In that case, the server MUST immediately 588 change the UIDVALIDITY and MUST communicate this to the client. The 589 server MAY do this by sending an unsolicited UIDVALIDITY message, in 590 the same form as in response to the SELECT command. Clients MUST be 591 prepared to handle such a message and the possibly coincident failure 592 of the command in process. For example: 594 C: 032 UID STORE 382 +Flags.silent \Deleted 595 S: * OK [UIDVALIDITY 12345] New UIDVALIDITY value! 596 S: 032 NO UID command rejected because UIDVALIDITY changed! 597 C: ...invalidates local information and re-fetches... 598 C: 033 FETCH 1:* UID 599 ...etc... 601 At the time of the writing of this document, the only server known to 602 do this does so only under the following condition: the client 603 selects INBOX, but there is not yet a physical INBOX file created. 604 Nonetheless, the SELECT succeeds, exporting an empty INBOX with a 605 temporary UIDVALIDITY of 1. While the INBOX remains selected, mail 606 is delivered to the user, which creates the real INBOX file and 607 assigns a permanent UIDVALIDITY (that is likely not to be 1). The 608 server reports the change of UIDVALIDITY, but as there were no 609 messages before, so no UIDs have actually changed, all the client 610 must do is accept the change in UIDVALIDITY. 612 Alternatively, a server may force the client to re-select the 613 mailbox, at which time it will obtain a new UIDVALIDITY value. To do 614 this, the server closes this client session (see "Severed 615 Connections" above) and the client then reconnects and gets back in 616 synch. Clients MUST be prepared for either of these behaviours. 618 We do not know of, nor do we anticipate the future existance of, a 619 server that changes UIDVALIDITY while there are existing messages, 620 but clients MUST be prepared to handle this eventuality. 622 3.4.4. FETCH Responses 624 When a client asks for certain information in a FETCH command, the 625 server MAY return the requested information in any order, not 626 necessarily in the order that it was requested. Further, the server 627 MAY return the information in separate FETCH responses and MAY also 628 return information that was not explicitly requested (to reflect to 629 the client changes in the state of the subject message). Some 630 examples: 632 C: 001 FETCH 1 UID FLAGS INTERNALDATE 633 S: * 5 FETCH (FLAGS (\Deleted)) 634 S: * 1 FETCH (FLAGS (\Seen) INTERNALDATE "..." UID 345) 635 S: 001 OK done 636 (In this case, the responses are in a different order. Also, the 637 server returned a flag update for message 5, which wasn't part of the 638 client's request.) 640 C: 002 FETCH 2 UID FLAGS INTERNALDATE 641 S: * 2 FETCH (INTERNALDATE "...") 642 S: * 2 FETCH (UID 399) 643 S: * 2 FETCH (FLAGS ()) 644 S: 002 OK done 645 (In this case, the responses are in a different order and were 646 returned in separate responses.) 648 C: 003 FETCH 2 BODY[1] 649 S: * 2 FETCH (FLAGS (\Seen) BODY[1] {14} 650 S: Hello world! 651 S: ) 652 S: 003 OK done 653 (In this case, the FLAGS response was added by the server, since 654 fetching the body part caused the server to set the \Seen flag.) 656 Because of this characteristic a client MUST be ready to receive any 657 FETCH response at any time and should use that information to update 658 its local information about the message to which the FETCH response 659 refers. A client MUST NOT assume that any FETCH responses will come 660 in any particular order, or even that any will come at all. If after 661 receiving the tagged response for a FETCH command the client finds 662 that it did not get all of the information requested, the client 663 SHOULD send a NOOP command to the server to ensure that the server 664 has an opportunity to send any pending EXPUNGE responses to the 665 client (see [RFC-2180]). 667 3.4.5. RFC822.SIZE 669 Some back-end mail stores keep the mail in a canonical form, rather 670 than retaining the original MIME format of the messages. This means 671 that the server must reassemble the message to produce a MIME stream 672 when a client does a fetch such as RFC822 or BODY[], requesting the 673 entire message. It also may mean that the server has no convenient 674 way to know the RFC822.SIZE of the message. Often, such a server 675 will actually have to build the MIME stream to compute the size, only 676 to throw the stream away and report the size to the client. 678 When this is the case, some servers have chosen to estimate the size, 679 rather than to compute it precisely. Such an estimate allows the 680 client to display an approximate size to the user and to use the 681 estimate in flood control considerations (q.v.), but requires that 682 the client not use the size for things such as allocation of buffers, 683 because those buffers might then be too small to hold the actual MIME 684 stream. Instead, a client SHOULD use the size that's returned in the 685 literal when you fetch the data. 687 The protocol requires that the RFC822.SIZE value returned by the 688 server be EXACT. Estimating the size is a protocol violation, and 689 server designers must be aware that, despite the performance savings 690 they might realize in using an estimate, this practice will cause 691 some clients to fail in various ways. If possible, the server SHOULD 692 compute the RFC822.SIZE for a particular message once, and then save 693 it for later retrieval. If that's not possible, the server MUST 694 compute the value exactly every time. Incorrect estimates do cause 695 severe interoperability problems with some clients. 697 3.4.6. Expunged Messages 699 If the server allows multiple connections to the same mailbox, it is 700 often possible for messages to be expunged in one client unbeknownst 701 to another client. Since the server is not allowed to tell the 702 client about these expunged messages in response to a FETCH command, 703 the server may have to deal with the issue of how to return 704 information about an expunged message. There was extensive 705 discussion about this issue, and the results of that discussion are 706 summarized in [RFC-2180]. See that reference for a detailed 707 explanation and for recommendations. 709 3.4.7. The Namespace Issue 711 Namespaces are a very muddy area in IMAP4 implementation right now 712 (see [NAMESPACE] for a proposal to clear the water a bit). Until the 713 issue is resolved, the important thing for client developers to 714 understand is that some servers provide access through IMAP to more 715 than just the user's personal mailboxes, and, in fact, the user's 716 personal mailboxes may be "hidden" somewhere in the user's default 717 hierarchy. The client, therefore, SHOULD provide a setting wherein 718 the user can specify a prefix to be used when accessing mailboxes. 719 If the user's mailboxes are all in "~/mail/", for instance, then the 720 user can put that string in the prefix. The client would then put 721 the prefix in front of any name pattern in the LIST and LSUB 722 commands: 723 C: 001 LIST "" ~/mail/% 724 (See also "Reference Names in the LIST Command" below.) 726 3.4.8. Creating Special-Use Mailboxes 728 It may seem at first that this is part of the namespace issue; it is 729 not, and is only indirectly related to it. A number of clients like 730 to create special-use mailboxes with particular names. Most 731 commonly, clients with a "trash folder" model of message deletion 732 want to create a mailbox with the name "Trash" or "Deleted". Some 733 clients want to create a "Drafts" mailbox, an "Outbox" mailbox, or a 734 "Sent Mail" mailbox. And so on. There are two major 735 interoperability problems with this practice: 736 1. different clients may use different names for mailboxes with 737 similar functions (such as "Trash" and "Deleted"), or may manage the 738 same mailboxes in different ways, causing problems if a user switches 739 between clients and 740 2. there is no guarantee that the server will allow the creation of 741 the desired mailbox. 743 The client developer is, therefore, well advised to consider 744 carefully the creation of any special-use mailboxes on the server, 745 and, further, the client MUST NOT require such mailbox creation - 746 that is, if you do decide to do this, you MUST handle gracefully the 747 failure of the CREATE command and behave reasonably when your 748 special-use mailboxes do not exist and can not be created. 750 In addition, the client developer SHOULD provide a convenient way for 751 the user to select the names for any special-use mailboxes, allowing 752 the user to make these names the same in all clients used and to put 753 them where the user wants them. 755 3.4.9. Reference Names in the LIST Command 757 Many implementers of both clients and servers are confused by the 758 "reference name" on the LIST command. The reference name is intended 759 to be used in much the way a "cd" (change directory) command is used 760 on Unix, PC DOS, Windows, and OS/2 systems. That is, the mailbox 761 name is interpreted in much the same way as a file of that name would 762 be found if one had done a "cd" command into the directory specified 763 by the reference name. For example, in Unix we have the following: 765 > cd /u/jones/junk 766 > vi banana [file is "/u/jones/junk/banana"] 767 > vi stuff/banana [file is "/u/jones/junk/stuff/banana"] 768 > vi /etc/hosts [file is "/etc/hosts"] 770 In the past, there have been several interoperability problems with 771 this. First, while some IMAP servers are built on Unix or PC file 772 systems, many others are not, and the file system semantics do not 773 make sense in those configurations. Second, while some IMAP servers 774 expose the underlying file system to the clients, others allow access 775 only to the user's personal mailboxes, or to some other limited set 776 of files, making such file-system-like semantics less meaningful. 777 Third, because the IMAP spec leaves the interpretation of the 778 reference name as "implementation-dependent", in the past the various 779 server implementations handled it in vastly differing ways. 781 The following recommendations are the result of significant 782 operational experience, and are intended to maximize 783 interoperability. 785 Server implementations MUST implement the reference argument in a way 786 that matches the intended "change directory" operation as closely as 787 possible. As a minimum implementation, the reference argument may be 788 prepended to the mailbox name (while suppressing double delimiters; 789 see the next paragraph). Even servers that do not provide a way to 790 break out of the current hierarchy (see "breakout facility" below) 791 MUST provide a reasonable implementation of the reference argument, 792 as described here, so that they will interoperate with clients that 793 use it. 795 Server implementations that prepend the reference argument to the 796 mailbox name SHOULD insert a hierarchy delimiter between them, and 797 MUST NOT insert a second if one is already present: 799 C: A001 LIST ABC DEF 800 S: * LIST () "/" ABC/DEF <=== SHOULD do this 801 S: A001 OK done 803 C: A002 LIST ABC/ /DEF 804 S: * LIST () "/" ABC//DEF <=== MUST NOT do this 805 S: A002 OK done 807 On clients, the reference argument is chiefly used to implement a 808 "breakout facility", wherein the user may directly access a mailbox 809 outside the "current directory" hierarchy. Client implementations 810 SHOULD have an operational mode that does not use the reference 811 argument. This is to interoperate with older servers that did not 812 implement the reference argument properly. While it's a good idea to 813 give the user access to a breakout facility, clients that do not 814 intend to do so SHOULD NOT use the reference argument at all. 816 Client implementations SHOULD always place a trailing hierarchy 817 delimiter on the reference argument. This is because some servers 818 prepend the reference argument to the mailbox name without inserting 819 a hierarchy delimiter, while others do insert a hierarchy delimiter 820 if one is not already present. A client that puts the delimiter in 821 will work with both varieties of server. 823 Client implementations that implement a breakout facility SHOULD 824 allow the user to choose whether or not to use a leading hierarchy 825 delimiter on the mailbox argument. This is because the handling of a 826 leading mailbox hierarchy delimiter also varies from server to 827 server, and even between different mailstores on the same server. In 828 some cases, a leading hierarchy delimiter means "discard the 829 reference argument" (implementing the intended breakout facility), 830 thus: 832 C: A001 LIST ABC/ /DEF 833 S: * LIST () "/" /DEF 834 S: A001 OK done 836 In other cases, however, the two are catenated and the extra 837 hierarchy delimiter is discarded, thus: 839 C: A001 LIST ABC/ /DEF 840 S: * LIST () "/" ABC/DEF 841 S: A001 OK done 843 Client implementations MUST NOT assume that the server supports a 844 breakout facility, but MAY provide a way for the user to use one if 845 it is available. Any breakout facility should be exported to the 846 user interface. Note that there may be other "breakout" characters 847 besides the hierarchy delimiter (for instance, UNIX filesystem 848 servers are likely to use a leading "~" as well), and that their 849 interpretation is server-dependent. 851 3.4.12. Mailbox Hierarchy Delimiters 853 The server's selection of what to use as a mailbox hierarchy 854 delimiter is a difficult one, involving several issues: What 855 characters do users expect to see? What characters can they enter 856 for a hierarchy delimiter if it is desired (or required) that the 857 user enter it? What character can be used for the hierarchy 858 delimiter, noting that the chosen character can not otherwise be used 859 in the mailbox name? 861 Because some interfaces show users the hierarchy delimiters or allow 862 users to enter qualified mailbox names containing them, server 863 implementations SHOULD use delimiter characters that users generally 864 expect to see as name separators. The most common characters used 865 for this are "/" (as in Unix file names), "\" (as in OS/2 and Windows 866 file names), and "." (as in news groups). There is little to choose 867 among these apart from what users may expect or what is dictated by 868 the underlying file system, if any. One consideration about using 869 "\" is that it's also a special character in the IMAP protocol. 870 While the use of other hierarchy delimiter characters is permissible, 871 A DESIGNER IS WELL ADVISED TO STAY WITH ONE FROM THIS SET unless the 872 server is intended for special purposes only. Implementers might be 873 thinking about using characters such as "-", "_", ";", "&", "#", "@", 874 and "!", but they should be aware of the surprise to the user as well 875 as of the effect on URLs and other external specifications (since 876 some of these characters have special meanings there). Also, a 877 server that uses "\" (and clients of such a server) MUST remember to 878 escape that character in quoted strings or to send literals instead. 879 Literals are recommended over escaped characters in quoted strings in 880 order to maintain compatibility with older IMAP versions that did not 881 allow escaped characters in quoted strings (but check the grammar to 882 see where literals are allowed): 883 C: 001 LIST "" {13} 884 S: + send literal 885 C: this\%\%\%\h* 886 S: * LIST () "\\" {27} 887 S: this\is\a\mailbox\hierarchy 888 S: 001 OK LIST complete 890 In any case, a server SHOULD NOT use normal alpha-numeric characters 891 (such as "X" or "0") as delimiters; a user would be very surprised to 892 find that "EXPENDITURES" actually represented a two-level hierarchy. 893 And a server SHOULD NOT use characters that are non-printable or 894 difficult or impossible to enter on a standard US keyboard. Control 895 characters, box-drawing characters, and characters from non-US 896 alphabets fit into this category. Their use presents 897 interoperability problems that are best avoided. 899 The UTF-7 encoding of mailbox names also raises questions about what 900 to do with the hierarchy delimiters in encoded names: do we encode 901 each hierarchy level and separate them with delimiters, or do we 902 encode the fully qualified name, delimiters and all? The answer for 903 IMAP is the former: encode each hierarchy level separately, and 904 insert delimiters between. This makes it particularly important not 905 to use as a hierarchy delimiter a character that might cause 906 confusion with IMAP's modified UTF-7 [UTF-7 and RFC-2060] encoding. 908 To repeat: a server SHOULD use "/", "\", or "." as its hierarchy 909 delimiter. The use of any other character is likely to cause 910 problems and is STRONGLY DISCOURAGED. 912 3.4.11. ALERT Response Codes 914 The protocol spec is very clear on the matter of what to do with 915 ALERT response codes, and yet there are many clients that violate it 916 so it needs to be said anyway: "The human-readable text contains a 917 special alert that MUST be presented to the user in a fashion that 918 calls the user's attention to the message." That should be clear 919 enough, but I'll repeat it here: Clients MUST present ALERT text 920 clearly to the user. 922 3.4.12. Deleting Mailboxes 924 The protocol does not guarantee that a client may delete a mailbox 925 that is not empty, though on some servers it is permissible and is, 926 in fact, much faster than the alternative or deleting all the 927 messages from the client. If the client chooses to try to take 928 advantage of this possibility it MUST be prepared to use the other 929 method in the even that the more convenient one fails. Further, a 930 client SHOULD NOT try to delete the mailbox that it has selected, but 931 should first close that mailbox; some servers do not permit the 932 deletion of the selected mailbox. 934 That said, a server SHOULD permit the deletion of a non-empty 935 mailbox; there's little reason to pass this work on to the client. 936 Moreover, forbidding this prevents the deletion of a mailbox that for 937 some reason can not be opened or expunged, leading to possible 938 denial-of-service problems. 940 Example: 941 [User tells the client to delete mailbox BANANA, which is 942 currently selected...] 943 C: 008 CLOSE 944 S: 008 OK done 945 C: 009 DELETE BANANA 946 S: 009 NO Delete failed; mailbox is not empty. 947 C: 010 SELECT BANANA 948 S: * ... untagged SELECT responses 949 S: 010 OK done 950 C: 011 STORE 1:* +FLAGS.SILENT \DELETED 951 S: 011 OK done 952 C: 012 CLOSE 953 S: 012 OK done 954 C: 013 DELETE BANANA 955 S: 013 OK done 957 3.5. A Word About Testing 959 Since the whole point of IMAP is interoperability, and since 960 interoperability can not be tested in a vacuum, the final 961 recommendation of this treatise is, "Test against EVERYTHING." Test 962 your client against every server you can get an account on. Test 963 your server with every client you can get your hands on. Many 964 clients make limited test versions available on the Web for the 965 downloading. Many server owners will give serious client developers 966 guest accounts for testing. Contact them and ask. NEVER assume that 967 because your client works with one or two servers, or because your 968 server does fine with one or two clients, you will interoperate well 969 in general. 971 In particular, in addition to everything else, be sure to test 972 against the reference implementations: the PINE client, the 973 University of Washington server, and the Cyrus server. 975 See the following URLs on the web for more information here: 976 IMAP Products and Sources: http://www.imap.org/products.html 977 IMC MailConnect: http://www.imc.org/imc-mailconnect 979 4. Security Considerations 981 This document describes behaviour of clients and servers that use the 982 IMAP4 protocol, and as such, has the same security considerations as 983 described in [RFC-2060]. 985 5. References 987 [RFC-2060]; Crispin, M.; "Internet Message Access Protocol - Version 988 4rev1"; RFC 2060; University of Washington; December 1996. 990 [RFC-2119]; Bradner, S.; "Key words for use in RFCs to Indicate 991 Requirement Levels"; RFC 2119; Harvard University; March 1997. 993 [RFC-2180]; Gahrns, M.; "IMAP4 Multi-Accessed Mailbox Practice"; RFC 994 2180; Microsoft; July 1997. 996 [UTF-8]; Yergeau, F.; " UTF-8, a transformation format of Unicode and 997 ISO 10646"; RFC 2044; Alis Technilogies; October 1996. 999 [UTF-7]; Goldsmith, D. & Davis, M.; "UTF-7, a Mail-Safe 1000 Transformation Format of Unicode"; RFC 2152; Apple Computer, Inc. & 1001 Taligent, Inc.; May 1997. 1003 [NAMESPACE]; Gahrns, M. & Newman, C.; "IMAP4 Namespace"; draft 1004 document ; Microsoft & Innosoft; 1005 June 1997. 1007 6. Author's Address 1009 Barry Leiba 1010 IBM T.J. Watson Research Center 1011 30 Saw Mill River Road 1012 Hawthorne, NY 10532 1014 Phone: 1-914-784-7941 1015 Email: leiba@watson.ibm.com 1017 This document will expire at the end of October 1999.