RFC 4315

Internet Message Access Protocol (IMAP) - UIDPLUS extension ✨

Okay bestie, this is RFC 4315 🎀, all about the UIDPLUS extension for IMAP. It was written by M. Crispin in December 2005 💌. It's a Standards Track document, so it's an actual official protocol and not just a vibe 👑. It OBSOLETES RFC 2359, which means 2359 is retired and this one replaces it. It doesn't update any other RFCs.

Status of This Memo 📜

This document specifies an Internet standards track protocol for the Internet community, and it wants discussion and suggestions for improvements. For the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited.

Copyright Notice ©️

Copyright (C) The Internet Society (2005).

Abstract 🌸

UIDPLUS is an extension to the Internet Message Access Protocol (IMAP) that gives you a few features meant to cut down on the time and resources some client operations use 🚀. These features are mostly for disconnected-use clients, the ones that sync up and go offline.

1. Introduction and Overview ✨

The UIDPLUS extension is present in any IMAP server implementation that returns "UIDPLUS" as one of its supported capabilities when the client sends the CAPABILITY command. If you see it in that list, the extension is there 💅.

UIDPLUS adds one new command. It also recommends some new status response codes that SHOULD be returned by all server implementations, even ones that don't implement UIDPLUS 🫶.

The features in UIDPLUS are optimizations. Clients can still do the same things without them by using the base protocol, just less efficiently 🐢.

1.1. Conventions Used in This Document 🦋

In the examples, "C:" marks lines sent by the client and "S:" marks lines sent by the server 💬.

Okay so the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are read the way [KEYWORDS] describes. These words are the official rule-words, so they matter a lot 🙈.

A "UID set" is like the [IMAP] sequence set, with one difference: the "*" value is not allowed for a UID set. No stars allowed here, periodt 🌟.

2. Additional Commands 💖

The command definition below extends [IMAP] section 6.4.

2.1. UID EXPUNGE Command 🗑️

Arguments:  sequence set

Data:       untagged responses: EXPUNGE

Result:     OK - expunge completed
            NO - expunge failure (e.g., permission denied)
            BAD - command unknown or arguments invalid

Main character energy 👑: the UID EXPUNGE command permanently removes every message that has BOTH the \Deleted flag set AND a UID inside the sequence set you gave it, from the currently selected mailbox. Anything without the \Deleted flag, or whose UID isn't in your sequence set, is left alone 🛡️.

This command is especially useful for disconnected use clients 📱. When you resync with the server, use UID EXPUNGE instead of EXPUNGE so you don't accidentally delete messages that other clients marked as \Deleted while you were offline 😭.

If the server doesn't support the UIDPLUS capability, the client should fall back to using the STORE command to temporarily clear the \Deleted flag on the messages it does NOT want removed. Then it issues the EXPUNGE command. Finally, the client uses STORE again to put the \Deleted flag back on the messages it temporarily cleared 🔄.

Or, alternatively, the client may fall back to just the EXPUNGE command, but that risks removing some messages by accident 💀.

Example:

C: A003 UID EXPUNGE 3000:3002
S: * 3 EXPUNGE
S: * 3 EXPUNGE
S: * 3 EXPUNGE
S: A003 OK UID EXPUNGE completed

3. Additional Response Codes 🎀

The response codes below extend the response codes defined in [IMAP] section 7.1. There are a few limited exceptions, which are covered below, but servers that advertise the UIDPLUS extension SHOULD return these response codes 🌈.

If a mailbox lets the client COPY or APPEND to it but NOT SELECT or EXAMINE it, the server SHOULD NOT send an APPENDUID or COPYUID response code. Those codes would reveal info about the mailbox, and that's a no-go 🙅‍♀️.

If a mailbox has UIDNOTSTICKY status (more on that below), the server MAY leave out the APPENDUID or COPYUID response code, since it doesn't mean anything there 🤷‍♀️.

If the server doesn't return APPENDUID or COPYUID, the client can still find out this info by selecting the destination mailbox. The client can work out where messages landed after a COPY or APPEND by using FETCH and/or SEARCH commands. For example, it can search for a Message-ID or some unique marker placed in the message during an APPEND 🔍.

APPENDUID 📨

APPENDUID is followed by the UIDVALIDITY of the destination mailbox and the UID given to the appended message in that destination mailbox. It means the message was appended to the destination mailbox with that UID 💌.

If the server also supports the [MULTIAPPEND] extension, and the client appended multiple messages in one APPEND command, then the second value is a UID set. That UID set has the UIDs given to the appended messages, in the same order they were sent in the APPEND command. This UID set MAY NOT contain extra UIDs or the symbol "". (Note: MAY NOT here is just the plain-English reading of the original, so the strict rule is the key part: no extra UIDs and no "".)

Note: the UID set form of the APPENDUID response code MUST NOT be used if only a single message was appended. In particular, a server MUST NOT send a range like 123:123. Why? A client that doesn't support [MULTIAPPEND] only expects one single UID, not a UID set, so a range would confuse it 🙃.

UIDs are assigned in strictly ascending order in the mailbox (see [IMAP], section 2.3.1.1). UID ranges work as in [IMAP]. Fun fact: a range of 12:10 is exactly the same as 10:12 and refers to 10, 11, 12 🧠.

This response code is returned in a tagged OK response to the APPEND command.

COPYUID 📋

COPYUID is followed by the UIDVALIDITY of the destination mailbox, a UID set holding the UIDs of the message(s) in the source mailbox that got copied, and a UID set holding the UIDs given to the copied message(s) in the destination mailbox. It means those messages were copied to the destination mailbox with the stated UIDs ✨.

The source UID set is listed in the order the messages were copied. The destination UID set matches the source UID set, in the same order. Neither UID set may contain extra UIDs or the symbol "*" 🚫.

UIDs are assigned in strictly ascending order in the mailbox (see [IMAP], section 2.3.1.1). UID ranges work as in [IMAP]. Again, a range of 12:10 is exactly the same as 10:12, so it refers to 10, 11, 12 🌸.

This response code is returned in a tagged OK response to the COPY command.

UIDNOTSTICKY 🫠

The selected mailbox is backed by a mail store that doesn't support persistent UIDs. In other words, UIDVALIDITY will be different every time the mailbox is selected. Because of that, APPEND or COPY to this mailbox will NOT return an APPENDUID or COPYUID response code 😵‍💫.

This response code is returned in an untagged NO response to the SELECT command.

Note: servers SHOULD NOT have any UIDNOTSTICKY mail stores. This facility only exists to support legacy mail stores where it's technically infeasible to support persistent UIDs. You should avoid this when designing new mail stores 🙏.

Example:

C: A003 APPEND saved-messages (\Seen) {297}
C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST)
C: From: Fred Foobar <foobar@example.com>
C: Subject: afternoon meeting
C: To: mooch@example.com
C: Message-Id: <B27397-0100000@example.com>
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:
S: A003 OK [APPENDUID 38505 3955] APPEND completed
C: A004 COPY 2:4 meeting
S: A004 OK [COPYUID 38505 304,319:320 3956:3958] Done
C: A005 UID COPY 305:310 meeting
S: A005 OK No matching messages, so nothing copied
C: A006 COPY 2 funny
S: A006 OK Done
C: A007 SELECT funny
S: * 1 EXISTS
S: * 1 RECENT
S: * OK [UNSEEN 1] Message 1 is first unseen
S: * OK [UIDVALIDITY 3857529045] Validity session-only
S: * OK [UIDNEXT 2] Predicted next UID
S: * NO [UIDNOTSTICKY] Non-persistent UIDs
S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
S: * OK [PERMANENTFLAGS (\Deleted \Seen)] Limited
S: A007 OK [READ-WRITE] SELECT completed

Let's break this example down 🔍. A003 and A004 show a successful append and copy to a mailbox that gives back the UIDs assigned to the messages 💖. A005 copies nothing, and that's because in A003 we learn that message 2 had UID 304 and message 3 had UID 319. So UIDs 305 through 310 don't exist (see section 2.3.1.1 of [IMAP] for more). A006 copies a message and gets no COPYUID back. As expected, A007 shows that the mail store behind that mailbox doesn't support persistent UIDs 🫶.

4. Formal Syntax 📐

Formal syntax is defined using ABNF [ABNF], which extends the ABNF rules defined in [IMAP]. The IMAP4 ABNF should be imported before you try to validate these rules.

append-uid      = uniqueid

capability      =/ "UIDPLUS"
command-select  =/ uid-expunge

resp-code-apnd  = "APPENDUID" SP nz-number SP append-uid

resp-code-copy  = "COPYUID" SP nz-number SP uid-set SP uid-set

resp-text-code  =/ resp-code-apnd / resp-code-copy / "UIDNOTSTICKY"
                  ; incorporated before the expansion rule of
                  ;  atom [SP 1*<any TEXT-CHAR except "]">]
                  ; that appears in [IMAP]

uid-expunge     = "UID" SP "EXPUNGE" SP sequence-set

uid-set         = (uniqueid / uid-range) *("," uid-set)

uid-range       = (uniqueid ":" uniqueid)
                  ; two uniqueid values and all values
                  ; between these two regards of order.
                  ; Example: 2:4 and 4:2 are equivalent.

Servers that support [MULTIAPPEND] get one extra rule on top of the ones above 🎁:

append-uid      =/ uid-set
                  ; only permitted if client uses [MULTIAPPEND]
                  ; to append multiple messages.

5. Security Considerations 🔐

Heads up, this part is serious 😤. The COPYUID and APPENDUID response codes return information about the mailbox. That info may be sensitive if the mailbox's permissions let the client COPY or APPEND to it but NOT SELECT or EXAMINE it.

So these response codes SHOULD NOT be issued if the client doesn't have access to SELECT or EXAMINE the mailbox. Protect that info, bestie 🛡️💜.

6. IANA Considerations 🌍

This document registers the UIDPLUS capability in the imap4-capabilities registry, replacing [RFC2359].

---

To be continued in part 2 🦋✨

7. Normative References 📚

okay bestie, these are the docs this spec literally cannot function without 💅

• [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005.
• [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.
• [MULTIAPPEND] Crispin, M., "Internet Message Access Protocol (IMAP) - MULTIAPPEND Extension", RFC 3502, March 2003.

8. Informative References 🦋

these ones are more of a "read this if you're curious" situation, not a must-read ✨

• [RFC2359] Myers, J., "IMAP4 UIDPLUS extension", RFC 2359, June 1998.

9. Changes from RFC 2359 🌸

okay so this is the glow-up section, and it's giving "here's what changed and why"

this document obsoletes [RFC2359]. but honestly? it's built on that doc and takes a lot of its text. it's just got a ton of clarified wording now, so it reads way cleaner 🫶

[RFC2359] kind of implied that a server has to always send back COPYUID/APPENDUID data. the problem is that this suggests a server should send back arbitrary data when the destination mailbox doesn't support persistent UIDs. 😭 that's messy!!

so this document adds the UIDNOTSTICKY response code. it's how a mailbox says "hey, I don't do persistent UIDs." and it also lays down the rule that a UIDPLUS server does not return COPYUID/APPENDUID data when the COPY (or APPEND) destination mailbox has UIDNOTSTICKY status. that's the fix, periodt 💅

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

Full Copyright Statement 🌈

Copyright (C) The Internet Society (2005).

okay so this doc is subject to the rights, licenses and restrictions in BCP 78. the authors keep all their rights, except for whatever is set out in BCP 78. 🫶

and this is the part where the boilerplate gets real. the document and the info in it come "AS IS." the contributor, the organization they represent or are sponsored by (if any), the Internet Society, and the Internet Engineering Task Force all disclaim every warranty below. this is verbatim so nobody can say they misread it 😭

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 💜

IPR Positions

the IETF doesn't take a side on whether any IP rights claimed around this tech are valid or how far they reach. it also doesn't say whether licenses are available. and it hasn't done its own independent search for those rights either 🙈

if you want the rules on rights in RFC docs, check out BCP 78 and BCP 79. 🍓

IPR Disclosures and Licences

copies of IPR disclosures sent to the IETF Secretariat live in the IETF online IPR repository at http://www.ietf.org/ipr. that's also where you'd find any assurances of licences, or the result of an attempt to get a general license or permission to use the rights. this is for implementers and users of the spec 👑

Invitation to Report

the IETF invites anyone to bring it any copyrights, patents, patent applications, or other proprietary rights that might cover tech needed to implement this standard. send that info to ietf-ipr@ietf.org 🧚

Acknowledgement 🫶

funding for the RFC Editor function is currently provided by the Internet Society. thank you, Internet Society! ✨