RFC 4469

RFC 4469: Internet Message Access Protocol (IMAP) CATENATE Extension 💖

Okay bestie, the title block first 📋 This one is by P. Resnick from QUALCOMM Incorporated, dated April 2006. It's a Standards Track doc, so it's a real protocol spec and not just a vibe. It updates RFC 3501 and RFC 3502 🔥 and doesn't obsolete anything. It's in the Network Working Group stream. Now let's get into it 🦋

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 (2006).

Abstract 🌈

Okay so the CATENATE extension to IMAP extends the APPEND command so clients can create messages on the server that mix brand-new data with parts of (or entire) messages that are already sitting on the server 🧚 The big win is that the client can stitch an existing message onto a new one without downloading the data first and uploading it back ✨ No re-upload drama, just vibes 💅

1. Introduction ✨

The CATENATE extension to IMAP [1] lets the client create a message on the server that can include the text of messages (or parts of messages) that already exist on the server, without having to FETCH them and APPEND them back to the server 🦋 It extends the APPEND command so that, instead of one single message literal, the command can take any combo of message literals (as described in IMAP [1]) and message URLs (as described in the IMAP URL Scheme [2] specification) as arguments. The server takes all the pieces and catenates them into the output message 🎀 The CATENATE extension can also hang out with the MULTIAPPEND extension [3] to APPEND multiple messages in a single command 👑

There are some obvious uses, obviously 💀 The motivating use case was giving a resource-constrained client a way to compose a message for later submission that contains data already living in that client's IMAP store. Since the client doesn't have to download and re-upload potentially huge message parts, bandwidth and processing limits don't hit as hard 😭 Also, since the client can build the message in its own IMAP store, it also covers the desire to archive a copy of a sent message without uploading the message twice 🫶 (Mechanisms for actually sending the message are outside the scope of this document, so don't come for that part 🙈)

The extended APPEND command can also copy parts of a message to another mailbox for archival purposes while ditching the undesired parts 🍓 In environments where server storage is limited, a client could get rid of large message parts by copying over only the necessary parts and then deleting the original message. The mechanism could also be used to add data to a message (like prepending message header fields), or to include other data by making a copy of the original and catenating the new data onto it 🌸

2. The CATENATE Capability 💅

A server that supports this extension returns "CATENATE" as one of the responses to the CAPABILITY command. Simple, iconic, no notes 💖

3. The APPEND Command 🎀

Here's the shape of the command 👀

Arguments:  mailbox name
            (The following can be repeated in the presence of the
            MULTIAPPEND extension [3])
            OPTIONAL flag parenthesized list
            OPTIONAL date/time string
            a single message literal or one or more message parts to
            catenate, specified as:
                        message literal
                        or
                        message (or message part) URL

Responses:  OPTIONAL NO responses: BADURL, TOOBIG

Result:     OK -  append completed
            NO -  append error: can't append to that mailbox, error
                  in flags or date/time or message text, or can't
                  fetch that data
            BAD - command unknown or arguments invalid

So the APPEND command glues all the message parts together and tacks them on as a new message at the end of the specified mailbox 🧚 The parenthesized flag list and the date/time string set the flags and the internal date, respectively, as described in IMAP [1]. The parts that come after those are appended one after another onto the output message ✨

If you use the original form of APPEND, a message literal follows the optional flag list and date/time string, and it gets appended just like IMAP [1] describes 🌸 If you use the extended form, you write "CATENATE" followed by a parenthesized list of message literals and message URLs, and each one gets appended to the new message 💜 A message literal is marked with "TEXT", and the octets after the count get appended. A message URL is marked with "URL", and the octets of the body part that URL points to get appended too. It's basically as if the literal you'd get back in a FETCH BODY response were dropped in right where the message part specifier is 🦋 Also, the APPEND command does not set the \Seen flag on any catenated body part, and it does not change the selected mailbox. Main character behavior, honestly 👑

Now the URL stuff, which is where it gets spicy 🌶️ In the extended APPEND command, the string after "URL" is an IMAP URL [2], and it gets interpreted according to the rules in [2]. This document only covers URLs that point at specific messages or message parts on the current IMAP server from the current authenticated IMAP session. So only relative IMAP message or message part URLs (the ones with no scheme or <iserver>) are used. The base URL for resolving a relative URL is imap://user@server/, where "user" is the user name of the currently authenticated user and "server" is the domain name of the current server. When the session is in the selected state, the base URL is imap://user@server/mailbox, where "mailbox" is the encoded name of the currently selected mailbox 🧚 And since APPEND is valid in the authenticated state, no further LOGIN or AUTHENTICATE command gets run for URLs in the extended APPEND command. No re-login, no drama 🫶

Note: Using an absolute IMAP URL, or any URL that points at something other than a message or message part from the current authenticated IMAP session, is outside the scope of this document 🙈 It would need an extension to this specification, and a server implementing only this specification would return NO to such a request. Not it, bestie.

The client is responsible for making sure the catenated message is in the format of an Internet Message Format (RFC 2822) [4] or Multipurpose Internet Mail Extension (MIME) [5] message 💅 When a URL gets catenated, the server copies octets, unchanged, from the indicated message or message part into the catenated message. It doesn't do any data conversion (like MIME transfer encodings), and it doesn't verify that the data is appropriate for the MIME part it's being inserted into. The client is also responsible for inserting appropriate MIME boundaries between body parts, and for writing MIME Content-Type and Content-Transfer-Encoding lines wherever they're needed 😭 So yeah, you're in charge of the vibes there 🌈

Responses behave exactly like the original APPEND command described in IMAP [1] ✨ If the server implements the IMAP UIDPLUS extension [6], it will also return an APPENDUID response code in the tagged OK response 🎀 And if the APPEND command fails, two response codes from Section 4 can show up in the tagged NO response 💖

4. Response Codes 🌸

When an APPEND command fails, it may return a response code describing the reason for the failure 🍓

4.1. BADURL Response 🫶

The BADURL response code is returned if the APPEND fails to process one of the specified URLs 💜 Possible reasons for that are bad URL syntax, an unrecognized URL schema, an invalid message UID, or an invalid body part 🧚 The BADURL response code carries the first URL passed as a parameter to the APPEND command that caused the operation to fail. Finding the culprit has never been easier 🔍

4.2. TOOBIG Response 😭

The TOOBIG response code is returned if the resulting message will exceed the 4-GB IMAP message limit 💀 For example, this might happen if the client specifies 3 URLs for 2-GB messages (3 × 2 GB is way over, bestie 🙈). Even if the server doesn't return TOOBIG, it still has to be defensive against misbehaving or malicious clients that try to construct a message over the 4-GB limit 🔥 The server may also wish to return the TOOBIG response code if the resulting message exceeds a server-specific message size limit 🦋

Appendix A. Examples 🎀

okay bestie, this is the good part 💅 Lines that don't start with C: or S: are just continuations of the line above them, so read them as one message 🫶

The original message in Examples 1 and 2 (UID = 20) is a multipart/mixed MIME message with two body parts 🦋

1. text/plain
2. application/x-zip-compressed

Example 1 shows how a CATENATE client can swap out an attachment in a draft without downloading it to the client and uploading it back. no cap, that's so efficient 🧚

C: A003 APPEND Drafts (\Seen \Draft $MDNSent) CATENATE
 (URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;section=HEADER"
 TEXT {42}
S: + Ready for literal data
C:
C: --------------030308070208000400050907
C:  URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;section=1.MIME"
 URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;section=1" TEXT {42}
S: + Ready for literal data
C:
C: --------------030308070208000400050907
C:  URL "/Drafts;UIDVALIDITY=385759045/;UID=30" TEXT {44}
S: + Ready for literal data
C:
C: --------------030308070208000400050907--
C: )
S: A003 OK catenate append completed

Example 2 is the glow-up 💖 It uses CATENATE to replace edited text in a draft, and also swaps the top-level header fields (the Subject has changed, bestie 😭). The old version gets marked as \Deleted. The server also supports UIDPLUS, so the APPENDUID response code shows up in the successful OK response to APPEND ✨

C: A003 APPEND Drafts (\Seen \Draft $MDNSent) CATENATE (TEXT {738}
S: + Ready for literal data
C: Return-Path: <bar@example.org>
C: Received: from [127.0.0.2]
C:           by rufus.example.org via TCP (internal) with ESMTPA;
C:           Thu, 11 Nov 2004 16:57:07 +0000
C: Message-ID: <419399E1.6000505@example.org>
C: Date: Thu, 12 Nov 2004 16:57:05 +0000
C: From: Bob Ar <bar@example.org>
C: X-Accept-Language: en-us, en
C: MIME-Version: 1.0
C: To: foo@example.net
C: Subject: About our holiday trip
C: Content-Type: multipart/mixed;
C:               boundary="------------030308070208000400050907"
C:
C: --------------030308070208000400050907
C: Content-Type: text/plain; charset=us-ascii; format=flowed
C: Content-Transfer-Encoding: 7bit
C:
C: Our travel agent has sent the updated schedule.
C:
C: Cheers,
C: Bob
C: --------------030308070208000400050907
C:  URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;Section=2.MIME"
 URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;Section=2" TEXT {44}
S: + Ready for literal data
C:
C: --------------030308070208000400050907--
C: )
S: A003 OK [APPENDUID 385759045 45] append Completed
C: A004 UID STORE 20 +FLAGS.SILENT (\Deleted)
S: A004 OK STORE completed

Example 3 is the attachment-stripping era 🍓 CATENATE gets used to strip attachments. Here a PowerPoint attachment gets replaced by a tiny text part that explains the attachment was removed. lowkey iconic ✨

C: A003 APPEND Drafts (\Seen \Draft $MDNSent) CATENATE
 (URL "/Drafts;UIDVALIDITY=385759045/;UID=21/;section=HEADER"
 TEXT {42}
S: + Ready for literal data
C:
C: --------------030308070208000400050903
C:  URL "/Drafts;UIDVALIDITY=385759045/;UID=21/;section=1.MIME"
 URL "/Drafts;UIDVALIDITY=385759045/;UID=21/;section=1" TEXT {255}
S: + Ready for literal data
C:
C: --------------030308070208000400050903
C: Content-type: text/plain; charset="us-ascii"
C: Content-transfer-encoding: 7bit
C:
C: This body part contained a Power Point presentation that was
C: deleted upon your request.
C: --------------030308070208000400050903--
C: )
S: A003 OK append Completed

Example 4 is the failure case 💀 The APPEND doesn't work, and the server returns the BADURL response code to say one of the URLs is invalid. This one also shows how CATENATE can build a digest out of several messages 🌈

C: A003 APPEND Sent (\Seen $MDNSent) CATENATE (TEXT {541}
S: + Ready for literal data
C: Return-Path: <foo@example.org>
C: Received: from [127.0.0.2]
C:           by rufus.example.org via TCP (internal) with ESMTPA;
C:           Thu, 11 Nov 2004 16:57:07 +0000
C: Message-ID: <419399E1.6000505@example.org>
C: Date: Thu, 21 Nov 2004 16:57:05 +0000
C: From: Farren Oo <foo@example.org>
C: X-Accept-Language: en-us, en
C: MIME-Version: 1.0
C: To: bar@example.org
C: Subject: Digest of the mailing list for today
C: Content-Type: multipart/digest;
C:               boundary="------------030308070208000400050904"
C:
C: --------------030308070208000400050904
C:  URL "/INBOX;UIDVALIDITY=785799047/;UID=11467" TEXT {42}
S: + Ready for literal data
C:
C: --------------030308070208000400050904
C:  URL "/INBOX;UIDVALIDITY=785799047/;UID=113330/;section=1.5.9"
 TEXT {42}
S: + Ready for literal data
C:
C: --------------030308070208000400050904
C:  URL "/INBOX;UIDVALIDITY=785799047/;UID=11916" TEXT {44}
S: + Ready for literal data
C:
C: --------------030308070208000400050904--
C: )
S: A003 NO [BADURL "/INBOX;UIDVALIDITY=785799047/;UID=113330;
section=1.5.9"] CATENATE append has failed, one message expunged

Heads up: the server could have checked the URLs as they came in. That means it could have sent the tagged NO response with the BADURL response code instead of a continuation request once the URL arrived 👀

---

9. Normative References 📚

• [1] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", RFC 3501, March 2003.
• [2] Newman, C., "IMAP URL Scheme", RFC 2192, September 1997.
• [3] Crispin, M., "Internet Message Access Protocol (IMAP) - MULTIAPPEND Extension", RFC 3502, March 2003.
• [4] Resnick, P., "Internet Message Format", RFC 2822, April 2001.
• [5] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996.
• [6] Crispin, M., "Internet Message Access Protocol (IMAP) - UIDPLUS extension", RFC 4315, December 2005.
• [7] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005.
• [8] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 ABNF", RFC 4466, April 2006.

Author's Address 🖋️

Peter W. Resnick
QUALCOMM Incorporated
5775 Morehouse Drive
San Diego, CA  92121-1714
US

Phone: +1 858 651 4478
EMail: presnick@qualcomm.com
URI:   http://www.qualcomm.com/~presnick/

Full Copyright Statement 💜

Copyright (C) The Internet Society (2006).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM 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.

Intellectual Property 🦋

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.

Acknowledgement 🫶

Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA).

That's the whole RFC, bestie! 🌈✨