rfc3502.txt (13379B)
1 2 3 4 5 6 7 Network Working Group M. Crispin 8 Request for Comments: 3502 University of Washington 9 Category: Standards Track March 2003 10 11 12 Internet Message Access Protocol (IMAP) - MULTIAPPEND Extension 13 14 Status of this Memo 15 16 This document specifies an Internet standards track protocol for the 17 Internet community, and requests discussion and suggestions for 18 improvements. Please refer to the current edition of the "Internet 19 Official Protocol Standards" (STD 1) for the standardization state 20 and status of this protocol. Distribution of this memo is unlimited. 21 22 Copyright Notice 23 24 Copyright (C) The Internet Society (2003). All Rights Reserved. 25 26 Abstract 27 28 This document describes the multiappending extension to the Internet 29 Message Access Protocol (IMAP) (RFC 3501). This extension provides 30 substantial performance improvements for IMAP clients which upload 31 multiple messages at a time to a mailbox on the server. 32 33 A server which supports this extension indicates this with a 34 capability name of "MULTIAPPEND". 35 36 Terminology 37 38 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 39 "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to 40 be interpreted as described in [KEYWORDS]. 41 42 Introduction 43 44 The MULTIAPPEND extension permits uploading of multiple messages with 45 a single command. When used in conjunction with the [LITERAL+] 46 extension, the entire upload is accomplished in a single 47 command/response round trip. 48 49 A MULTIAPPEND APPEND operation is atomic; either all messages are 50 successfully appended, or no messages are appended. 51 52 In the base IMAP specification, each message must be appended in a 53 separate command, and there is no mechanism to "unappend" messages if 54 an error occurs while appending. Also, some mail stores may require 55 56 57 58 Crispin Standards Track [Page 1] 59 60 RFC 3502 IMAP MULTIAPPEND March 2003 61 62 63 an expensive "open/lock + sync/unlock/close" operation as part of 64 appending; this can be quite expensive if it must be done on a 65 per-message basis. 66 67 If the server supports both LITERAL+ and pipelining but not 68 MULTIAPPEND, it may be possible to get some of the performance 69 advantages of MULTIAPPEND by doing a pipelined "batch" append. 70 However, it will not work as well as MULTIAPPEND for the following 71 reasons: 72 73 1) Multiple APPEND commands, even as part of a pipelined batch, 74 are non-atomic by definition. There is no way to revert the 75 mailbox to the state before the batch append in the event of an 76 error. 77 78 2) It may not be feasible for the server to coalesce pipelined 79 APPEND operations so as to avoid the "open/lock + 80 sync/unlock/close" overhead described above. In any case, such 81 coalescing would be timing dependent and thus potentially 82 unreliable. In particular, with traditional UNIX mailbox files, 83 it is assumed that a lock is held only for a single atomic 84 operation, and many applications disregard any lock that is 85 older than 5 minutes. 86 87 3) If an error occurs, depending upon the nature of the error, 88 it is possible for additional messages to be appended after the 89 error. For example, the user wants to append 5 messages, but a 90 disk quota error occurs with the third message because of its 91 size. However, the fourth and fifth messages have already been 92 sent in the pipeline, so the mailbox ends up with the first, 93 second, fourth, and fifth messages of the batch appended. 94 95 6.3.11. APPEND Command 96 97 Arguments: mailbox name 98 one or more messages to upload, specified as: 99 OPTIONAL flag parenthesized list 100 OPTIONAL date/time string 101 message literal 102 103 Data: no specific responses for this command 104 105 Result: OK - append completed 106 NO - append error: can't append to that mailbox, error 107 in flags or date/time or message text, 108 append cancelled 109 BAD - command unknown or arguments invalid 110 111 112 113 114 Crispin Standards Track [Page 2] 115 116 RFC 3502 IMAP MULTIAPPEND March 2003 117 118 119 The APPEND command appends the literal arguments as new messages 120 to the end of the specified destination mailbox. This argument 121 SHOULD be in the format of an [RFC-2822] message. 8-bit 122 characters are permitted in the message. A server implementation 123 that is unable to preserve 8-bit data properly MUST be able to 124 reversibly convert 8-bit APPEND data to 7-bit using a [MIME-IMB] 125 content transfer encoding. 126 127 Note: There MAY be exceptions, e.g., draft messages, in 128 which required [RFC-2822] header lines are omitted in the 129 message literal argument to APPEND. The full implications 130 of doing so MUST be understood and carefully weighed. 131 132 If a flag parenthesized list is specified, the flags SHOULD be set 133 in the resulting message; otherwise, the flag list of the 134 resulting message is set empty by default. 135 136 If a date-time is specified, the internal date SHOULD be set in 137 the resulting message; otherwise, the internal date of the 138 resulting message is set to the current date and time by default. 139 140 A zero-length message literal argument is an error, and MUST 141 return a NO. This can be used to cancel the append. 142 143 If the append is unsuccessful for any reason (including being 144 cancelled), the mailbox MUST be restored to its state before the 145 APPEND attempt; no partial appending is permitted. The server MAY 146 return an error before processing all the message arguments. 147 148 If the destination mailbox does not exist, a server MUST return an 149 error, and MUST NOT automatically create the mailbox. Unless it 150 is certain that the destination mailbox can not be created, the 151 server MUST send the response code "[TRYCREATE]" as the prefix of 152 the text of the tagged NO response. This gives a hint to the 153 client that it can attempt a CREATE command and retry the APPEND 154 if the CREATE is successful. 155 156 If the mailbox is currently selected, the normal new message 157 actions SHOULD occur. Specifically, the server SHOULD notify the 158 client immediately via an untagged EXISTS response. If the server 159 does not do so, the client MAY issue a NOOP command (or failing 160 that, a CHECK command) after one or more APPEND commands. 161 162 163 164 165 166 167 168 169 170 Crispin Standards Track [Page 3] 171 172 RFC 3502 IMAP MULTIAPPEND March 2003 173 174 175 Example: C: A003 APPEND saved-messages (\Seen) {329} 176 S: + Ready for literal data 177 C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) 178 C: From: Fred Foobar <foobar@Blurdybloop.example.COM> 179 C: Subject: afternoon meeting 180 C: To: mooch@owatagu.example.net 181 C: Message-Id: <B27397-0100000@Blurdybloop.example.COM> 182 C: MIME-Version: 1.0 183 C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII 184 C: 185 C: Hello Joe, do you think we can meet at 3:30 tomorrow? 186 C: (\Seen) " 7-Feb-1994 22:43:04 -0800" {295} 187 S: + Ready for literal data 188 C: Date: Mon, 7 Feb 1994 22:43:04 -0800 (PST) 189 C: From: Joe Mooch <mooch@OWaTaGu.example.net> 190 C: Subject: Re: afternoon meeting 191 C: To: foobar@blurdybloop.example.com 192 C: Message-Id: <a0434793874930@OWaTaGu.example.net> 193 C: MIME-Version: 1.0 194 C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII 195 C: 196 C: 3:30 is fine with me. 197 C: 198 S: A003 OK APPEND completed 199 C: A004 APPEND bogusname (\Flagged) {1023} 200 S: A004 NO [TRYCREATE] No such mailbox as bogusname 201 C: A005 APPEND test (\Flagged) {99} 202 S: + Ready for literal data 203 C: Date: Mon, 7 Feb 2000 22:43:04 -0800 (PST) 204 C: From: Fred Foobar <fred@example.com> 205 C: Subject: hmm... 206 C: {35403} 207 S: A005 NO APPEND failed: Disk quota exceeded 208 209 Note: The APPEND command is not used for message delivery, 210 because it does not provide a mechanism to transfer [SMTP] 211 envelope information. 212 213 Modification to IMAP4rev1 Base Protocol Formal Syntax 214 215 The following syntax specification uses the Augmented Backus-Naur 216 Form (ABNF) notation as specified in [ABNF]. 217 218 append = "APPEND" SP mailbox 1*append-message 219 220 append-message = [SP flag-list] [SP date-time] SP literal 221 222 223 224 225 226 Crispin Standards Track [Page 4] 227 228 RFC 3502 IMAP MULTIAPPEND March 2003 229 230 231 MULTIAPPEND Interaction with UIDPLUS Extension 232 233 Servers which support both MULTIAPPEND and [UIDPLUS] will have the 234 "resp-code-apnd" rule modified as follows: 235 236 resp-code-apnd = "APPENDUID" SP nz-number SP set 237 238 That is, the APPENDUID response code returns as many UIDs as there 239 were messages appended in the multiple append. The UIDs returned 240 should be in the order the articles where appended. The message set 241 may not contain extraneous UIDs or the symbol "*". 242 243 Security Considerations 244 245 The MULTIAPPEND extension does not raise any security considerations 246 that are not present in the base [IMAP] protocol, and these issues 247 are discussed in [IMAP]. Nevertheless, it is important to remember 248 that IMAP4rev1 protocol transactions, including electronic mail data, 249 are sent in the clear over the network unless protection from 250 snooping is negotiated, either by the use of STARTTLS, privacy 251 protection is negotiated in the AUTHENTICATE command, or some other 252 protection mechanism is in effect. 253 254 Normative References 255 256 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax 257 Specifications: ABNF", RFC 2234, November 1997. 258 259 [IMAP] Crispin, M., "Internet Message Access Protocol - Version 260 4rev1", RFC 3501, March 2003. 261 262 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate 263 Requirement Levels", BCP 14, RFC 2119, March 1997. 264 265 [MIME-IMB] Freed, N. and N. Borenstein, "MIME (Multipurpose Internet 266 Mail Extensions) Part One: Format of Internet Message 267 Bodies", RFC 2045, November 1996. 268 269 [RFC-2822] Resnick, P., "Internet Message Format", RFC 2822, April 270 2001. 271 272 273 274 275 276 277 278 279 280 281 282 Crispin Standards Track [Page 5] 283 284 RFC 3502 IMAP MULTIAPPEND March 2003 285 286 287 Informative References 288 289 [LITERAL+] Myers, J., "IMAP4 non-synchronizing literals", RFC 2088, 290 January 1997. 291 292 [UIDPLUS] Myers, J., "IMAP4 UIDPLUS extension", RFC 2359, June 1988. 293 294 [SMTP] Klensin, J., Editor, "Simple Mail Transfer Protocol", RFC 295 2821, April 2001. 296 297 Author's Address 298 299 Mark R. Crispin 300 Networks and Distributed Computing 301 University of Washington 302 4545 15th Avenue NE 303 Seattle, WA 98105-4527 304 305 Phone: (206) 543-5762 306 EMail: MRC@CAC.Washington.EDU 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 Crispin Standards Track [Page 6] 339 340 RFC 3502 IMAP MULTIAPPEND March 2003 341 342 343 Full Copyright Statement 344 345 Copyright (C) The Internet Society (2003). All Rights Reserved. 346 347 This document and translations of it may be copied and furnished to 348 others, and derivative works that comment on or otherwise explain it 349 or assist in its implementation may be prepared, copied, published 350 and distributed, in whole or in part, without restriction of any 351 kind, provided that the above copyright notice and this paragraph are 352 included on all such copies and derivative works. However, this 353 document itself may not be modified in any way, such as by removing 354 the copyright notice or references to the Internet Society or other 355 Internet organizations, except as needed for the purpose of 356 developing Internet standards in which case the procedures for 357 copyrights defined in the Internet Standards process must be 358 followed, or as required to translate it into languages other than 359 English. 360 361 The limited permissions granted above are perpetual and will not be 362 revoked by the Internet Society or its successors or assigns. 363 364 This document and the information contained herein is provided on an 365 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 366 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 367 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 368 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 369 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 370 371 Acknowledgement 372 373 Funding for the RFC Editor function is currently provided by the 374 Internet Society. 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 Crispin Standards Track [Page 7] 395