IMAP4 Multimailbox SEARCH Extension
obsoletes
- rfc-6237 — IMAP4 Multimailbox SEARCH Extension
updates
- rfc-4466 — Collected Extensions to IMAP4 ABNF
Extracted elements (25)
The MAILBOX, UIDVALIDITY, and TAG correlators in each ESEARCH response allow a client to safely pipeline multiple ESEARCH commands without waiting for each to complete, since responses from different commands and mailboxes can be unambiguously matched. This was the primary motivation for using ESEARCH over untagged SEARCH.
The 'subtree-one' specifier was added (not present in RFC 5465's filter-mailboxes) to allow one-level-deep subtree searches, giving clients a middle ground between searching a single mailbox and an arbitrarily deep hierarchy.
UIDs are used instead of message numbers in ESEARCH responses because message numbers are only meaningful in the context of the selected mailbox; searching non-selected mailboxes makes message numbers inapplicable. Using UIDs universally keeps the response model consistent.
The Fuzzy Search extension (RFC 6203) is compatible with MULTISEARCH. This document explicitly permits flexible (fuzzy) text matching for TEXT and BODY searches in multimailbox searches; servers MAY use fuzzy matching even without the Fuzzy Search extension.
This document obsoletes RFC 6237 (Experimental) and promotes the extension to Standards Track. Changes include: addition of a paragraph on duplicate source mailboxes (server MAY return BAD), and addition of Section 2.3 explicitly permitting fuzzy text matching in multimailbox searches.
When the CONTEXT=SEARCH/SORT extension is used together with ESEARCH: the UPDATE return option MUST apply only to the currently selected mailbox and MUST return BAD if no mailbox is selected; the PARTIAL return option applies per mailbox searched.
Each ESEARCH response MUST contain the MAILBOX, TAG, and UIDVALIDITY correlators to allow clients to distinguish responses when multiple ESEARCH commands are pipelined.
For each mailbox satisfying the source options, a single ESEARCH response MUST be returned if any messages in that mailbox match the search criteria; an ESEARCH response MUST NOT be returned for mailboxes that contain no matching messages.
If source options are absent, the value 'selected' is assumed, meaning only the currently selected mailbox is searched. Presence of a source option without a result option implies the 'ALL' result option.
If source options include or default to 'selected', the IMAP session MUST be in 'selected' state. If source options specify other mailboxes and not 'selected', the session MUST be in 'selected' or 'authenticated' state; otherwise the ESEARCH command MUST return a BAD result.
If 'subtree' is specified, the server MUST defend against loops in the mailbox hierarchy (e.g., from recursive filesystem links). It SHOULD track visited mailboxes and stop traversal on a repeat; if it cannot, it MAY limit hierarchy depth.
If the SEARCHRES extension is used in an ESEARCH command, that command MUST be executed after all previous SEARCH/ESEARCH commands complete and before any subsequent ones; the server MAY run consecutive ESEARCH commands in parallel only when none use SEARCHRES.
If the server supports SEARCHRES, the SAVE result option is valid in ESEARCH only if 'selected' is the sole mailbox being searched. If any other source option is specified, the ESEARCH command MUST return a BAD result.
If the server supports the ACL extension, the user must have the 'r' right for explicitly named mailboxes and the 'l' right for implicitly included ones (e.g., via 'personal' or 'subtree'). Mailboxes for which the user lacks rights MUST be silently ignored; ESEARCH responses MUST NOT be returned for them.
In response to an ESEARCH command, the server MUST return ESEARCH responses (not SEARCH responses), and the responses MUST contain UID information, not message numbers — even if source options specify only the selected mailbox.
It MUST NOT be considered an error if search terms include a range of message numbers that extends beyond the end of the mailbox. This allows clients to implement a rolling search window efficiently.
Servers MAY apply resource limits on multi-mailbox searches (e.g., mailbox count or total message size). A server MAY respond 'NO [LIMIT]' upfront if a limit is exceeded, or 'OK [LIMIT]' with partial results after terminating a search mid-execution.
Source options use the 'filter-mailboxes' specifier from RFC 5465, with two modifications: 'selected-delayed' is forbidden, and a new 'subtree-one' specifier is added that searches the named mailbox plus all selectable direct children (one hierarchy level down), unlike 'subtree' which descends indefinitely.
The ESEARCH command extends IMAP searching by accepting optional source options (IN clause specifying mailboxes), optional result options, an optional charset, and one or more search criteria. A server supporting this extension advertises 'MULTISEARCH' in its IMAP capability string.
The search-correlator item is extended to include a MAILBOX (astring), UIDVALIDITY (nz-number), and TAG (tag-string) field; each correlator MUST appear exactly once per ESEARCH response. These fields allow a client to match responses to commands when pipelining multiple ESEARCH commands.
The IMAP Capabilities Registry entry for the 'MULTISEARCH' capability is updated to reference this document (RFC 7377), superseding the earlier Experimental RFC 6237.
A single ESEARCH command can trigger expensive searches across tens of thousands of mailboxes, creating a resource-exhaustion vector not easily possible with standard per-mailbox SEARCH commands. Servers must implement per-client resource limits and per-search mailbox count limits to prevent one client from adversely affecting others.
Access controls MUST be applied to ESEARCH identically to any other IMAP command. Mailboxes for which the user lacks rights must be silently ignored; distinguishing 'insufficient access' from 'non-existent mailbox' in error responses could expose information about the mailbox hierarchy that is not otherwise available.
When 'subtree' is used, the server MUST defend against hierarchy loops to prevent infinite traversal; failure to do so could itself become a denial-of-service vector.
The ESEARCH command ABNF is: 'ESEARCH [SP esearch-source-opts] [SP search-return-opts] SP search-program', where esearch-source-opts is 'IN SP ( source-mbox [SP ( scope-options )] )' and source-mbox is one or more filter-mailboxes items separated by SP.