IMAP4 Extension to SEARCH Command for Controlling What Kind of Information Is Returned
updated by
- rfc-9394 — IMAP PARTIAL Extension for Paged SEARCH and FETCH
Extracted elements (17)
If the list of result options is empty, this requests an ESEARCH response instead of a SEARCH response, and is equivalent to specifying '(ALL)'. This allows clients to obtain sequence-set formatted results without explicitly requesting ALL.
When a single MIN or MAX result option is specified, servers can optimize SEARCH execution, potentially reducing CPU and I/O load by stopping once the single extreme value is found.
Future extensions to this document may allow servers to return multiple ESEARCH responses for a single extended SEARCH command; such extensions must describe how results from multiple ESEARCH responses are to be amalgamated.
An extended UID SEARCH command MUST cause an ESEARCH response with the UID indicator present.
If one or more result options are specified, the extended SEARCH command MUST return a single ESEARCH response instead of the SEARCH response.
If SEARCH results in no matches, the server MUST NOT include the ALL result option in the ESEARCH response; however, it still MUST send the ESEARCH response.
The client MUST NOT assume that messages/UIDs in the ALL result will be listed in any particular order.
The COUNT result option MUST always be included in the ESEARCH response when requested, even if no messages match.
When both ESEARCH and CONDSTORE extensions are supported and the client requests result options together with the MODSEQ search criterion, the server MUST return an ESEARCH response containing the MODSEQ result option.
The ALL result option returns matching messages using sequence-set syntax (rather than individual message numbers), which may be more compact and can be used directly in subsequent IMAP commands that accept sequence-set arguments.
The ESEARCH capability extends IMAP SEARCH and UID SEARCH commands with result options: MIN (lowest matching message number/UID), MAX (highest matching message number/UID), ALL (all matching messages as sequence-set), and COUNT (number of matching messages).
When CONDSTORE interaction is active: if SEARCH contained only MIN or only MAX, the MODSEQ result contains the mod-sequence for that one found message; if both MIN and MAX with no ALL/COUNT, MODSEQ contains the highest mod-sequence of those two messages; otherwise MODSEQ contains the highest mod-sequence across all returned messages.
This document defines the ESEARCH IMAP capability, which IANA added to the IMAP4 capabilities registry at http://www.iana.org/assignments/imap4-capabilities. New capabilities are registered by publishing a standards track or IESG-approved experimental RFC.
IMAP SEARCH/UID SEARCH commands can be CPU and/or I/O intensive and are a potential attack vector for denial-of-service attacks. The ALL and COUNT result options do not change how SEARCH works internally; MIN and MAX can lighten server load when servers choose to optimize searches containing only those options. This extension is not believed to raise additional security concerns beyond those in RFC 3501.
The ESEARCH capability string is advertised in the IMAP capability list via the ABNF production 'capability =/ "ESEARCH"'.
The search-return-data ABNF production defines: MIN followed by a nz-number, MAX followed by a nz-number, ALL followed by a sequence-set, or COUNT followed by a number. With CONDSTORE, MODSEQ followed by a mod-sequence-value is also permitted.
The search-return-opt tokens are MIN, MAX, ALL, and COUNT; all alphabetic tokens are case-insensitive and implementations MUST accept them in a case-insensitive fashion.