idnits 2.17.1 draft-leiba-imap-implement-guide-00.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-25) 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. == 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 (September 1997) is 9719 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) -- Looks like a reference, but probably isn't: '1' on line 399 ** 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: 13 errors (**), 0 flaws (~~), 1 warning (==), 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-00.txt September 1997 6 IMAP4 Implementation Recommendations 8 Status of this Document 10 This document provides information for the Internet community. This 11 document does not specify an Internet standard of any kind. 12 Distribution of this document is unlimited. 14 This document is an Internet Draft. Internet Drafts are working 15 documents of the Internet Engineering Task Force (IETF), its Areas, 16 and its Working Groups. Note that other groups may also distribute 17 working documents as Internet Drafts. 19 Internet Drafts are draft documents valid for a maximum of six 20 months. Internet Drafts may be updated, replaced, or obsoleted by 21 other documents at any time. It is not appropriate to use Internet 22 Drafts as reference material or to cite them other than as a "working 23 draft" or "work in progress". 25 To learn the current status of any Internet-Draft, please check the 26 1id-abstracts.txt listing contained in the Internet-Drafts Shadow 27 Directories on ds.internic.net, nic.nordu.net, ftp.isi.edu, or 28 munnari.oz.au. 30 A revised version of this draft document will be submitted to the RFC 31 editor. Discussion and suggestions for improvement are requested. 32 This document will expire by the end of February 1998. 34 1. Abstract 36 The IMAP4 specification [RFC-2060] describes a rich protocol for use 37 in building clients and servers for storage, retrieval, and 38 manipulation of electronic mail. Because the protocol is so rich and 39 has so many implementation choices, there are often trade-offs that 40 must be made and issues that must be considered when designing such 41 clients and servers. This document attempts to outline these issues 42 and to make recommendations in order to make the end products as 43 interoperable as possible. 45 Internet DRAFT Implementation Recommendations September 1997 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), and 85 4. you must avoid using the STATUS command on a mailbox that you 86 have selected (with some server implementations the STATUS command 87 has the same problems with multiple access as do the SELECT and 88 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. 95 Internet DRAFT Implementation Recommendations September 1997 97 3.1.2. Severed Connections 99 The client/server connection may be severed for one of three reasons: 100 the client severs the connection, the server severs the connection, 101 or the connection is severed by outside forces beyond the control of 102 the client and the server (a telephone line drops, for example). 103 Clients and servers must both deal with these situations. 105 When the client wants to sever a connection, it's usually because it 106 has finished the work it needed to do on that connection. The client 107 SHOULD send a LOGOUT command, wait for the tagged response, and then 108 close the socket. But note that, while this is what's intended in 109 the protocol design, there isn't universal agreement here. Some 110 contend that sending the LOGOUT and waiting for the two responses 111 (untagged BYE and tagged OK) is wasteful and unnecessary, and that 112 the client can simply close the socket. The server should interpret 113 the closed socket as a log out by the client. The counterargument is 114 that it's useful from the standpoint of cleanup, problem 115 determination, and the like, to have an explicit client log out. 117 Because of this disagreement, server designers must be aware that 118 some clients might close the socket without sending a LOGOUT. In any 119 case, whether or not a LOGOUT was sent, the server SHOULD NOT 120 implicitly expunge any messages from the selected mailbox. If a 121 client wants the server to do so, it MUST send a CLOSE or EXPUNGE 122 command explicitly. 124 When the server wants to sever a connection it's usually due to an 125 inactivity timeout or is because a situation has arisen that has 126 changed the state of the mail store in a way that the server can not 127 communicate to the client. The server SHOULD send an untagged BYE 128 response to the client and then close the socket. Sending an 129 untagged BYE response before severing allows the server to send a 130 human-readable explanation of the problem to the client, which the 131 client may then log, display to the user, or both (see section 7.1.5 132 of [RFC-2060]). Note that the server MAY also choose to send an 133 untagged ALERT as well, if it wants to be sure that the client shows 134 the message to the user. The server designer should think carefully, 135 though, before making a decision that's better left to the client. 137 3.2. Scaling 139 IMAP4 has many features that allow for scalability, as mail stores 140 become larger and more numerous. Large numbers of users, mailboxes, 141 and messages, and very large messages require thought to handle 142 efficiently. This document will not address the administrative 144 Internet DRAFT Implementation Recommendations September 1997 146 issues involved in large numbers of users, but we will look at the 147 other items. 149 3.2.1. Flood Control 151 There are three situations when a client can make a request that will 152 result in a very large response - too large for the client reasonably 153 to deal with: there are a great many mailboxes available, there are a 154 great many messages in the selected mailbox, or there is a very large 155 message part. The danger here is that the end user will be stuck 156 waiting while the server sends (and the client processes) an enormous 157 response. In all of these cases there are things a client can do to 158 reduce that danger. 160 3.2.1.1. Listing Mailboxes 162 Some servers present Usenet newsgroups to IMAP users. Newsgroups, 163 and other such hierarchical mailbox structures, can be very numerous 164 but may have only a few entries at the top level of hierarchy. 165 Clients that will have trouble with this are those that use 166 C: 001 LIST "" * 167 to determine the mailbox list. Because of this, clients SHOULD NOT 168 use an unqualified "*" that way in the LIST command. A safer 169 approach is to list each level of hierarchy individually, allowing 170 the user to traverse the tree one limb at a time, thus: 172 C: 001 LIST "" % 173 S: * LIST () "/" Banana 174 S: * LIST ...etc... 175 S: 001 OK done 176 and hen 177 C: 002 LIST "" Banana/% 178 S: * LIST () "/" Banana/Apple 179 S: * LIST ...etc... 180 S: 002 OK done 182 Using this technique the client's user interface can give the user 183 full flexibility without choking on the voluminous reply to "LIST *". 184 Of course, it is still possible that the reply to 185 C: 005 LIST "" alt.fan.celebrity.% 186 may be thousands of entries long, and there is, unfortunately, 187 nothing the client can do to protect itself from that. This has not 188 yet been a notable problem. 190 Internet DRAFT Implementation Recommendations September 1997 192 3.2.1.2. Fetching the List of Messages 194 When a client selects a mailbox, it is given a count, in the untagged 195 EXISTS response, of the messages in the mailbox. This number can be 196 very large. In such a case it might be unwise to use 197 C: 004 FETCH 1:* ALL 198 to populate the user's view of the mailbox. A good method to avoid 199 problems with this is to batch the requests, thus: 201 C: 004 FETCH 1:50 ALL 202 S: * 1 FETCH ...etc... 203 S: 004 OK done 204 C: 005 FETCH 51:100 ALL 205 S: * 51 FETCH ...etc... 206 S: 005 OK done 207 C: 006 FETCH 101:150 ALL 208 ...etc... 210 Using this method, another command, such as "FETCH 6 BODY[1]" can be 211 inserted as necessary, and the client will not have its access to the 212 server blocked by a storm of FETCH replies. (Such a method could be 213 reversed to fetch the LAST 50 messages first, then the 50 prior to 214 that, and so on.) 216 3.2.1.3. Fetching a Large Body Part 218 The issue here is similar to the one for a list of messages. In the 219 BODYSTRUCTURE response the client knows the size, in bytes, of the 220 body part it plans to fetch. Suppose this is a 70 MB video clip. 221 The client can use partial fetches to retrieve the body part in 222 pieces, avoiding the problem of an uninterruptible 70 MB literal 223 coming back from the server: 225 C: 022 FETCH 3 BODY[1]<0.20000> 226 S: * 3 FETCH (FLAGS(\Seen) BODY[1]<0> {20000} 227 S: ...data...) 228 S: 022 OK done 229 C: 023 FETCH 3 BODY[1]<20001.20000> 230 S: * 3 FETCH (BODY[1]<20001> {20000} 231 S: ...data...) 232 S: 023 OK done 233 C: 024 FETCH 3 BODY[1]<40001.20000> 234 ...etc... 236 3.2.1.4. BODYSTRUCTURE vs. Entire Messages 238 Because FETCH BODYSTRUCTURE is necessary in order to determine the 240 Internet DRAFT Implementation Recommendations September 1997 242 number of body parts, and, thus, whether a message has "attachments", 243 clients often use FETCH FULL as their normal method of populating the 244 user's view of a mailbox. The benefit is that the client can display 245 a paperclip icon or some such indication along with the normal 246 message summary. However, this comes at a significant cost with some 247 server configurations. The parsing needed to generate the FETCH 248 BODYSTRUCTURE response may be time-consuming compared with that 249 needed for FETCH ENVELOPE. The client developer should consider this 250 issue when deciding whether the ability to add a paperclip icon is 251 worth the tradeoff in performance, especially with large mailboxes. 253 Some clients, rather than using FETCH BODYSTRUCTURE, use FETCH BODY[] 254 (or the equivalent FETCH RFC822) to retrieve the entire message. 255 They then do the MIME parsing in the client. This may give the 256 client slightly more flexibility in some areas (access, for instance, 257 to header fields that aren't returned in the BODYSTRUCTURE and 258 ENVELOPE responses), but it can cause severe performance problems by 259 forcing the transfer of all body parts when the user might only want 260 to see some of them - a user logged on by modem and reading a small 261 text message with a large ZIP file attached may prefer to read the 262 text only and save the ZIP file for later. Therefore, a client 263 SHOULD NOT normally retrieve entire messages and SHOULD retrieve 264 message body parts selectively. 266 3.2.2. Subscriptions 268 The client isn't the only entity that can get flooded: the end user, 269 too, may need some flood control. The IMAP4 protocol provides such 270 control in the form of subscriptions. Most servers support the 271 SUBSCRIBE, UNSUBSCRIBE, and LSUB commands, and many users choose to 272 narrow down a large list of available mailboxes by subscribing to the 273 ones that they usually want to see. Clients, with this in mind, 274 SHOULD give the user a way to see only subscribed mailboxes. A 275 client that never uses the LSUB command takes a significant usability 276 feature away from the user. Of course, the client would not want to 277 hide the LIST command completely; the user needs to be able to go 278 both ways. 280 3.2.3. Searching 282 IMAP SEARCH commands can become particularly troublesome (that is, 283 slow) on mailboxes containing a large number of messages. So let's 284 put a few things in perspective in that regard. 286 The flag searches SHOULD be fast. The flag searches (ALL, [UN]SEEN, 287 [UN]ANSWERED, [UN]DELETED, [UN]DRAFT, [UN]FLAGGED, NEW, OLD, RECENT) 288 are known to be used by clients for the client's own use (for 290 Internet DRAFT Implementation Recommendations September 1997 292 instance, some clients use "SEARCH UNSEEN" to find unseen mail and 293 "SEARCH DELETED" to warn the user before expunging messages). 295 Other searches, particularly the text searches (HEADER, TEXT, BODY) 296 are initiated by the user, rather than by the client itself, and 297 somewhat slower performance can be tolerated, since the user is aware 298 that the search is being done (and is probably aware that it might be 299 time-consuming). 301 The client MAY allow other commands to be sent to the server while a 302 SEARCH is in progress, but at the time of this writing there is 303 little or no server support for parallel processing of multiple 304 commands in the same session (and see "Multiple Accesses of the Same 305 Mailbox" above for a description of the dangers of trying to work 306 around this by doing your SEARCH in another session). 308 Another word about text searches: some servers, built on database 309 back-ends with indexed search capabilities, may return search results 310 that do not match the IMAP spec's "case-insensitive substring" 311 requirements. While these servers are in violation of the protocol, 312 there is little harm in the violation as long as the search results 313 are used only to response to a user's request. Still, developers of 314 such servers should be aware that they ARE violating the protocol, 315 should think carefully about that behaviour, and MUST be certain that 316 their servers respond accurately to the flag searches for the reasons 317 outlined above. 319 3.3. Miscellaneous Protocol Considerations 321 We describe here a number of important protocol-related issues, the 322 misunderstanding of which has caused significant interoperability 323 problems in IMAP4 implementations. One general item is that every 324 implementer should be certain to take note of and to understand 325 section 2.2.2 and the preamble to section 7 of the IMAP4rev1 spec 326 [RFC-2060]. 328 3.3.1. UIDs and UIDVALIDITY 330 Servers that support existing back-end mail stores often have no good 331 place to save UIDs for messages. Often the existing mail store will 332 not have the concept of UIDs in the sense that IMAP has: strictly 333 increasing, never re-issued, 32-bit integers. Some servers solve 334 this by storing the UIDs in a place that's accessible to end users, 335 allowing for the possibility that the users will delete them. Others 336 solve it by re-assigning UIDs every time a mailbox is selected. 338 The server SHOULD maintain UIDs permanently for all messages if it 340 Internet DRAFT Implementation Recommendations September 1997 342 can. If that's not possible, the server MUST change the UIDVALIDITY 343 value for the mailbox whenever any of the UIDs may have become 344 invalid. Clients MUST recognize that the UIDVALIDITY has changed and 345 MUST respond to that condition by throwing away any information that 346 they have saved about UIDs in that mailbox. There have been many 347 problems in this area when clients have failed to do this; in the 348 worst case it will result in loss of mail when a client deletes the 349 wrong piece of mail by using a stale UID. 351 It seems to be a common myth that "the UIDVALIDITY and the UID, taken 352 together, form a 64-bit identifier that uniquely identifies a message 353 on a server". This is absolutely NOT TRUE. There is no assurance 354 that the UIDVALIDITY values of two mailboxes be different, so the 355 UIDVALIDITY in no way identifies a mailbox. The ONLY purpose of 356 UIDVALIDITY is, as its name indicates, to give the client a way to 357 check the validity of the UIDs it has cached. 359 Under extreme circumstances (and this is extreme, indeed), the server 360 may have to invalidate UIDs while a mailbox is in use by a client - 361 that is, the UIDs that the client knows about in its active mailbox 362 are no longer valid. In that case, since there is no way to 363 communicate this to the client (and since this could result in a loss 364 of mail, should the client use the old UIDs to refer to the wrong 365 messages), the server MUST force the client to re-select the mailbox, 366 at which time it will obtain a new UIDVALIDITY value. To do this, 367 the server closes this client session (see "Severed Connections" 368 above) and the client then reconnects and gets back in synch. 370 3.3.2. FETCH Responses 372 When a client asks for certain information in a FETCH command, the 373 server MAY return the requested information in any order, not 374 necessarily in the order that it was requested. Further, the server 375 MAY return the information in separate FETCH responses and MAY also 376 return information that was not explicitly requested (to reflect to 377 the client changes in the state of the subject message). Some 378 examples: 380 C: 001 FETCH 1 UID FLAGS INTERNALDATE 381 S: * 5 FETCH (FLAGS (\Deleted)) 382 S: * 1 FETCH (FLAGS (\Seen) INTERNALDATE "..." UID 345) 383 S: 001 OK done 384 (In this case, the responses are in a different order. Also, the 385 server returned a flag update for message 5, which wasn't part of the 386 client's request.) 388 Internet DRAFT Implementation Recommendations September 1997 390 C: 002 FETCH 2 UID FLAGS INTERNALDATE 391 S: * 2 FETCH (INTERNALDATE "...") 392 S: * 2 FETCH (UID 399) 393 S: * 2 FETCH (FLAGS ()) 394 S: 002 OK done 395 (In this case, the responses are in a different order and were 396 returned in separate responses.) 398 C: 003 FETCH 2 BODY[1] 399 S: * 2 FETCH (FLAGS (\Seen) BODY[1] {14} 400 S: Hello world! 401 S: ) 402 S: 003 OK done 403 (In this case, the FLAGS response was added by the server, since 404 fetching the body part caused the server to set the \Seen flag.) 406 Because of this characteristic a client MUST be ready to receive any 407 FETCH response at any time and should use that information to update 408 its local information about the message to which the FETCH response 409 refers. A client MUST NOT assume that any FETCH responses will come 410 in any particular order, or even that any will come at all. If after 411 receiving the tagged response for a FETCH command the client finds 412 that it did not get all of the information requested, the client 413 SHOULD send a NOOP command to the server to ensure that the server 414 has an opportunity to send any pending EXPUNGE responses to the 415 client (see [RFC-2180]). 417 3.3.3. RFC822.SIZE 419 Some back-end mail stores keep the mail in a canonical form, rather 420 than retaining the original MIME format of the messages. This means 421 that the server must reassemble the message to produce a MIME stream 422 when a client does a fetch such as RFC822 or BODY[], requesting the 423 entire message. It also may mean that the server has no convenient 424 way to know the RFC822.SIZE of the message. Often, such a server 425 will actually have to build the MIME stream to compute the size, only 426 to throw the stream away and report the size to the client. 428 When this is the case, some servers have chosen to estimate the size, 429 rather than to compute it precisely. Such an estimate allows the 430 client to display an approximate size to the user and to use the 431 estimate in flood control considerations (q.v.), but requires that 432 the client not use the size for things such as allocation of buffers, 433 because those buffers might then be too small to hold the actual MIME 434 stream. Instead, use the size that's returned in the literal when 435 you fetch the data. 437 The protocol requires that the RFC822.SIZE value returned by the 439 Internet DRAFT Implementation Recommendations September 1997 441 server be EXACT. Estimating the size is a protocol violation, and 442 server designers must be aware that, despite the performance savings 443 they might realize in using an estimate, this practice will cause 444 some clients to fail in various ways. If possible, the server SHOULD 445 compute the RFC822.SIZE for a particular message once, and then save 446 it for later retrieval. If that's not possible, the server MUST 447 compute the value exactly every time. Incorrect estimates do cause 448 severe interoperability problems with some clients. 450 3.3.4. Expunged Messages 452 If the server allows multiple connections to the same mailbox, it is 453 often possible for messages to be expunged in one client unbeknownst 454 to another client. Since the server is not allowed to tell the 455 client about these expunged messages in response to a FETCH command, 456 the server may have to deal with the issue of how to return 457 information about an expunged message. There was extensive 458 discussion about this issue, and the results of that discussion are 459 summarized in [RFC-2180]. See that reference for a detailed 460 explanation and for recommendations. 462 3.3.5. The Namespace Issue 464 Namespaces are a very muddy area in IMAP4 implementation right now 465 (see [NAMESPACE] for a proposal to clear the water a bit). Until the 466 issue is resolved, the important thing for client developers to 467 understand is that some servers provide access through IMAP to more 468 than just the user's personal mailboxes, and, in fact, the user's 469 personal mailboxes may be "hidden" somewhere in the user's default 470 hierarchy. The client, therefore, SHOULD provide a setting wherein 471 the user can specify a prefix to be used when accessing mailboxes. 472 If the user's mailboxes are all in "~/mail/", for instance, then the 473 user can put that string in the prefix. The client would then put 474 the prefix in front of any name pattern in the LIST and LSUB 475 commands: 476 C: 001 LIST "" ~/mail/% 477 (See also "Reference Names in the LIST Command" below.) 479 3.3.6. Creating Special-Use Mailboxes 481 It may seem at first that this is part of the namespace issue; it is 482 not, and is only indirectly related to it. A number of clients like 483 to create special-use mailboxes with particular names. Most 484 commonly, clients with a "trash folder" model of message deletion 485 want to create a mailbox with the name "Trash" or "Deleted". Some 486 clients want to create a "Drafts" mailbox, an "Outbox" mailbox, or a 488 Internet DRAFT Implementation Recommendations September 1997 490 "Sent Mail" mailbox. And so on. There are two major 491 interoperability problems with this practice: 492 1. different clients may use different names for mailboxes with 493 similar functions (such as "Trash" and "Deleted"), or may manage the 494 same mailboxes in different ways, causing problems if a user switches 495 between clients and 496 2. there is no guarantee that the server will allow the creation of 497 the desired mailbox. 499 The client developer is, therefore, well advised to consider 500 carefully the creation of any special-use mailboxes on the server, 501 and, further, the client MUST NOT require such mailbox creation - 502 that is, if you do decide to do this, you MUST handle gracefully the 503 failure of the CREATE command and behave reasonably when your 504 special-use mailboxes do not exist and can not be created. 506 3.3.7. Reference Names in the LIST Command 508 Many implementers of both clients and servers are confused by the 509 "reference name" on the LIST command. The reference name is intended 510 to be used in much the way a "cd" (change directory) command is used 511 on Unix, PC DOS, Windows, and OS/2 systems. That is, the mailbox 512 name is interpreted in much the same way as a file of that name would 513 be found if one had done a "cd" command into the directory specified 514 by the reference name. For example, in Unix we have the following: 516 > cd /u/jones/junk 517 > vi banana [file is "/u/jones/junk/banana"] 518 > vi stuff/banana [file is "/u/jones/junk/stuff/banana"] 519 > vi /etc/hosts [file is "/etc/hosts"] 521 The interoperability problems with this, in practice, are several. 522 First, while some IMAP servers are built on Unix or PC file systems, 523 many others are not, and the file system semantics do not make sense 524 in those configurations. Second, while some IMAP servers expose the 525 underlying file system to the clients, others allow access only to 526 the user's personal mailboxes, or to some other limited set of files, 527 making such file-system-like semantics less meaningful. Third, 528 because the IMAP spec leaves the interpretation of the reference name 529 as "implementation-dependent", the various server implementations 530 handle it in vastly differing ways, and fourth, many implementers 531 simply do not understand it and misuse it, do not use it, or ignore 532 it as a result. 534 The following statement gets somewhat into the religious issues that 535 we've tried to avoid scrupulously here; so be it: because of the 536 confusion around the reference name, its use by a client is a 537 dangerous thing, prone to result in interoperability problems. There 539 Internet DRAFT Implementation Recommendations September 1997 541 are servers that interpret it as originally intended; there are 542 servers that ignore it completely; there are servers that simply 543 prepend it to the mailbox name (with or without inserting a hierarchy 544 delimiter in between). Because a client can't know which of these 545 four behaviours to expect, the safest route is to leave it empty and 546 put the full mailbox name pattern in the mailbox name argument. 548 There is in no way universal agreement about the use or non-use of 549 the reference name. The last words here are, "Be aware." 551 3.4. A Word About Testing 553 Since the whole point of IMAP is interoperability, and since 554 interoperability can not be tested in a vacuum, the final 555 recommendation of this treatise is, "Test against EVERYTHING." Test 556 your client against every server you can get an account on. Test 557 your server with every client you can get your hands on. Many 558 clients make limited test versions available on the Web for the 559 downloading. Many server owners will give serious client developers 560 guest accounts for testing. Contact them and ask. NEVER assume that 561 because your client works with one or two servers, or because your 562 server does fine with one or two clients, you will interoperate well 563 in general. 565 In particular, in addition to everything else, be sure to test 566 against the reference implementations: the PINE client, the 567 University of Washington server, and the Cyrus server. 569 See the following URLs on the web for more information here: 570 IMAP Products and Sources: http://www.imap.org/products.html 571 IMC MailConnect: http://www.imc.org/imc-mailconnect 573 4. Security Considerations 575 This document describes behavior of servers that use the IMAP4 576 protocol, and as such, has the same security considerations as 577 described in [RFC-2060]. 579 5. References 581 [RFC-2060], Crispin, M., "Internet Message Access Protocol - Version 582 4rev1", RFC 2060, University of Washington, December 1996. 584 [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate 585 Requirement Levels", RFC 2119, Harvard University, March 1997. 587 Internet DRAFT Implementation Recommendations September 1997 589 [RFC-2180], Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC 590 2180, Microsoft, July 1997. 592 [NAMESPACE], Gahrns, M. & Newman, C., "IMAP4 Namespace", draft 593 document , June 1997. 595 6. Acknowledgments 597 To be completed... 599 This document is the result of discussions on the IMAP4 mailing list 600 and is meant to reflect consensus of this group. In particular, Mark 601 Crispin was an active participant in the discussions or made 602 suggestions to this document. 604 7. Author's Address 606 Barry Leiba 607 IBM T.J. Watson Research Center 608 30 Saw Mill River Road 609 Hawthorne, NY 10532 611 Phone: 1-914-784-7941 612 Email: leiba@watson.ibm.com