IMAP PARTIAL Extension for Paged SEARCH and FETCH
updates
Extracted elements (21)
Negative indexing (prepending "-" to range values) was introduced to allow clients to request the most recent results first. The RFC notes this syntax explicitly helps server implementations optimize their SEARCHes by avoiding full-result materialization.
Result indexing in PARTIAL is 1-based and intentionally mirrors IMAP message sequence numbers, so that clients can use familiar offset arithmetic when paginating through large search results.
The PARTIAL FETCH modifier can be combined with the CHANGEDSINCE (CONDSTORE) FETCH modifier. The server first selects the messages in the PARTIAL range and then returns only flag changes with MODSEQ higher than the specified value. The order of PARTIAL and CHANGEDSINCE modifiers in the command is not significant.
This extension is compatible with both IMAP4rev1 (RFC 3501) and IMAP4rev2 (RFC 9051). Section 3.2 applies only if the server advertises "PARTIAL" or "CONTEXT=SEARCH" together with "ESEARCH" and/or IMAP4rev2.
When SAVE and PARTIAL are combined with COUNT, the PARTIAL and COUNT options are returned and the "$" marker always contains references to all messages found by the SEARCH or UID SEARCH command, not just the PARTIAL subset.
When SAVE and PARTIAL are combined with MIN or MAX (without COUNT), the PARTIAL and MIN/MAX results are returned, and the "$" marker contains references to all PARTIAL messages plus the MIN/MAX message. When combined with both MIN and MAX (without COUNT), all three result options are returned and "$" includes PARTIAL, MIN, and MAX messages.
When SAVE and PARTIAL result options are combined without MIN, MAX, or COUNT, the corresponding PARTIAL results are returned and the "$" marker contains references to all messages returned by the PARTIAL option.
A single command MUST NOT contain more than one PARTIAL or ALL search return option; that is, either one PARTIAL, one ALL, or neither PARTIAL nor ALL is allowed in the same SEARCH command.
For SEARCH results, the entire list of results MUST be ordered in mailbox order — that is, in UID or message sequence number order.
Implementations MUST accept capability and keyword strings in a case-insensitive fashion, as the use of uppercase or lowercase characters in token definitions is for editorial clarity only.
An IMAP server advertises support for the PARTIAL extension by including the "PARTIAL" capability in the CAPABILITY response or response code.
Clients can direct the server to start a SEARCH from the latest matching message by prepending "-" to the index. For example, -1 is the last message and -2 is next to last; "PARTIAL -1:-100" returns the 100 most recent results.
The PARTIAL extension extends the UID FETCH command with a PARTIAL FETCH modifier, which has the same syntax as the PARTIAL SEARCH result option. It instructs the server to return FETCH results only for messages in the specified range, useful when the sequence-set parameter includes an unknown number of messages.
The PARTIAL SEARCH return option causes the server to provide in an ESEARCH response a subset of results denoted by the sequence range given as a mandatory argument. The first result (lowest matching UID) is 1, so "PARTIAL 1:500" returns the first 500 results and "PARTIAL 501:1000" the second 500.
When a PARTIAL range references results that do not exist, the server returns only the results that are in the set. If the whole range references no existing results, the server returns the special value "NIL" in the PARTIAL return data item instead of a sequence set.
IANA has added the "PARTIAL" capability to the "IMAP Capabilities" registry with RFC 9394 as the reference. IMAP4 capabilities are registered by publishing a Standards Track or IESG-approved Informational or Experimental RFC.
The extension reduces both server work and data returned to the client, likely reducing memory usage. However, because this is new code in both client and server implementations, rigorous testing is required to avoid introducing new implementation bugs.
The PARTIAL extension does not change the underlying security considerations of IMAP4rev1 or IMAP4rev2. The authors and reviewers believe no new security issues are introduced by these additional capabilities.
The partial-range-first production is defined as "nz-number ":" nz-number", requesting results from oldest (lowest UIDs) to newest. A range 500:400 is treated the same as 400:500; the range cannot contain "*".
The partial-range-last production is defined as "MINUS nz-number ":" MINUS nz-number" (e.g., -500:-400), requesting results from newest (highest UIDs) to oldest. A range -500:-400 is equivalent to -400:-500.
The ret-data-partial response format is "PARTIAL" SP "(" partial-range SP partial-results ")", where partial-range echoes the requested range and partial-results is either a sequence-set or "NIL" when no results correspond to the range.