1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/rfc/rfc3502.txt	Mon Sep 14 15:17:45 2009 +0900
     1.3 @@ -0,0 +1,395 @@
     1.4 +
     1.5 +
     1.6 +
     1.7 +
     1.8 +
     1.9 +
    1.10 +Network Working Group                                         M. Crispin
    1.11 +Request for Comments: 3502                      University of Washington
    1.12 +Category: Standards Track                                     March 2003
    1.13 +
    1.14 +
    1.15 +    Internet Message Access Protocol (IMAP) - MULTIAPPEND Extension
    1.16 +
    1.17 +Status of this Memo
    1.18 +
    1.19 +   This document specifies an Internet standards track protocol for the
    1.20 +   Internet community, and requests discussion and suggestions for
    1.21 +   improvements.  Please refer to the current edition of the "Internet
    1.22 +   Official Protocol Standards" (STD 1) for the standardization state
    1.23 +   and status of this protocol.  Distribution of this memo is unlimited.
    1.24 +
    1.25 +Copyright Notice
    1.26 +
    1.27 +   Copyright (C) The Internet Society (2003).  All Rights Reserved.
    1.28 +
    1.29 +Abstract
    1.30 +
    1.31 +   This document describes the multiappending extension to the Internet
    1.32 +   Message Access Protocol (IMAP) (RFC 3501).  This extension provides
    1.33 +   substantial performance improvements for IMAP clients which upload
    1.34 +   multiple messages at a time to a mailbox on the server.
    1.35 +
    1.36 +   A server which supports this extension indicates this with a
    1.37 +   capability name of "MULTIAPPEND".
    1.38 +
    1.39 +Terminology
    1.40 +
    1.41 +   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
    1.42 +   "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to
    1.43 +   be interpreted as described in [KEYWORDS].
    1.44 +
    1.45 +Introduction
    1.46 +
    1.47 +   The MULTIAPPEND extension permits uploading of multiple messages with
    1.48 +   a single command.  When used in conjunction with the [LITERAL+]
    1.49 +   extension, the entire upload is accomplished in a single
    1.50 +   command/response round trip.
    1.51 +
    1.52 +   A MULTIAPPEND APPEND operation is atomic; either all messages are
    1.53 +   successfully appended, or no messages are appended.
    1.54 +
    1.55 +   In the base IMAP specification, each message must be appended in a
    1.56 +   separate command, and there is no mechanism to "unappend" messages if
    1.57 +   an error occurs while appending.  Also, some mail stores may require
    1.58 +
    1.59 +
    1.60 +
    1.61 +Crispin                     Standards Track                     [Page 1]
    1.62 +
    1.63 +RFC 3502                    IMAP MULTIAPPEND                  March 2003
    1.64 +
    1.65 +
    1.66 +   an expensive "open/lock + sync/unlock/close" operation as part of
    1.67 +   appending; this can be quite expensive if it must be done on a
    1.68 +   per-message basis.
    1.69 +
    1.70 +   If the server supports both LITERAL+ and pipelining but not
    1.71 +   MULTIAPPEND, it may be possible to get some of the performance
    1.72 +   advantages of MULTIAPPEND by doing a pipelined "batch" append.
    1.73 +   However, it will not work as well as MULTIAPPEND for the following
    1.74 +   reasons:
    1.75 +
    1.76 +        1) Multiple APPEND commands, even as part of a pipelined batch,
    1.77 +        are non-atomic by definition.  There is no way to revert the
    1.78 +        mailbox to the state before the batch append in the event of an
    1.79 +        error.
    1.80 +
    1.81 +        2) It may not be feasible for the server to coalesce pipelined
    1.82 +        APPEND operations so as to avoid the "open/lock +
    1.83 +        sync/unlock/close" overhead described above.  In any case, such
    1.84 +        coalescing would be timing dependent and thus potentially
    1.85 +        unreliable.  In particular, with traditional UNIX mailbox files,
    1.86 +        it is assumed that a lock is held only for a single atomic
    1.87 +        operation, and many applications disregard any lock that is
    1.88 +        older than 5 minutes.
    1.89 +
    1.90 +        3) If an error occurs, depending upon the nature of the error,
    1.91 +        it is possible for additional messages to be appended after the
    1.92 +        error.  For example, the user wants to append 5 messages, but a
    1.93 +        disk quota error occurs with the third message because of its
    1.94 +        size.  However, the fourth and fifth messages have already been
    1.95 +        sent in the pipeline, so the mailbox ends up with the first,
    1.96 +        second, fourth, and fifth messages of the batch appended.
    1.97 +
    1.98 +6.3.11.  APPEND Command
    1.99 +
   1.100 +   Arguments:  mailbox name
   1.101 +               one or more messages to upload, specified as:
   1.102 +                  OPTIONAL flag parenthesized list
   1.103 +                  OPTIONAL date/time string
   1.104 +                  message literal
   1.105 +
   1.106 +   Data:       no specific responses for this command
   1.107 +
   1.108 +   Result:     OK - append completed
   1.109 +               NO - append error: can't append to that mailbox, error
   1.110 +                    in flags or date/time or message text,
   1.111 +                    append cancelled
   1.112 +               BAD - command unknown or arguments invalid
   1.113 +
   1.114 +
   1.115 +
   1.116 +
   1.117 +Crispin                     Standards Track                     [Page 2]
   1.118 +
   1.119 +RFC 3502                    IMAP MULTIAPPEND                  March 2003
   1.120 +
   1.121 +
   1.122 +      The APPEND command appends the literal arguments as new messages
   1.123 +      to the end of the specified destination mailbox.  This argument
   1.124 +      SHOULD be in the format of an [RFC-2822] message.  8-bit
   1.125 +      characters are permitted in the message.  A server implementation
   1.126 +      that is unable to preserve 8-bit data properly MUST be able to
   1.127 +      reversibly convert 8-bit APPEND data to 7-bit using a [MIME-IMB]
   1.128 +      content transfer encoding.
   1.129 +
   1.130 +            Note: There MAY be exceptions, e.g., draft messages, in
   1.131 +            which required [RFC-2822] header lines are omitted in the
   1.132 +            message literal argument to APPEND.  The full implications
   1.133 +            of doing so MUST be understood and carefully weighed.
   1.134 +
   1.135 +      If a flag parenthesized list is specified, the flags SHOULD be set
   1.136 +      in the resulting message; otherwise, the flag list of the
   1.137 +      resulting message is set empty by default.
   1.138 +
   1.139 +      If a date-time is specified, the internal date SHOULD be set in
   1.140 +      the resulting message; otherwise, the internal date of the
   1.141 +      resulting message is set to the current date and time by default.
   1.142 +
   1.143 +      A zero-length message literal argument is an error, and MUST
   1.144 +      return a NO.  This can be used to cancel the append.
   1.145 +
   1.146 +      If the append is unsuccessful for any reason (including being
   1.147 +      cancelled), the mailbox MUST be restored to its state before the
   1.148 +      APPEND attempt; no partial appending is permitted.  The server MAY
   1.149 +      return an error before processing all the message arguments.
   1.150 +
   1.151 +      If the destination mailbox does not exist, a server MUST return an
   1.152 +      error, and MUST NOT automatically create the mailbox.  Unless it
   1.153 +      is certain that the destination mailbox can not be created, the
   1.154 +      server MUST send the response code "[TRYCREATE]" as the prefix of
   1.155 +      the text of the tagged NO response.  This gives a hint to the
   1.156 +      client that it can attempt a CREATE command and retry the APPEND
   1.157 +      if the CREATE is successful.
   1.158 +
   1.159 +      If the mailbox is currently selected, the normal new message
   1.160 +      actions SHOULD occur.  Specifically, the server SHOULD notify the
   1.161 +      client immediately via an untagged EXISTS response.  If the server
   1.162 +      does not do so, the client MAY issue a NOOP command (or failing
   1.163 +      that, a CHECK command) after one or more APPEND commands.
   1.164 +
   1.165 +
   1.166 +
   1.167 +
   1.168 +
   1.169 +
   1.170 +
   1.171 +
   1.172 +
   1.173 +Crispin                     Standards Track                     [Page 3]
   1.174 +
   1.175 +RFC 3502                    IMAP MULTIAPPEND                  March 2003
   1.176 +
   1.177 +
   1.178 +   Example: C: A003 APPEND saved-messages (\Seen) {329}
   1.179 +            S: + Ready for literal data
   1.180 +            C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST)
   1.181 +            C: From: Fred Foobar <foobar@Blurdybloop.example.COM>
   1.182 +            C: Subject: afternoon meeting
   1.183 +            C: To: mooch@owatagu.example.net
   1.184 +            C: Message-Id: <B27397-0100000@Blurdybloop.example.COM>
   1.185 +            C: MIME-Version: 1.0
   1.186 +            C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
   1.187 +            C:
   1.188 +            C: Hello Joe, do you think we can meet at 3:30 tomorrow?
   1.189 +            C:  (\Seen) " 7-Feb-1994 22:43:04 -0800" {295}
   1.190 +            S: + Ready for literal data
   1.191 +            C: Date: Mon, 7 Feb 1994 22:43:04 -0800 (PST)
   1.192 +            C: From: Joe Mooch <mooch@OWaTaGu.example.net>
   1.193 +            C: Subject: Re: afternoon meeting
   1.194 +            C: To: foobar@blurdybloop.example.com
   1.195 +            C: Message-Id: <a0434793874930@OWaTaGu.example.net>
   1.196 +            C: MIME-Version: 1.0
   1.197 +            C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
   1.198 +            C:
   1.199 +            C: 3:30 is fine with me.
   1.200 +            C:
   1.201 +            S: A003 OK APPEND completed
   1.202 +            C: A004 APPEND bogusname (\Flagged) {1023}
   1.203 +            S: A004 NO [TRYCREATE] No such mailbox as bogusname
   1.204 +            C: A005 APPEND test (\Flagged) {99}
   1.205 +            S: + Ready for literal data
   1.206 +            C: Date: Mon, 7 Feb 2000 22:43:04 -0800 (PST)
   1.207 +            C: From: Fred Foobar <fred@example.com>
   1.208 +            C: Subject: hmm...
   1.209 +            C:  {35403}
   1.210 +            S: A005 NO APPEND failed: Disk quota exceeded
   1.211 +
   1.212 +        Note: The APPEND command is not used for message delivery,
   1.213 +        because it does not provide a mechanism to transfer [SMTP]
   1.214 +        envelope information.
   1.215 +
   1.216 +Modification to IMAP4rev1 Base Protocol Formal Syntax
   1.217 +
   1.218 +   The following syntax specification uses the Augmented Backus-Naur
   1.219 +   Form (ABNF) notation as specified in [ABNF].
   1.220 +
   1.221 +   append          = "APPEND" SP mailbox 1*append-message
   1.222 +
   1.223 +   append-message  = [SP flag-list] [SP date-time] SP literal
   1.224 +
   1.225 +
   1.226 +
   1.227 +
   1.228 +
   1.229 +Crispin                     Standards Track                     [Page 4]
   1.230 +
   1.231 +RFC 3502                    IMAP MULTIAPPEND                  March 2003
   1.232 +
   1.233 +
   1.234 +MULTIAPPEND Interaction with UIDPLUS Extension
   1.235 +
   1.236 +   Servers which support both MULTIAPPEND and [UIDPLUS] will have the
   1.237 +   "resp-code-apnd" rule modified as follows:
   1.238 +
   1.239 +   resp-code-apnd  = "APPENDUID" SP nz-number SP set
   1.240 +
   1.241 +   That is, the APPENDUID response code returns as many UIDs as there
   1.242 +   were messages appended in the multiple append.  The UIDs returned
   1.243 +   should be in the order the articles where appended.  The message set
   1.244 +   may not contain extraneous UIDs or the symbol "*".
   1.245 +
   1.246 +Security Considerations
   1.247 +
   1.248 +   The MULTIAPPEND extension does not raise any security considerations
   1.249 +   that are not present in the base [IMAP] protocol, and these issues
   1.250 +   are discussed in [IMAP].  Nevertheless, it is important to remember
   1.251 +   that IMAP4rev1 protocol transactions, including electronic mail data,
   1.252 +   are sent in the clear over the network unless protection from
   1.253 +   snooping is negotiated, either by the use of STARTTLS, privacy
   1.254 +   protection is negotiated in the AUTHENTICATE command, or some other
   1.255 +   protection mechanism is in effect.
   1.256 +
   1.257 +Normative References
   1.258 +
   1.259 +   [ABNF]     Crocker, D. and P. Overell, "Augmented BNF for Syntax
   1.260 +              Specifications: ABNF", RFC 2234, November 1997.
   1.261 +
   1.262 +   [IMAP]     Crispin, M., "Internet Message Access Protocol - Version
   1.263 +              4rev1", RFC 3501, March 2003.
   1.264 +
   1.265 +   [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
   1.266 +              Requirement Levels", BCP 14, RFC 2119, March 1997.
   1.267 +
   1.268 +   [MIME-IMB] Freed, N. and N. Borenstein, "MIME (Multipurpose Internet
   1.269 +              Mail Extensions) Part One: Format of Internet Message
   1.270 +              Bodies", RFC 2045, November 1996.
   1.271 +
   1.272 +   [RFC-2822] Resnick, P., "Internet Message Format", RFC 2822, April
   1.273 +              2001.
   1.274 +
   1.275 +
   1.276 +
   1.277 +
   1.278 +
   1.279 +
   1.280 +
   1.281 +
   1.282 +
   1.283 +
   1.284 +
   1.285 +Crispin                     Standards Track                     [Page 5]
   1.286 +
   1.287 +RFC 3502                    IMAP MULTIAPPEND                  March 2003
   1.288 +
   1.289 +
   1.290 +Informative References
   1.291 +
   1.292 +   [LITERAL+] Myers, J., "IMAP4 non-synchronizing literals", RFC 2088,
   1.293 +              January 1997.
   1.294 +
   1.295 +   [UIDPLUS]  Myers, J., "IMAP4 UIDPLUS extension", RFC 2359, June 1988.
   1.296 +
   1.297 +   [SMTP]     Klensin, J., Editor, "Simple Mail Transfer Protocol", RFC
   1.298 +              2821, April 2001.
   1.299 +
   1.300 +Author's Address
   1.301 +
   1.302 +   Mark R. Crispin
   1.303 +   Networks and Distributed Computing
   1.304 +   University of Washington
   1.305 +   4545 15th Avenue NE
   1.306 +   Seattle, WA  98105-4527
   1.307 +
   1.308 +   Phone: (206) 543-5762
   1.309 +   EMail: MRC@CAC.Washington.EDU
   1.310 +
   1.311 +
   1.312 +
   1.313 +
   1.314 +
   1.315 +
   1.316 +
   1.317 +
   1.318 +
   1.319 +
   1.320 +
   1.321 +
   1.322 +
   1.323 +
   1.324 +
   1.325 +
   1.326 +
   1.327 +
   1.328 +
   1.329 +
   1.330 +
   1.331 +
   1.332 +
   1.333 +
   1.334 +
   1.335 +
   1.336 +
   1.337 +
   1.338 +
   1.339 +
   1.340 +
   1.341 +Crispin                     Standards Track                     [Page 6]
   1.342 +
   1.343 +RFC 3502                    IMAP MULTIAPPEND                  March 2003
   1.344 +
   1.345 +
   1.346 +Full Copyright Statement
   1.347 +
   1.348 +   Copyright (C) The Internet Society (2003).  All Rights Reserved.
   1.349 +
   1.350 +   This document and translations of it may be copied and furnished to
   1.351 +   others, and derivative works that comment on or otherwise explain it
   1.352 +   or assist in its implementation may be prepared, copied, published
   1.353 +   and distributed, in whole or in part, without restriction of any
   1.354 +   kind, provided that the above copyright notice and this paragraph are
   1.355 +   included on all such copies and derivative works.  However, this
   1.356 +   document itself may not be modified in any way, such as by removing
   1.357 +   the copyright notice or references to the Internet Society or other
   1.358 +   Internet organizations, except as needed for the purpose of
   1.359 +   developing Internet standards in which case the procedures for
   1.360 +   copyrights defined in the Internet Standards process must be
   1.361 +   followed, or as required to translate it into languages other than
   1.362 +   English.
   1.363 +
   1.364 +   The limited permissions granted above are perpetual and will not be
   1.365 +   revoked by the Internet Society or its successors or assigns.
   1.366 +
   1.367 +   This document and the information contained herein is provided on an
   1.368 +   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   1.369 +   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   1.370 +   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   1.371 +   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   1.372 +   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
   1.373 +
   1.374 +Acknowledgement
   1.375 +
   1.376 +   Funding for the RFC Editor function is currently provided by the
   1.377 +   Internet Society.
   1.378 +
   1.379 +
   1.380 +
   1.381 +
   1.382 +
   1.383 +
   1.384 +
   1.385 +
   1.386 +
   1.387 +
   1.388 +
   1.389 +
   1.390 +
   1.391 +
   1.392 +
   1.393 +
   1.394 +
   1.395 +
   1.396 +
   1.397 +Crispin                     Standards Track                     [Page 7]
   1.398 +