imap/docs/rfc/rfc3502.txt

   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 \f
  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 \f
 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 \f
 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 \f
 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 \f
 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 \f
 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 \f