RFC's
RFC 3502 - Internet Message Access Protocol (IMAP) - MULTIAPPEND Extension

Network Working Group M. Crispin

Request for Comments: 3502 University of Washington

Category: Standards Track March 2003

Internet Message Access Protocol (IMAP) - MULTIAPPEND Extension

Status of this Memo

This document specifies an Internet standards track protocol for the

Internet community, and requests discussion and suggestions for

improvements. Please refer to the current edition of the "Internet

Official Protocol Standards" (STD 1) for the standardization state

and status of this protocol. Distribution of this memo is unlimited.

Copyright Notice

Copyright (C) The Internet Society (2003). All Rights Reserved.

Abstract

This document describes the multiappending extension to the Internet

Message Access Protocol (IMAP) (RFC 3501). This extension provides

substantial performance improvements for IMAP clients which upload

multiple messages at a time to a mailbox on the server.

A server which supports this extension indicates this with a

capability name of "MULTIAPPEND".

Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",

"SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to

be interpreted as described in [KEYWORDS].

Introduction

The MULTIAPPEND extension permits uploading of multiple messages with

a single command. When used in conjunction with the [LITERAL+]

extension, the entire upload is accomplished in a single

command/response round trip.

A MULTIAPPEND APPEND operation is atomic; either all messages are

successfully appended, or no messages are appended.

In the base IMAP specification, each message must be appended in a

separate command, and there is no mechanism to "unappend" messages if

an error occurs while appending. Also, some mail stores may require

Crispin Standards Track [Page 1]

RFC 3502 IMAP MULTIAPPEND March 2003

an expensive "open/lock + sync/unlock/close" operation as part of

appending; this can be quite expensive if it must be done on a

per-message basis.

If the server supports both LITERAL+ and pipelining but not

MULTIAPPEND, it may be possible to get some of the performance

advantages of MULTIAPPEND by doing a pipelined "batch" append.

However, it will not work as well as MULTIAPPEND for the following

reasons:

1) Multiple APPEND commands, even as part of a pipelined batch,

are non-atomic by definition. There is no way to revert the

mailbox to the state before the batch append in the event of an

error.

2) It may not be feasible for the server to coalesce pipelined

APPEND operations so as to avoid the "open/lock +

sync/unlock/close" overhead described above. In any case, such

coalescing would be timing dependent and thus potentially

unreliable. In particular, with traditional UNIX mailbox files,

it is assumed that a lock is held only for a single atomic

operation, and many applications disregard any lock that is

older than 5 minutes.

3) If an error occurs, depending upon the nature of the error,

it is possible for additional messages to be appended after the

error. For example, the user wants to append 5 messages, but a

disk quota error occurs with the third message because of its

size. However, the fourth and fifth messages have already been

sent in the pipeline, so the mailbox ends up with the first,

second, fourth, and fifth messages of the batch appended.

6.3.11. APPEND Command

Arguments: mailbox name

one or more messages to upload, specified as:

OPTIONAL flag parenthesized list

OPTIONAL date/time string

message literal

Data: no specific responses for this command

Result: OK - append completed

NO - append error: can't append to that mailbox, error

in flags or date/time or message text,

append cancelled

BAD - command unknown or arguments invalid

Crispin Standards Track [Page 2]

RFC 3502 IMAP MULTIAPPEND March 2003

The APPEND command appends the literal arguments as new messages

to the end of the specified destination mailbox. This argument

SHOULD be in the format of an [RFC-2822] message. 8-bit

characters are permitted in the message. A server implementation

that is unable to preserve 8-bit data properly MUST be able to

reversibly convert 8-bit APPEND data to 7-bit using a [MIME-IMB]

content transfer encoding.

Note: There MAY be exceptions, e.g., draft messages, in

which required [RFC-2822] header lines are omitted in the

message literal argument to APPEND. The full implications

of doing so MUST be understood and carefully weighed.

If a flag parenthesized list is specified, the flags SHOULD be set

in the resulting message; otherwise, the flag list of the

resulting message is set empty by default.

If a date-time is specified, the internal date SHOULD be set in

the resulting message; otherwise, the internal date of the

resulting message is set to the current date and time by default.

A zero-length message literal argument is an error, and MUST

return a NO. This can be used to cancel the append.

If the append is unsuccessful for any reason (including being

cancelled), the mailbox MUST be restored to its state before the

APPEND attempt; no partial appending is permitted. The server MAY

return an error before processing all the message arguments.

If the destination mailbox does not exist, a server MUST return an

error, and MUST NOT automatically create the mailbox. Unless it

is certain that the destination mailbox can not be created, the

server MUST send the response code "[TRYCREATE]" as the prefix of

the text of the tagged NO response. This gives a hint to the

client that it can attempt a CREATE command and retry the APPEND

if the CREATE is successful.

If the mailbox is currently selected, the normal new message

actions SHOULD occur. Specifically, the server SHOULD notify the

client immediately via an untagged EXISTS response. If the server

does not do so, the client MAY issue a NOOP command (or failing

that, a CHECK command) after one or more APPEND commands.

Crispin Standards Track [Page 3]

RFC 3502 IMAP MULTIAPPEND March 2003

Example: C: A003 APPEND saved-messages (\Seen) {329}

S: + Ready for literal data

C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST)

C: From: Fred Foobar <foobar></foobar>

C: Subject: afternoon meeting

C: To: mooch@owatagu.example.net

C: Message-Id: <b27397-0100000></b27397-0100000>

C: MIME-Version: 1.0

C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII

C:

C: Hello Joe, do you think we can meet at 3:30 tomorrow?

C: (\Seen) " 7-Feb-1994 22:43:04 -0800" {295}

S: + Ready for literal data

C: Date: Mon, 7 Feb 1994 22:43:04 -0800 (PST)

C: From: Joe Mooch <mooch></mooch>

C: Subject: Re: afternoon meeting

C: To: foobar@blurdybloop.example.com

C: Message-Id: <a0434793874930></a0434793874930>

C: MIME-Version: 1.0

C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII

C:

C: 3:30 is fine with me.

C:

S: A003 OK APPEND completed

C: A004 APPEND bogusname (\Flagged) {1023}

S: A004 NO [TRYCREATE] No such mailbox as bogusname

C: A005 APPEND test (\Flagged) {99}

S: + Ready for literal data

C: Date: Mon, 7 Feb 2000 22:43:04 -0800 (PST)

C: From: Fred Foobar <fred></fred>

C: Subject: hmm...

C: {35403}

S: A005 NO APPEND failed: Disk quota exceeded

Note: The APPEND command is not used for message delivery,

because it does not provide a mechanism to transfer [SMTP]

envelope information.

Modification to IMAP4rev1 Base Protocol Formal Syntax

The following syntax specification uses the Augmented Backus-Naur

Form (ABNF) notation as specified in [ABNF].

append = "APPEND" SP mailbox 1*append-message

append-message = [SP flag-list] [SP date-time] SP literal

Crispin Standards Track [Page 4]

RFC 3502 IMAP MULTIAPPEND March 2003

MULTIAPPEND Interaction with UIDPLUS Extension

Servers which support both MULTIAPPEND and [UIDPLUS] will have the

"resp-code-apnd" rule modified as follows:

resp-code-apnd = "APPENDUID" SP nz-number SP set

That is, the APPENDUID response code returns as many UIDs as there

were messages appended in the multiple append. The UIDs returned

should be in the order the articles where appended. The message set

may not contain extraneous UIDs or the symbol "*".

Security Considerations

The MULTIAPPEND extension does not raise any security considerations

that are not present in the base [IMAP] protocol, and these issues

are discussed in [IMAP]. Nevertheless, it is important to remember

that IMAP4rev1 protocol transactions, including electronic mail data,

are sent in the clear over the network unless protection from

snooping is negotiated, either by the use of STARTTLS, privacy

protection is negotiated in the AUTHENTICATE command, or some other

protection mechanism is in effect.

Normative References

[ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax

Specifications: ABNF", RFC 2234, November 1997.

[IMAP] Crispin, M., "Internet Message Access Protocol - Version

4rev1", RFC 3501, March 2003.

[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate

Requirement Levels", BCP 14, RFC 2119, March 1997.

[MIME-IMB] Freed, N. and N. Borenstein, "MIME (Multipurpose Internet

Mail Extensions) Part One: Format of Internet Message

Bodies", RFC 2045, November 1996.

[RFC-2822] Resnick, P., "Internet Message Format", RFC 2822, April

2001.

Crispin Standards Track [Page 5]

RFC 3502 IMAP MULTIAPPEND March 2003

Informative References

[LITERAL+] Myers, J., "IMAP4 non-synchronizing literals", RFC 2088,

January 1997.

[UIDPLUS] Myers, J., "IMAP4 UIDPLUS extension", RFC 2359, June 1988.

[SMTP] Klensin, J., Editor, "Simple Mail Transfer Protocol", RFC

2821, April 2001.

Author's Address

Mark R. Crispin

Networks and Distributed Computing

University of Washington

4545 15th Avenue NE

Seattle, WA 98105-4527

Phone: (206) 543-5762

EMail: MRC@CAC.Washington.EDU

Crispin Standards Track [Page 6]

RFC 3502 IMAP MULTIAPPEND March 2003

Full Copyright Statement

Copyright (C) The Internet Society (2003). All Rights Reserved.

This document and translations of it may be copied and furnished to

others, and derivative works that comment on or otherwise explain it

or assist in its implementation may be prepared, copied, published

and distributed, in whole or in part, without restriction of any

kind, provided that the above copyright notice and this paragraph are

included on all such copies and derivative works. However, this

document itself may not be modified in any way, such as by removing

the copyright notice or references to the Internet Society or other

Internet organizations, except as needed for the purpose of

developing Internet standards in which case the procedures for

copyrights defined in the Internet Standards process must be

followed, or as required to translate it into languages other than

English.

The limited permissions granted above are perpetual and will not be

revoked by the Internet Society or its successors or assigns.

This document and the information contained herein is provided on an

"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING

TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING

BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION

HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF

MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

Funding for the RFC Editor function is currently provided by the

Internet Society.

Crispin Standards Track [Page 7]

&lt;PRE&gt; Network Working Group M. Crispin Request for Comments: 3502 University of Washington Category: Standards Track March 2003 Internet Message Access Protocol (IMAP) - MULTIAPPEND Extension Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the &quot;Internet Official Protocol Standards&quot; (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract This document describes the multiappending extension to the Internet Message Access Protocol (IMAP) (RFC 3501). This extension provides substantial performance improvements for IMAP clients which upload multiple messages at a time to a mailbox on the server. A server which supports this extension indicates this with a capability name of &quot;MULTIAPPEND&quot;. Terminology The key words &quot;MUST&quot;, &quot;MUST NOT&quot;, &quot;REQUIRED&quot;, &quot;SHALL&quot;, &quot;SHALL NOT&quot;, &quot;SHOULD&quot;, &quot;SHOULD NOT&quot;, &quot;MAY&quot;, and &quot;OPTIONAL&quot; in this document are to be interpreted as described in [KEYWORDS]. Introduction The MULTIAPPEND extension permits uploading of multiple messages with a single command. When used in conjunction with the [LITERAL+] extension, the entire upload is accomplished in a single command/response round trip. A MULTIAPPEND APPEND operation is atomic; either all messages are successfully appended, or no messages are appended. In the base IMAP specification, each message must be appended in a separate command, and there is no mechanism to &quot;unappend&quot; messages if an error occurs while appending. Also, some mail stores may require Crispin Standards Track [Page 1] RFC 3502 IMAP MULTIAPPEND March 2003 an expensive &quot;open/lock + sync/unlock/close&quot; operation as part of appending; this can be quite expensive if it must be done on a per-message basis. If the server supports both LITERAL+ and pipelining but not MULTIAPPEND, it may be possible to get some of the performance advantages of MULTIAPPEND by doing a pipelined &quot;batch&quot; append. However, it will not work as well as MULTIAPPEND for the following reasons: 1) Multiple APPEND commands, even as part of a pipelined batch, are non-atomic by definition. There is no way to revert the mailbox to the state before the batch append in the event of an error. 2) It may not be feasible for the server to coalesce pipelined APPEND operations so as to avoid the &quot;open/lock + sync/unlock/close&quot; overhead described above. In any case, such coalescing would be timing dependent and thus potentially unreliable. In particular, with traditional UNIX mailbox files, it is assumed that a lock is held only for a single atomic operation, and many applications disregard any lock that is older than 5 minutes. 3) If an error occurs, depending upon the nature of the error, it is possible for additional messages to be appended after the error. For example, the user wants to append 5 messages, but a disk quota error occurs with the third message because of its size. However, the fourth and fifth messages have already been sent in the pipeline, so the mailbox ends up with the first, second, fourth, and fifth messages of the batch appended. 6.3.11. APPEND Command Arguments: mailbox name one or more messages to upload, specified as: OPTIONAL flag parenthesized list OPTIONAL date/time string message literal Data: no specific responses for this command Result: OK - append completed NO - append error: can&#039;t append to that mailbox, error in flags or date/time or message text, append cancelled BAD - command unknown or arguments invalid Crispin Standards Track [Page 2] RFC 3502 IMAP MULTIAPPEND March 2003 The APPEND command appends the literal arguments as new messages to the end of the specified destination mailbox. This argument SHOULD be in the format of an [RFC-2822] message. 8-bit characters are permitted in the message. A server implementation that is unable to preserve 8-bit data properly MUST be able to reversibly convert 8-bit APPEND data to 7-bit using a [MIME-IMB] content transfer encoding. Note: There MAY be exceptions, e.g., draft messages, in which required [RFC-2822] header lines are omitted in the message literal argument to APPEND. The full implications of doing so MUST be understood and carefully weighed. If a flag parenthesized list is specified, the flags SHOULD be set in the resulting message; otherwise, the flag list of the resulting message is set empty by default. If a date-time is specified, the internal date SHOULD be set in the resulting message; otherwise, the internal date of the resulting message is set to the current date and time by default. A zero-length message literal argument is an error, and MUST return a NO. This can be used to cancel the append. If the append is unsuccessful for any reason (including being cancelled), the mailbox MUST be restored to its state before the APPEND attempt; no partial appending is permitted. The server MAY return an error before processing all the message arguments. If the destination mailbox does not exist, a server MUST return an error, and MUST NOT automatically create the mailbox. Unless it is certain that the destination mailbox can not be created, the server MUST send the response code &quot;[TRYCREATE]&quot; as the prefix of the text of the tagged NO response. This gives a hint to the client that it can attempt a CREATE command and retry the APPEND if the CREATE is successful. If the mailbox is currently selected, the normal new message actions SHOULD occur. Specifically, the server SHOULD notify the client immediately via an untagged EXISTS response. If the server does not do so, the client MAY issue a NOOP command (or failing that, a CHECK command) after one or more APPEND commands. Crispin Standards Track [Page 3] RFC 3502 IMAP MULTIAPPEND March 2003 Example: C: A003 APPEND saved-messages (\Seen) {329} S: + Ready for literal data C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) C: From: Fred Foobar &lt;FOOBAR@BLURDYBLOOP.EXAMPLE.COM&gt; C: Subject: afternoon meeting C: To: mooch@owatagu.example.net C: Message-Id: &lt;B27397-0100000@BLURDYBLOOP.EXAMPLE.COM&gt; C: MIME-Version: 1.0 C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII C: C: Hello Joe, do you think we can meet at 3:30 tomorrow? C: (\Seen) &quot; 7-Feb-1994 22:43:04 -0800&quot; {295} S: + Ready for literal data C: Date: Mon, 7 Feb 1994 22:43:04 -0800 (PST) C: From: Joe Mooch &lt;MOOCH@OWATAGU.EXAMPLE.NET&gt; C: Subject: Re: afternoon meeting C: To: foobar@blurdybloop.example.com C: Message-Id: &lt;A0434793874930@OWATAGU.EXAMPLE.NET&gt; C: MIME-Version: 1.0 C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII C: C: 3:30 is fine with me. C: S: A003 OK APPEND completed C: A004 APPEND bogusname (\Flagged) {1023} S: A004 NO [TRYCREATE] No such mailbox as bogusname C: A005 APPEND test (\Flagged) {99} S: + Ready for literal data C: Date: Mon, 7 Feb 2000 22:43:04 -0800 (PST) C: From: Fred Foobar &lt;FRED@EXAMPLE.COM&gt; C: Subject: hmm... C: {35403} S: A005 NO APPEND failed: Disk quota exceeded Note: The APPEND command is not used for message delivery, because it does not provide a mechanism to transfer [SMTP] envelope information. Modification to IMAP4rev1 Base Protocol Formal Syntax The following syntax specification uses the Augmented Backus-Naur Form (ABNF) notation as specified in [ABNF]. append = &quot;APPEND&quot; SP mailbox 1*append-message append-message = [SP flag-list] [SP date-time] SP literal Crispin Standards Track [Page 4] RFC 3502 IMAP MULTIAPPEND March 2003 MULTIAPPEND Interaction with UIDPLUS Extension Servers which support both MULTIAPPEND and [UIDPLUS] will have the &quot;resp-code-apnd&quot; rule modified as follows: resp-code-apnd = &quot;APPENDUID&quot; SP nz-number SP set That is, the APPENDUID response code returns as many UIDs as there were messages appended in the multiple append. The UIDs returned should be in the order the articles where appended. The message set may not contain extraneous UIDs or the symbol &quot;*&quot;. Security Considerations The MULTIAPPEND extension does not raise any security considerations that are not present in the base [IMAP] protocol, and these issues are discussed in [IMAP]. Nevertheless, it is important to remember that IMAP4rev1 protocol transactions, including electronic mail data, are sent in the clear over the network unless protection from snooping is negotiated, either by the use of STARTTLS, privacy protection is negotiated in the AUTHENTICATE command, or some other protection mechanism is in effect. Normative References [ABNF] Crocker, D. and P. Overell, &quot;Augmented BNF for Syntax Specifications: ABNF&quot;, RFC 2234, November 1997. [IMAP] Crispin, M., &quot;Internet Message Access Protocol - Version 4rev1&quot;, RFC 3501, March 2003. [KEYWORDS] Bradner, S., &quot;Key words for use in RFCs to Indicate Requirement Levels&quot;, BCP 14, RFC 2119, March 1997. [MIME-IMB] Freed, N. and N. Borenstein, &quot;MIME (Multipurpose Internet Mail Extensions) Part One: Format of Internet Message Bodies&quot;, RFC 2045, November 1996. [RFC-2822] Resnick, P., &quot;Internet Message Format&quot;, RFC 2822, April 2001. Crispin Standards Track [Page 5] RFC 3502 IMAP MULTIAPPEND March 2003 Informative References [LITERAL+] Myers, J., &quot;IMAP4 non-synchronizing literals&quot;, RFC 2088, January 1997. [UIDPLUS] Myers, J., &quot;IMAP4 UIDPLUS extension&quot;, RFC 2359, June 1988. [SMTP] Klensin, J., Editor, &quot;Simple Mail Transfer Protocol&quot;, RFC 2821, April 2001. Author&#039;s Address Mark R. Crispin Networks and Distributed Computing University of Washington 4545 15th Avenue NE Seattle, WA 98105-4527 Phone: (206) 543-5762 EMail: MRC@CAC.Washington.EDU Crispin Standards Track [Page 6] RFC 3502 IMAP MULTIAPPEND March 2003 Full Copyright Statement Copyright (C) The Internet Society (2003). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an &quot;AS IS&quot; basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Crispin Standards Track [Page 7] &lt;/PRE&gt;
live preview
enter atleast 10 characters
WARNING: You mentioned %MENTIONS%, but they cannot see this message and will not be notified
Saving...
Saved
With selected deselect posts show selected posts
All posts under this topic will be deleted ?
Pending draft ... Click to resume editing
Discard draft