IMAP UIDPLUS: IMAP4 UIDPLUS extension
Three protocol optimizations that let email clients work more efficiently with IMAP servers.
Myers, J., "IMAP4 UIDPLUS extension", RFC 2359, DOI 10.17487/RFC2359, June 1998, <https://www.rfc-editor.org/info/rfc2359>.
@misc{rfc2359,
series = {Request for Comments},
number = 2359,
howpublished = {RFC 2359},
publisher = {RFC Editor},
doi = {10.17487/RFC2359},
url = {https://www.rfc-editor.org/info/rfc2359},
author = {J. Myers},
title = {{IMAP4 UIDPLUS extension}},
pagetotal = 6,
year = 1998,
month = jun,
} RFC text
Contents
Network Working Group J. Myers
Request for Comments: 2359 Netscape Communications
Category: Standards Track June 1998
IMAP4 UIDPLUS 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 (1998). All Rights Reserved.
IESG NOTE
The IMAP extension described here assumes a particular means of using
IMAP to support disconnected operation. However, this means of
supporting disconnected operation is not yet documented. Also, there
are multiple theories about how best to do disconnected operation in
IMAP, and as yet, there is no consensus on which one should be
adopted as a standard.
This document is being approved as a Proposed Standard because it
does not appear to have technical flaws in itelf. However, approval
of this document as a Proposed Standard should not be considered an
IETF endorsement of any particular means of doing disconnected
operation in IMAP.
Table of Contents
1. Abstract .............................................. 2
2. Conventions Used in this Document ..................... 2
3. Introduction and Overview ............................. 2
4. Features .............................................. 2
4.1. UID EXPUNGE Command ................................... 2
4.2. APPENDUID response code ............................... 3
4.3. COPYUID response code ................................. 4
5. Formal Syntax ......................................... 4
6. References ............................................ 4
7. Security Considerations ............................... 5
8. Author's Address ...................................... 5
9. Full Copyright Statement .............................. 6
1. Abstract
The UIDPLUS extension of the Internet Message Access Protocol [IMAP4]
provides a set of features intended to reduce the amount of time and
resources used by some client operations. The features in UIDPLUS
are primarily intended for disconnected-use clients.
2. Conventions Used in this Document
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively.
The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
in this document are to be interpreted as defined in "Key words for
use in RFCs to Indicate Requirement Levels" [KEYWORDS].
3. Introduction and Overview
The UIDPLUS extension is present in any IMAP4 server implementation
which returns "UIDPLUS" as one of the supported capabilities to the
CAPABILITY command. The UIDPLUS extension contains one additional
command and additional data returned with successful APPEND and COPY
commands.
Clients that wish to use the new command in UIDPLUS must of course
first test for the presence of the extension by issuing a CAPABILITY
command. Each of the features in UIDPLUS are optimizations; clients
can provide the same functionality, albeit more slowly, by using
commands in the base protocol. With each feature, this document
recommends a fallback approach to take when the UIDPLUS extension is
not supported by the server.
4. Features
4.1. UID EXPUNGE Command
Arguments: message set
Data: untagged responses: EXPUNGE
Result: OK - expunge completed
NO - expunge failure (e.g. permission denied)
BAD - command unknown or arguments invalid
The UID EXPUNGE command permanently removes from the currently
selected mailbox all messages that both have the \Deleted flag set
and have a UID that is included in the specified message set. If
a message either does not have the \Deleted flag set or is has a
UID that is not included in the specified message set, it is not
affected.
This command may be used to ensure that a replayed EXPUNGE command
does not remove any messages that have been marked as \Deleted
between the time that the user requested the expunge operation and
the time the server processes the command.
If the server does not support the UIDPLUS capability, the client
should fall back to using the STORE command to temporarily remove
the \Deleted flag from messages it does not want to remove. The
client could alternatively fall back to using the EXPUNGE command,
risking the unintended removal of some messages.
Example: C: A003 UID EXPUNGE 3000:3002
S: * 3 EXPUNGE
S: * 3 EXPUNGE
S: * 3 EXPUNGE
S: A003 OK UID EXPUNGE completed
4.2. APPENDUID response code
Successful APPEND commands return an APPENDUID response code in the
tagged OK response. The APPENDUID response code contains as
arguments the UIDVALIDITY of the destination mailbox and the UID
assigned to the appended message.
If the server does not support the UIDPLUS capability, the client can
only discover this information by selecting the destination mailbox
and issuing FETCH commands.
Example: C: A003 APPEND saved-messages (\Seen) {310}
C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST)
C: From: Fred Foobar <foobar@Blurdybloop.COM>
C: Subject: afternoon meeting
C: To: mooch@owatagu.siam.edu
C: Message-Id: <B27397-0100000@Blurdybloop.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
4.3. COPYUID response code
Successful COPY and UID COPY commands return a COPYUID response code
in the tagged OK response whenever at least one message was copied.
The COPYUID response code contains as an argument the UIDVALIDITY of
the appended-to mailbox, a message set containing the UIDs of the
messages copied to the destination mailbox, in the order they were
copied, and a message containing the UIDs assigned to the copied
messages, in the order they were assigned. Neither of the message
sets may contain extraneous UIDs or the symbol '*'.
If the server does not support the UIDPLUS capability, the client can
only discover this information by selecting the destination mailbox
and issuing FETCH commands.
Example: C: A003 COPY 2:4 MEETING
S: A003 OK [COPYUID 38505 304,319:320 3956:3958] Done
C: A003 UID COPY 305:310 MEETING
S: A003 OK Done
5. Formal Syntax
The following syntax specification uses the augmented Backus-Naur
Form (BNF) notation as specified in [RFC-822] as modified by [IMAP4].
Non-terminals referenced but not defined below are as defined by
[IMAP4].
Except as noted otherwise, all alphabetic characters are case-
insensitive. The use of upper or lower case characters to define
token strings is for editorial clarity only. Implementations MUST
accept these strings in a case-insensitive fashion.
resp_code_apnd ::= "APPENDUID" SPACE nz_number SPACE uniqueid
resp_code_copy ::= "COPYUID" SPACE nz_number SPACE set SPACE set
uid_expunge ::= "UID" SPACE "EXPUNGE" SPACE set
6. References
[IMAP4] Crispin, M., "Internet Message Access Protocol -
Version 4rev1", RFC 2060, December 1996.
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC-822] Crocker, D., "Standard for the Format of ARPA Internet
Text Messages", STD 11, RFC 822, August 1982.
7. Security Considerations
There are no known security issues with this extension.
8. Author's Address
John Gardiner Myers
Netscape Communications
501 East Middlefield Road
Mail Stop MV-029
Mountain View, CA 94043
EMail: jgmyers@netscape.com
9. Full Copyright Statement
Copyright (C) The Internet Society (1998). 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.
AI ELI5
On this page
§1The UIDPLUS Extension
UIDPLUS is an extension to the Internet Message Access Protocol version 4 (IMAP4). The extension provides features intended to reduce the time and resources used by client operations, particularly for clients that work in disconnected mode.
An IMAP4 server advertises support for UIDPLUS by returning UIDPLUS in response to a CAPABILITY command. The extension adds one new command and additional response codes that servers return with successful APPEND and COPY commands. Clients can provide the same functionality without UIDPLUS by using other IMAP4 commands, but more slowly.
IMAP is a protocol that lets your email program talk to a mail server to get messages. UIDPLUS is an add-on that gives the server a way to tell your program faster results when your program asks to add or move messages.
§2The UID EXPUNGE Command
The UID EXPUNGE command permanently removes messages from the currently selected mailbox. Unlike the standard EXPUNGE command, UID EXPUNGE only deletes messages that both have the \Deleted flag set and have a UID (unique identifier) that is included in the specified message set.
This is useful for disconnected clients. When a user marks messages for deletion offline and the mailbox changes before the expunge is replayed to the server, UID EXPUNGE ensures the client only deletes the intended messages. If other messages were marked for deletion in the meantime, they are not affected.
Without UIDPLUS, a client would have to use the STORE command to remove the \Deleted flag from unwanted messages before calling EXPUNGE, or take the risk that EXPUNGE might delete unintended messages.
The UID EXPUNGE command is like saying to the mail server: delete the messages I sent you, and only those messages, rather than delete all messages marked for deletion. This is safer when the server has changed since your last check.
§3APPENDUID Response
When a client appends a new message to a mailbox, the APPENDUID response code tells the client the UID that the server assigned to the new message. The response contains two pieces of information: the UIDVALIDITY value of the destination mailbox and the UID of the appended message.
Without this response, a client would have to select the mailbox and issue FETCH commands to discover which UID the server assigned to the new message. With APPENDUID, the server returns this information immediately with the OK response, saving a round trip.
Example: A003 OK [APPENDUID 38505 3955] APPEND completed tells the client that the message was assigned UID 3955 in a mailbox with UIDVALIDITY 38505.
When you send a new message to the mail server, the server automatically gives it a number. APPENDUID makes the server tell you the number right away, so you do not have to ask the server a second time.
§4COPYUID Response
When a client copies one or more messages to another mailbox, the COPYUID response code provides three pieces of information: the UIDVALIDITY of the destination mailbox, the UIDs of the messages copied from the source mailbox (in the order they were copied), and the UIDs assigned to those messages in the destination mailbox (in the order they were assigned).
This allows a client to track which source messages were copied to which destination UIDs without additional server queries. The response only appears when at least one message was successfully copied.
Example: A003 OK [COPYUID 38505 304,319:320 3956:3958] Done indicates three messages (304, 319, and 320) were copied from the source and assigned UIDs 3956, 3957, and 3958 in the destination mailbox.
When you copy messages to a different folder, COPYUID tells you which messages you copied and what numbers they got in the new folder. Without this, you would need to look in the new folder to figure out which message is which.
§5Use in Disconnected Clients
UIDPLUS is specifically designed for clients that download messages for offline reading and later sync changes back to the server. These clients must track which local messages correspond to which server UIDs.
When an offline client appends new messages, APPENDUID ensures the client immediately learns the server UIDs assigned to those messages. When copying or moving messages, COPYUID provides the mapping between source and destination UIDs. The UID EXPUNGE command lets the client safely delete messages even if the mailbox was modified between the download and the sync.
The RFC notes that the means of supporting disconnected operation in IMAP was not yet fully documented, and there was no consensus on the best approach. However, UIDPLUS provides useful optimizations for any IMAP client strategy.
Email programs that work offline need to remember which messages they sent to the server and what the server called them. UIDPLUS helps these programs keep track without needing to ask the server a lot of extra questions.