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