7Internet Engineering Task Force (IETF) B. Leiba
8Request for Comments: 7377 Huawei Technologies
9Obsoletes: 6237 A. Melnikov
10Updates: 4466 Isode Limited
11Category: Standards Track October 2014
15 IMAP4 Multimailbox SEARCH Extension
19 The IMAP4 specification allows the searching of only the selected
20 mailbox. A user often wants to search multiple mailboxes, and a
21 client that wishes to support this must issue a series of SELECT and
22 SEARCH commands, waiting for each to complete before moving on to the
23 next. This extension allows a client to search multiple mailboxes
24 with one command, limiting the delays caused by many round trips and
25 not requiring disruption of the currently selected mailbox. This
26 extension also uses MAILBOX, UIDVALIDITY, and TAG fields in ESEARCH
27 responses, allowing a client to pipeline the searches if it chooses.
28 This document updates RFC 4466 and obsoletes RFC 6237.
32 This is an Internet Standards Track document.
34 This document is a product of the Internet Engineering Task Force
35 (IETF). It represents the consensus of the IETF community. It has
36 received public review and has been approved for publication by the
37 Internet Engineering Steering Group (IESG). Further information on
38 Internet Standards is available in Section 2 of RFC 5741.
40 Information about the current status of this document, any errata,
41 and how to provide feedback on it may be obtained at
42 http://www.rfc-editor.org/info/rfc7377.
58Leiba & Melnikov Standards Track [Page 1]
60RFC 7377 IMAP4 Multimailbox SEARCH Extension October 2014
65 Copyright (c) 2014 IETF Trust and the persons identified as the
66 document authors. All rights reserved.
68 This document is subject to BCP 78 and the IETF Trust's Legal
69 Provisions Relating to IETF Documents
70 (http://trustee.ietf.org/license-info) in effect on the date of
71 publication of this document. Please review these documents
72 carefully, as they describe your rights and restrictions with respect
73 to this document. Code Components extracted from this document must
74 include Simplified BSD License text as described in Section 4.e of
75 the Trust Legal Provisions and are provided without warranty as
76 described in the Simplified BSD License.
80 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
81 1.1. Conventions Used in This Document . . . . . . . . . . . . . 3
82 2. New ESEARCH Command . . . . . . . . . . . . . . . . . . . . . 3
83 2.1. The ESEARCH Response . . . . . . . . . . . . . . . . . . . 4
84 2.2. Source Options: Specifying Mailboxes to Search . . . . . . 5
85 2.3. Strictness in Search Matches . . . . . . . . . . . . . . . 7
86 2.4. Server-Side Limitations on Search Volume . . . . . . . . . 7
87 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7
88 4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 8
89 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9
90 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
91 7. Changes since RFC 6237 . . . . . . . . . . . . . . . . . . . 10
92 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
93 8.1. Normative References . . . . . . . . . . . . . . . . . . . 10
94 8.2. Informative References . . . . . . . . . . . . . . . . . . 11
95 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 11
96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11
100 The IMAP4 specification allows the searching of only the selected
101 mailbox. A user often wants to search multiple mailboxes, and a
102 client that wishes to support this must issue a series of SELECT and
103 SEARCH commands, waiting for each to complete before moving on to the
104 next. The commands can't be pipelined, because the server might run
105 them in parallel and the untagged SEARCH responses could not then be
106 distinguished from each other.
114Leiba & Melnikov Standards Track [Page 2]
116RFC 7377 IMAP4 Multimailbox SEARCH Extension October 2014
119 This extension allows a client to search multiple mailboxes with one
120 command and includes MAILBOX and TAG fields in the ESEARCH response,
121 yielding the following advantages:
123 o A single command limits the number of round trips needed to search
126 o A single command eliminates the need to wait for one search to
127 complete before starting the next.
129 o A single command allows the server to optimize the search if it
132 o A command that is not dependent upon the selected mailbox
133 eliminates the need to disrupt the selection state or to open
134 another IMAP connection.
136 o The MAILBOX, UIDVALIDITY, and TAG fields in the responses allow a
137 client to distinguish which responses go with which search (and
138 which mailbox). A client can safely pipeline these search
139 commands without danger of confusion. The addition of the MAILBOX
140 and UIDVALIDITY fields updates the search-correlator item defined
143 This extension was previously published in an Experimental RFC.
144 There is now implementation experience, giving confidence in the
145 protocol, so this document puts the extension on the Standards Track,
146 with some minor updates that were informed by the implementation
147 experience. A brief summary of changes is in Section 7.
1491.1. Conventions Used in This Document
151 In examples, "C:" indicates lines sent by a client that is connected
152 to a server, and "S:" indicates lines sent by the server to the
155 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
156 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
157 document are to be interpreted as described in [RFC2119].
1592. New ESEARCH Command
161 Arguments: OPTIONAL source options
162 OPTIONAL result options
163 OPTIONAL charset specification (see [RFC2978])
164 searching criteria (one or more)
166 Responses: REQUIRED untagged response: ESEARCH
170Leiba & Melnikov Standards Track [Page 3]
172RFC 7377 IMAP4 Multimailbox SEARCH Extension October 2014
175 Result: OK -- search completed
176 NO -- error: cannot search that charset or criteria
177 BAD -- command unknown or arguments invalid
179 This section defines a new ESEARCH command, which works similarly to
180 the UID SEARCH command described in Section 2.6.1 of [RFC4466]
181 (initially described in Section 6.4.4 of [RFC3501] and extended by
184 The ESEARCH command further extends searching by allowing for
185 optional source and result options. This document does not define
186 any new result options (see Section 3.1 of [RFC4731]). A server that
187 supports this extension includes "MULTISEARCH" in its IMAP capability
190 Because there has been confusion about this, it is worth pointing out
191 that with ESEARCH, as with any SEARCH or UID SEARCH command, it MUST
192 NOT be considered an error if the search terms include a range of
193 message numbers that extends (or, in fact, starts) beyond the end of
194 the mailbox. For example, a client might want to establish a rolling
195 window through the search results this way:
197 C: tag1 UID ESEARCH FROM "frobozz" 1:100
199 ... followed later by this:
201 C: tag1 UID ESEARCH FROM "frobozz" 101:200
205 This tells the server to match only the first hundred messages in the
206 mailbox the first time, the second hundred the second time, etc. In
207 fact, it might likely allow the server to optimize the search
208 significantly. In the above example, whether the mailbox contains
209 50, 150, or 250 messages, neither of the search commands shown will
210 result in an error. It is up to the client to know when to stop
211 moving its search window.
2132.1. The ESEARCH Response
215 In response to an ESEARCH command, the server MUST return ESEARCH
216 responses [RFC4731] (that is, not SEARCH responses). Because message
217 numbers are not useful for mailboxes that are not selected, the
218 responses MUST contain information about UIDs, not message numbers.
219 This is true even if the source options specify that only the
220 selected mailbox be searched.
226Leiba & Melnikov Standards Track [Page 4]
228RFC 7377 IMAP4 Multimailbox SEARCH Extension October 2014
231 Presence of a source option in the absence of a result option implies
232 the "ALL" result option (see Section 3.1 of [RFC4731]). Note that
233 this is not the same as the result from the SEARCH command described
234 in the IMAP base protocol [RFC3501].
236 Source options describe which mailboxes must be searched for
237 messages. An ESEARCH command with source options does not affect
238 which mailbox, if any, is currently selected, regardless of which
239 mailboxes are searched.
241 For each mailbox satisfying the source options, a single ESEARCH
242 response MUST be returned if any messages in that mailbox match the
243 search criteria. An ESEARCH response MUST NOT be returned for
244 mailboxes that contain no matching messages. This is true even when
245 result options such as MIN, MAX, and COUNT are specified (see
246 Section 3.1 of [RFC4731]), and the values returned (lowest UID
247 matched, highest UID matched, and number of messages matched,
248 respectively) apply to the mailbox reported in that ESEARCH response.
250 Note that it is possible for an ESEARCH command to return no untagged
251 responses (no ESEARCH responses at all) in the case that there are no
252 matches to the search in any of the mailboxes that satisfy the source
253 options. Clients can detect this situation by finding the tagged OK
254 response without having received any matching untagged ESEARCH
257 Each ESEARCH response MUST contain the MAILBOX, TAG, and UIDVALIDITY
258 correlators. Correlators allow clients to issue several ESEARCH
259 commands at once (pipelined). If the SEARCHRES [RFC5182] extension
260 is used in an ESEARCH command, that ESEARCH command MUST be executed
261 by the server after all previous SEARCH/ESEARCH commands have
262 completed and before any subsequent SEARCH/ESEARCH commands are
263 executed. The server MAY perform consecutive ESEARCH commands in
264 parallel as long as none of them use the SEARCHRES extension.
2662.2. Source Options: Specifying Mailboxes to Search
268 The source options, if present, MUST contain a mailbox specifier as
269 defined in the IMAP NOTIFY extension [RFC5465], Section 6 (using the
270 "filter-mailboxes" ABNF item), with the following differences:
272 1. The "selected-delayed" specifier is not valid here.
274 2. A "subtree-one" specifier is added. The "subtree" specifier
275 results in a search of the specified mailbox and all selectable
276 mailboxes that are subordinate to it, through an indefinitely
282Leiba & Melnikov Standards Track [Page 5]
284RFC 7377 IMAP4 Multimailbox SEARCH Extension October 2014
287 deep hierarchy. The "subtree-one" specifier results in a search
288 of the specified mailbox and all selectable child mailboxes, one
289 hierarchy level down.
291 If "subtree" is specified, the server MUST defend against loops in
292 the hierarchy (for example, those caused by recursive file-system
293 links within the message store). The server SHOULD do this by
294 keeping track of the mailboxes that have been searched and by
295 terminating the hierarchy traversal when a repeat is found. If it
296 cannot do that, it MAY do it by limiting the hierarchy depth.
298 If the source options are not present, the value "selected" is
299 assumed -- that is, only the currently selected mailbox is searched.
301 The "personal" source option is a particularly convenient way to
302 search all of the current user's mailboxes. Note that there is no
303 way to use wildcard characters to search all mailboxes; the
304 "mailboxes" source option does not do wildcard expansion.
306 If the source options include (or default to) "selected", the IMAP
307 session MUST be in "selected" state. If the source options specify
308 other mailboxes and NOT "selected", then the IMAP session MUST be in
309 either "selected" or "authenticated" state. If the session is not in
310 a correct state, the ESEARCH command MUST return a "BAD" result.
312 The client SHOULD NOT provide source options that resolve to
313 including the same mailbox more than once. A server can, of course,
314 remove the duplicates before processing, but the server MAY return
315 "BAD" to an ESEARCH command with duplicate source mailboxes.
317 If the server supports the SEARCHRES [RFC5182] extension, then the
318 "SAVE" result option is valid only if "selected" is specified or
319 defaulted to as the sole mailbox to be searched. If any source
320 option other than "selected" is specified, the ESEARCH command MUST
321 return a "BAD" result.
323 If the server supports the CONTEXT=SEARCH and/or CONTEXT=SORT
324 extension [RFC5267], then the following additional rules apply:
326 o The CONTEXT return option (Section 4.2 of [RFC5267]) can be used
327 with an ESEARCH command.
329 o If the UPDATE return option is used (Section 4.3 of [RFC5267]), it
330 MUST apply only to the currently selected mailbox. If UPDATE is
331 used and there is no mailbox currently selected, the ESEARCH
332 command MUST return a "BAD" result.
338Leiba & Melnikov Standards Track [Page 6]
340RFC 7377 IMAP4 Multimailbox SEARCH Extension October 2014
343 o The PARTIAL search return option (Section 4.4 of [RFC5267]) can be
344 used and applies to each mailbox searched by the ESEARCH command.
346 If the server supports the Access Control List (ACL) [RFC4314]
347 extension, then the logged-in user is required to have the "r" right
348 for each mailbox she wants to search. In addition, any mailboxes
349 that are not explicitly named (accessed through "personal" or
350 "subtree", for example) are required to have the "l" right.
351 Mailboxes matching the source options for which the logged-in user
352 lacks sufficient rights MUST be ignored by the ESEARCH command
353 processing. In particular, ESEARCH responses MUST NOT be returned
3562.3. Strictness in Search Matches
358 The base IMAP SEARCH command (Section 6.4.4. of [RFC3501]) requires
359 strict substring matching in text searches. Many servers, however,
360 use search engines that match strings in different ways, for example,
361 matching "swim" to both "swam" and "swum" or only doing full word
362 matching (where "swim" will not match "swimming"). This is covered
363 by the "Fuzzy Search" extension to IMAP [RFC6203], and that extension
364 is compatible with this one and can be combined with it.
366 Whether or not Fuzzy Search is implemented or used, this extension
367 explicitly allows flexible searching with respect to TEXT and BODY
368 searches. Servers MAY use fuzzy text matching in multimailbox
3712.4. Server-Side Limitations on Search Volume
373 To avoid having a search use more than a reasonable share of server
374 resources, servers MAY apply limits that go beyond loop protection,
375 such as limits on the number of mailboxes that may be searched at
376 once and/or limits on the number or total size of messages searched.
377 A server can apply those limits up front, responding with "NO
378 [LIMIT]" if a limit is exceeded (see [RFC5530] for information about
379 response codes). Alternatively, a server can process the search and
380 terminate it when a limit is exceeded, responding with "OK [LIMIT]"
381 and returning partial results. Note that searches that return
382 partial results can cause complexity for client implementations and
387 In the following example, note that two ESEARCH commands are
388 pipelined and that the server is running them in parallel,
389 interleaving a response to the second search amid the responses to
390 the first (watch the tags).
394Leiba & Melnikov Standards Track [Page 7]
396RFC 7377 IMAP4 Multimailbox SEARCH Extension October 2014
399 C: tag1 ESEARCH IN (mailboxes "folder1" subtree "folder2") unseen
400 C: tag2 ESEARCH IN (mailboxes "folder1" subtree-one "folder2")
402 S: * ESEARCH (TAG "tag1" MAILBOX "folder1" UIDVALIDITY 1) UID ALL
403 4001,4003,4005,4007,4009
404 S: * ESEARCH (TAG "tag2" MAILBOX "folder1" UIDVALIDITY 1) UID ALL
406 S: * ESEARCH (TAG "tag1" MAILBOX "folder2/banana" UIDVALIDITY 503)
408 S: * ESEARCH (TAG "tag1" MAILBOX "folder2/peach" UIDVALIDITY 3) UID
411 S: * ESEARCH (TAG "tag2" MAILBOX "folder2/salmon" UIDVALIDITY
412 1111111) UID ALL 50003,50006,50009,50012
417 The following syntax specification uses the Augmented Backus-Naur
418 Form (ABNF) as described in [RFC5234]. Terms not defined here are
419 taken from [RFC3501], [RFC5465], or [RFC4466].
421 command-auth =/ esearch
422 ; Update definition from IMAP base [RFC3501].
423 ; Add new "esearch" command.
425 command-select =/ esearch
426 ; Update definition from IMAP base [RFC3501].
427 ; Add new "esearch" command.
429 filter-mailboxes-other =/ ("subtree-one" SP one-or-more-mailbox)
430 ; Update definition from IMAP Notify [RFC5465].
431 ; Add new "subtree-one" selector.
433 filter-mailboxes-selected = "selected"
434 ; Update definition from IMAP Notify [RFC5465].
435 ; We forbid the use of "selected-delayed".
437 one-correlator = ("TAG" SP tag-string) / ("MAILBOX" SP astring) /
438 ("UIDVALIDITY" SP nz-number)
439 ; Each correlator MUST appear exactly once.
441 scope-option = scope-option-name [SP scope-option-value]
442 ; No options defined here. Syntax for future extensions.
444 scope-option-name = tagged-ext-label
445 ; No options defined here. Syntax for future extensions.
450Leiba & Melnikov Standards Track [Page 8]
452RFC 7377 IMAP4 Multimailbox SEARCH Extension October 2014
455 scope-option-value = tagged-ext-val
456 ; No options defined here. Syntax for future extensions.
458 scope-options = scope-option *(SP scope-option)
459 ; A given option may only appear once.
460 ; No options defined here. Syntax for future extensions.
462 esearch = "ESEARCH" [SP esearch-source-opts]
463 [SP search-return-opts] SP search-program
465 search-correlator = SP "(" one-correlator *(SP one-correlator) ")"
466 ; Updates definition in IMAP4 ABNF [RFC4466].
468 esearch-source-opts = "IN" SP "(" source-mbox [SP
469 "(" scope-options ")"] ")"
471 source-mbox = filter-mailboxes *(SP filter-mailboxes)
472 ; "filter-mailboxes" is defined in IMAP Notify [RFC5465].
473 ; See updated definition of filter-mailboxes-other, above.
474 ; See updated definition of filter-mailboxes-selected, above.
4765. Security Considerations
478 This new IMAP ESEARCH command allows a single command to search many
479 mailboxes at once. On the one hand, a client could do that by
480 sending many IMAP SEARCH commands. On the other hand, this makes it
481 easier for a client to overwork a server by sending a single command
482 that results in an expensive search of tens of thousands of
483 mailboxes. Server implementations need to be aware of that and
484 provide mechanisms that prevent a client from adversely affecting
485 other users. Limitations on the number of mailboxes that may be
486 searched in one command and/or on the server resources that will be
487 devoted to responding to a single client, are reasonable limitations
488 for an implementation to impose (see also Section 2.4).
490 Implementations MUST, of course, apply access controls appropriately,
491 limiting a user's access to ESEARCH in the same way its access is
492 limited for any other IMAP commands. This extension has no data-
493 access risks beyond what may exist in the unextended IMAP
496 Mailboxes matching the source options for which the logged-in user
497 lacks sufficient rights MUST be ignored by the ESEARCH command
498 processing (see the paragraph about this in Section 2.2). In
499 particular, any attempt to distinguish insufficient access from non-
500 existent mailboxes may expose information about the mailbox hierarchy
501 that isn't otherwise available to the client.
506Leiba & Melnikov Standards Track [Page 9]
508RFC 7377 IMAP4 Multimailbox SEARCH Extension October 2014
511 If "subtree" is specified, the server MUST defend against loops in
512 the hierarchy (see the paragraph about this in Section 2.2).
5146. IANA Considerations
516 The "Internet Message Access Protocol (IMAP) Capabilities Registry"
517 is currently located at
518 <http://www.iana.org/assignments/imap-capabilities>.
520 IANA has changed the reference for the IMAP capability "MULTISEARCH"
521 to point to this document.
5237. Changes since RFC 6237
525 o Change to Standards Track.
527 o Added paragraph about duplicate mailboxes.
529 o Added Section 2.3 about Fuzzy Search.
5338.1. Normative References
535 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
536 Requirement Levels", BCP 14, RFC 2119, March 1997,
537 <http://www.rfc-editor.org/info/rfc2119>.
539 [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration
540 Procedures", BCP 19, RFC 2978, October 2000,
541 <http://www.rfc-editor.org/info/rfc2978>.
543 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
544 4rev1", RFC 3501, March 2003,
545 <http://www.rfc-editor.org/info/rfc3501>.
547 [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
548 RFC 4314, December 2005,
549 <http://www.rfc-editor.org/info/rfc4314>.
551 [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
552 ABNF", RFC 4466, April 2006,
553 <http://www.rfc-editor.org/info/rfc4466>.
555 [RFC4731] Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH
556 Command for Controlling What Kind of Information Is
557 Returned", RFC 4731, November 2006,
558 <http://www.rfc-editor.org/info/rfc4731>.
562Leiba & Melnikov Standards Track [Page 10]
564RFC 7377 IMAP4 Multimailbox SEARCH Extension October 2014
567 [RFC5182] Melnikov, A., "IMAP Extension for Referencing the Last
568 SEARCH Result", RFC 5182, March 2008,
569 <http://www.rfc-editor.org/info/rfc5182>.
571 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
572 Specifications: ABNF", STD 68, RFC 5234, January 2008,
573 <http://www.rfc-editor.org/info/rfc5234>.
575 [RFC5267] Cridland, D. and C. King, "Contexts for IMAP4", RFC 5267,
576 July 2008, <http://www.rfc-editor.org/info/rfc5267>.
578 [RFC5465] Gulbrandsen, A., King, C., and A. Melnikov, "The IMAP
579 NOTIFY Extension", RFC 5465, February 2009,
580 <http://www.rfc-editor.org/info/rfc5465>.
582 [RFC5530] Gulbrandsen, A., "IMAP Response Codes", RFC 5530, May
583 2009, <http://www.rfc-editor.org/info/rfc5530>.
5858.2. Informative References
587 [RFC6203] Sirainen, T., "IMAP4 Extension for Fuzzy Search", RFC
589 <http://www.rfc-editor.org/info/rfc6203>.
593 The authors gratefully acknowledge feedback provided by Timo
594 Sirainen, Peter Coates, Arnt Gulbrandsen, and Chris Newman.
601 Phone: +1 646 827 0648
602 EMail: barryleiba@computer.org
603 URI: http://internetmessagingtechnology.org/
609 Hampton, Middlesex TW12 2NP
612 EMail: Alexey.Melnikov@isode.com
613 URI: http://www.melnikov.ca/
618Leiba & Melnikov Standards Track [Page 11]