IMAP Extensions: Quick Flag Changes Resynchronization (CONDSTORE) and Quick Mailbox Resynchronization (QRESYNC)
obsoletes
- rfc-4551 — IMAP Extension for Conditional STORE Operation or Quick Flag Changes Resynchronization
- rfc-5162 — IMAP4 Extensions for Quick Mailbox Resynchronization
updates
- rfc-2683 — IMAP4 Implementation Recommendations
Extracted elements (30)
QRESYNC extends SELECT/EXAMINE to perform full resynchronization—including expunged message discovery—in a single round trip, eliminating the need for clients (especially mobile clients subject to frequent disconnects) to hold concurrent IMAP connections or issue separate UID SEARCH commands solely for resynchronization.
RFC 4551 defined mod-sequences as unsigned 64-bit values; this document redefines them as unsigned 63-bit values to simplify implementations on platforms such as Java. The system clock cannot be used directly as a mod-sequence source because NTP adjustments could produce non-monotonic values.
The optional fourth argument to QRESYNC SELECT (sequence number/UID match data) allows clients to provide sample seq-to-UID mappings so the server can restrict the range of reported expunged messages. This is especially effective when no expunges have occurred or all expunges are toward the end of the mailbox, substantially reducing VANISHED response size.
A client implementing CONDSTORE but not QRESYNC may incur an extra round trip when resynchronizing a mailbox that had messages expunged but no flag changes, because the HIGHESTMODSEQ increase causes a CHANGEDSINCE FETCH that returns no data. Clients implementing CONDSTORE are strongly encouraged to also implement QRESYNC.
The presence of the QRESYNC capability implies support for CONDSTORE even if CONDSTORE is not separately advertised. 'ENABLE QRESYNC' and 'ENABLE QRESYNC CONDSTORE' are equivalent and both CONDSTORE enabling commands. Servers SHOULD advertise CONDSTORE in addition to QRESYNC for compatibility with CONDSTORE-only clients.
This document updates RFC 2683's recommended IMAP command line length limit from 1000 octets to approximately 8192 octets (including quoted strings but not literals), because CONDSTORE/QRESYNC clients may send long UID sequences in extended SELECT or FETCH commands that would otherwise trigger server rejections.
After a CONDSTORE enabling command is issued, the server MUST return exactly one of the HIGHESTMODSEQ or NOMODSEQ response codes in an OK untagged response for every successful SELECT/EXAMINE command, depending on whether the mailbox supports persistent mod-sequence storage.
An IMAP server supporting CONDSTORE MUST associate a positive unsigned 63-bit mod-sequence with every message. Each STORE command on the same mailbox MUST receive a different mod-sequence value, and for any two successful STORE operations within a session on the same mailbox, the second completed operation MUST have a greater mod-sequence than the first.
Each mailbox supporting persistent mod-sequence storage MUST increment its per-mailbox mod-sequence when messages are expunged by EXPUNGE, UID EXPUNGE, CLOSE, or MOVE, and MUST associate the incremented mod-sequence with the UIDs of the expunged messages for later QRESYNC queries.
For EXPUNGE and UID EXPUNGE, when QRESYNC is enabled and at least one message was permanently removed, the server MUST send HIGHESTMODSEQ in the tagged OK response. For CLOSE, the server MUST NOT send HIGHESTMODSEQ, as doing so could cause loss of synchronization on the client.
If a client specifies a MODSEQ criterion in a SEARCH (or UID SEARCH) command and the server returns a non-empty result, the server MUST append the highest mod-sequence for all returned messages to the end of the untagged SEARCH response.
Once a client issues a CONDSTORE enabling command, the server MUST include mod-sequence data in all subsequent untagged FETCH responses for the duration of the connection, whether caused by a regular STORE, a conditional STORE, or an external agent.
Once ENABLE QRESYNC is issued, the server MUST automatically include both UID and mod-sequence data in all subsequent untagged FETCH responses, whether caused by STORE/UID STORE, conditional STORE, a FETCH that implicitly sets \Seen, or an external agent.
Servers supporting QRESYNC MUST implement and advertise the ENABLE extension. A client making use of QRESYNC MUST issue 'ENABLE QRESYNC' once authenticated. The server MUST return a tagged BAD if the QRESYNC SELECT parameter or VANISHED UID FETCH modifier is used without a prior successful ENABLE QRESYNC.
The VANISHED UID FETCH modifier MUST only be used together with the CHANGEDSINCE modifier; the server MUST reject it with a tagged BAD otherwise. Any VANISHED (EARLIER) responses resulting from this modifier MUST be returned before any FETCH responses to prevent confusion about message-number-to-UID mapping.
When messages fail the UNCHANGEDSINCE test, the server MUST return a MODIFIED response code listing the failed message numbers or UIDs. An untagged FETCH response including the MODSEQ data item MUST be sent for each message on which the operation succeeded, even if .SILENT was specified.
When QRESYNC is enabled, the server MUST use VANISHED responses instead of EXPUNGE responses for all mailboxes not returning NOMODSEQ. A VANISHED response without EARLIER MUST NOT be sent during FETCH, STORE, or SEARCH commands, and MUST NOT reference UIDs not yet announced to the client.
A modification sequence (mod-sequence) is a positive unsigned 63-bit opaque value associated with every IMAP message, updated by the server whenever a metadata item (such as a flag) is modified. It enables clients to determine exactly which messages have changed since a known point in time.
The CHANGEDSINCE FETCH modifier restricts the set of returned messages to those with a mod-sequence greater than the specified value, and implicitly adds the MODSEQ message data item to the response. It is defined for use with FETCH and UID FETCH commands.
The CLOSED response code has no parameters and is returned when the currently selected mailbox is implicitly closed via SELECT/EXAMINE on another mailbox. Any server advertising QRESYNC or CONDSTORE MUST return it to serve as a clear boundary between responses for the old and new mailboxes.
The HIGHESTMODSEQ response code (OK [HIGHESTMODSEQ <mod-sequence-value>]) is returned during SELECT/EXAMINE when the mailbox supports persistent mod-sequence storage. Its value is the highest mod-sequence of all messages in the mailbox and is used by disconnected clients to decide whether resynchronization is necessary.
The HIGHESTMODSEQ STATUS data item allows a client to check the highest mod-sequence of a mailbox without selecting it. If the mailbox does not support persistent mod-sequence storage, the server MUST return 0 for this item.
The MODSEQ message data item in FETCH causes the server to return per-message mod-sequence values in responses. Once requested, the server includes MODSEQ in all subsequent unsolicited FETCH responses for CONDSTORE-aware clients, covering changes from conditional STOREs and external agents.
The MODSEQ search criterion matches messages whose modification sequence is equal to or greater than a specified value. Optionally, the client may specify an entry-name (e.g., '/flags/\\Seen') and entry-type ('shared', 'priv', or 'all') to narrow the scope to a particular metadata item type.
The NOMODSEQ response code is returned during SELECT/EXAMINE when the mailbox does not support persistent mod-sequence storage. A server that returned NOMODSEQ MUST reject with a tagged BAD any FETCH with CHANGEDSINCE, FETCH/SEARCH with MODSEQ, or STORE with UNCHANGEDSINCE while that mailbox remains selected.
The QRESYNC parameter to SELECT/EXAMINE accepts four arguments: last known UIDVALIDITY, last known modification sequence, an optional set of known UIDs, and an optional parenthesized list of known sequence ranges with corresponding UIDs for match data. If UIDVALIDITY does not match, the server MUST ignore remaining parameters and behave as if no dynamic message data changed.
The UNCHANGEDSINCE STORE modifier causes the server to perform the flag operation only if the mod-sequence of every affected metadata item is at most the specified value. Messages whose mod-sequence exceeds the threshold are skipped and their identifiers are collected into a MODIFIED response code returned at the end.
The VANISHED response reports permanently removed UIDs in two forms: VANISHED (EARLIER), caused by UID FETCH (VANISHED) or SELECT (QRESYNC) and not requiring sequence-number adjustment; and VANISHED without EARLIER, used for real-time expunge notification, which requires the client to decrement message counts. Servers MUST NOT combine the two forms.
This document registers two capabilities in the IANA IMAP4 Capabilities Registry: 'CONDSTORE' for the Conditional STORE extension providing mod-sequence tracking and protected flag updates, and 'QRESYNC' for the Quick Mailbox Resynchronization extension that builds on CONDSTORE to support single-round-trip full resynchronization.
The CONDSTORE and QRESYNC extensions allow clients to retrieve complete metadata change histories for a mailbox. Implementations must ensure that mod-sequence data is only returned to sessions authorized to access the corresponding metadata items; in particular, private metadata changes MUST NOT be reported to sessions authenticated as different users, as shown in the flag-sharing examples.