7Internet Engineering Task Force (IETF) B. Leiba
8Request for Comments: 6237 Huawei Technologies
9Updates: 4466 A. Melnikov
10Category: Experimental Isode Limited
11ISSN: 2070-1721 May 2011
14 IMAP4 Multimailbox SEARCH Extension
18 The IMAP4 specification allows the searching of only the selected
19 mailbox. A user often wants to search multiple mailboxes, and a
20 client that wishes to support this must issue a series of SELECT and
21 SEARCH commands, waiting for each to complete before moving on to the
22 next. This extension allows a client to search multiple mailboxes
23 with one command, limiting the round trips and waiting for various
24 searches to complete, and not requiring disruption of the currently
25 selected mailbox. This extension also uses MAILBOX and TAG fields in
26 ESEARCH responses, allowing a client to pipeline the searches if it
27 chooses. This document updates RFC 4466.
31 This document is not an Internet Standards Track specification; it is
32 published for examination, experimental implementation, and
35 This document defines an Experimental Protocol for the Internet
36 community. This document is a product of the Internet Engineering
37 Task Force (IETF). It represents the consensus of the IETF
38 community. It has received public review and has been approved for
39 publication by the Internet Engineering Steering Group (IESG). Not
40 all documents approved by the IESG are a candidate for any level of
41 Internet Standard; see Section 2 of RFC 5741.
43 Information about the current status of this document, any errata,
44 and how to provide feedback on it may be obtained at
45 http://www.rfc-editor.org/info/rfc6237.
58Leiba & Melnikov Experimental [Page 1]
60RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
65 Copyright (c) 2011 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 3. Examples ........................................................6
86 4. Formal Syntax ...................................................7
87 5. Security Considerations .........................................8
88 6. IANA Considerations .............................................9
89 7. Acknowledgements ................................................9
90 8. Normative References ............................................9
94 The IMAP4 specification allows the searching of only the selected
95 mailbox. A user often wants to search multiple mailboxes, and a
96 client that wishes to support this must issue a series of SELECT and
97 SEARCH commands, waiting for each to complete before moving on to the
98 next. The commands can't be pipelined, because the server might run
99 them in parallel, and the untagged SEARCH responses could not then be
100 distinguished from each other.
102 This extension allows a client to search multiple mailboxes with one
103 command, and includes MAILBOX and TAG fields in the ESEARCH response,
104 yielding the following advantages:
106 o A single command limits the number of round trips needed to search
109 o A single command eliminates the need to wait for one search to
110 complete before starting the next.
114Leiba & Melnikov Experimental [Page 2]
116RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
119 o A single command allows the server to optimize the search, if it
122 o A command that is not dependent upon the selected mailbox
123 eliminates the need to disrupt the selection state or to open
124 another IMAP connection.
126 o The MAILBOX, UIDVALIDITY, and TAG fields in the responses allow a
127 client to distinguish which responses go with which search (and
128 which mailbox). A client can safely pipeline these search
129 commands without danger of confusion. The addition of the MAILBOX
130 and UIDVALIDITY fields updates the search-correlator item defined
1331.1. Conventions Used in This Document
135 In examples, "C:" indicates lines sent by a client that is connected
136 to a server. "S:" indicates lines sent by the server to the client.
138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
140 document are to be interpreted as described in RFC 2119 [RFC2119].
1422. New ESEARCH Command
144 Arguments: OPTIONAL source options
145 OPTIONAL result options
146 OPTIONAL charset specification (see [RFC2978])
147 searching criteria (one or more)
149 Responses: REQUIRED untagged response: ESEARCH
151 Result: OK -- search completed
152 NO -- error: cannot search that charset or criteria
153 BAD -- command unknown or arguments invalid
155 This section defines a new ESEARCH command, which works similarly to
156 the UID SEARCH command described in Section 2.6.1 of [RFC4466]
157 (initially described in Section 6.4.4 of [RFC3501] and extended by
160 The ESEARCH command further extends searching by allowing for
161 optional source and result options. This document does not define
162 any new result options (see Section 3.1 of [RFC4731]). A server that
163 supports this extension includes "MULTISEARCH" in its IMAP capability
170Leiba & Melnikov Experimental [Page 3]
172RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
175 Because there has been confusion about this, it is worth pointing out
176 that with ESEARCH, as with *any* SEARCH or UID SEARCH command, it
177 MUST NOT be considered an error if the search terms include a range
178 of message numbers that extends (or, in fact, starts) beyond the end
179 of the mailbox. For example, a client might want to establish a
180 rolling window through the search results this way:
182 C: tag1 UID ESEARCH FROM "frobozz" 1:100
184 ...followed later by this:
186 C: tag1 UID ESEARCH FROM "frobozz" 101:200
188 ...and so on. This tells the server to match only the first hundred
189 messages in the mailbox the first time, the second hundred the second
190 time, etc. In fact, it might likely allow the server to optimize the
191 search significantly. In the above example, whether the mailbox
192 contains 50 or 150 or 250 messages, neither of the search commands
193 shown will result in an error. It is up to the client to know when
194 to stop moving its search window.
1962.1. The ESEARCH Response
198 In response to an ESEARCH command, the server MUST return ESEARCH
199 responses [RFC4731] (that is, not SEARCH responses). Because message
200 numbers are not useful for mailboxes that are not selected, the
201 responses MUST contain information about UIDs, not message numbers.
202 This is true even if the source options specify that only the
203 selected mailbox be searched.
205 Presence of a source option in the absence of a result option implies
206 the "ALL" result option (see Section 3.1 of [RFC4731]). Note that
207 this is not the same as the result from the SEARCH command described
208 in the IMAP base protocol [RFC3501].
210 Source options describe which mailboxes must be searched for
211 messages. An ESEARCH command with source options does not affect
212 which mailbox, if any, is currently selected, regardless of which
213 mailboxes are searched.
215 For each mailbox satisfying the source options, a single ESEARCH
216 response MUST be returned if any messages in that mailbox match the
217 search criteria. An ESEARCH response MUST NOT be returned for
218 mailboxes that contain no matching messages. This is true even when
219 result options such as MIN, MAX, and COUNT are specified (see
220 Section 3.1 of [RFC4731]), and the values returned (lowest UID
221 matched, highest UID matched, and number of messages matched,
222 respectively) apply to the mailbox reported in that ESEARCH response.
226Leiba & Melnikov Experimental [Page 4]
228RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
231 Note that it is possible for an ESEARCH command to return *no*
232 untagged responses (no ESEARCH responses at all), in the case that
233 there are no matches to the search in any of the mailboxes that
234 satisfy the source options. Clients can detect this situation by
235 finding the tagged OK response without having received any matching
236 untagged ESEARCH responses.
238 Each ESEARCH response MUST contain the MAILBOX, TAG, and UIDVALIDITY
239 correlators. Correlators allow clients to issue several ESEARCH
240 commands at once (pipelined). If the SEARCHRES [RFC5182] extension
241 is used in an ESEARCH command, that ESEARCH command MUST be executed
242 by the server after all previous SEARCH/ESEARCH commands have
243 completed and before any subsequent SEARCH/ESEARCH commands are
244 executed. The server MAY perform consecutive ESEARCH commands in
245 parallel as long as none of them use the SEARCHRES extension.
2472.2. Source Options: Specifying Mailboxes to Search
249 The source options, if present, MUST contain a mailbox specifier as
250 defined in the IMAP NOTIFY extension [RFC5465], Section 6 (using the
251 "filter-mailboxes" ABNF item), with the following differences:
253 1. The "selected-delayed" specifier is not valid here.
255 2. A "subtree-one" specifier is added. The "subtree" specifier
256 results in a search of the specified mailbox and all selectable
257 mailboxes that are subordinate to it, through an indefinitely
258 deep hierarchy. The "subtree-one" specifier results in a search
259 of the specified mailbox and all selectable child mailboxes, one
260 hierarchy level down.
262 If "subtree" is specified, the server MUST defend against loops in
263 the hierarchy (for example, those caused by recursive file-system
264 links within the message store). The server SHOULD do this by
265 keeping track of the mailboxes that have been searched, and
266 terminating the hierarchy traversal when a repeat is found. If it
267 cannot do that, it MAY do it by limiting the hierarchy depth.
269 If the source options are not present, the value "selected" is
270 assumed -- that is, only the currently selected mailbox is searched.
272 The "personal" source option is a particularly convenient way to
273 search all of the current user's mailboxes. Note that there is no
274 way to use wildcard characters to search all mailboxes; the
275 "mailboxes" source option does not do wildcard expansion.
282Leiba & Melnikov Experimental [Page 5]
284RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
287 If the source options include (or default to) "selected", the IMAP
288 session MUST be in "selected" state. If the source options specify
289 other mailboxes and NOT "selected", then the IMAP session MUST be in
290 either "selected" or "authenticated" state. If the session is not in
291 a correct state, the ESEARCH command MUST return a "BAD" result.
293 If the server supports the SEARCHRES [RFC5182] extension, then the
294 "SAVE" result option is valid *only* if "selected" is specified or
295 defaulted as the sole mailbox to be searched. If any source option
296 other than "selected" is specified, the ESEARCH command MUST return a
299 If the server supports the CONTEXT=SEARCH and/or CONTEXT=SORT
300 extension [RFC5267], then the following additional rules apply:
302 o The CONTEXT return option (Section 4.2 of [RFC5267]) can be used
303 with an ESEARCH command.
305 o If the UPDATE return option is used (Section 4.3 of [RFC5267]), it
306 MUST apply ONLY to the currently selected mailbox. If UPDATE is
307 used and there is no mailbox currently selected, the ESEARCH
308 command MUST return a "BAD" result.
310 o The PARTIAL search return option (Section 4.4 of [RFC5267]) can be
311 used and applies to each mailbox searched by the ESEARCH command.
313 If the server supports the Access Control List (ACL) [RFC4314]
314 extension, then the logged-in user is required to have the "r" right
315 for each mailbox she wants to search. In addition, any mailboxes
316 that are not explicitly named (accessed through "personal" or
317 "subtree", for example) are required to have the "l" right.
318 Mailboxes matching the source options for which the logged-in user
319 lacks sufficient rights MUST be ignored by the ESEARCH command
320 processing. In particular, ESEARCH responses MUST NOT be returned
325 In the following example, note that two ESEARCH commands are
326 pipelined, and that the server is running them in parallel,
327 interleaving a response to the second search amid the responses to
328 the first (watch the tags).
330 C: tag1 ESEARCH IN (mailboxes "folder1" subtree "folder2") unseen
331 C: tag2 ESEARCH IN (mailboxes "folder1" subtree-one "folder2")
333 S: * ESEARCH (TAG "tag1" MAILBOX "folder1" UIDVALIDITY 1) UID ALL
334 4001,4003,4005,4007,4009
338Leiba & Melnikov Experimental [Page 6]
340RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
343 S: * ESEARCH (TAG "tag2" MAILBOX "folder1" UIDVALIDITY 1) UID ALL
345 S: * ESEARCH (TAG "tag1" MAILBOX "folder2/banana" UIDVALIDITY 503)
347 S: * ESEARCH (TAG "tag1" MAILBOX "folder2/peach" UIDVALIDITY 3) UID
350 S: * ESEARCH (TAG "tag2" MAILBOX "folder2/salmon" UIDVALIDITY
351 1111111) UID ALL 50003,50006,50009,50012
356 The following syntax specification uses the Augmented Backus-Naur
357 Form (ABNF) as described in [RFC5234]. Terms not defined here are
358 taken from [RFC3501], [RFC5465], or [RFC4466].
360 command-auth =/ esearch
361 ; Update definition from IMAP base [RFC3501].
362 ; Add new "esearch" command.
364 command-select =/ esearch
365 ; Update definition from IMAP base [RFC3501].
366 ; Add new "esearch" command.
368 filter-mailboxes-other =/ ("subtree-one" SP one-or-more-mailbox)
369 ; Update definition from IMAP Notify [RFC5465].
370 ; Add new "subtree-one" selector.
372 filter-mailboxes-selected = "selected"
373 ; Update definition from IMAP Notify [RFC5465].
374 ; We forbid the use of "selected-delayed".
376 one-correlator = ("TAG" SP tag-string) / ("MAILBOX" SP astring) /
377 ("UIDVALIDITY" SP nz-number)
378 ; Each correlator MUST appear exactly once.
380 scope-option = scope-option-name [SP scope-option-value]
381 ; No options defined here. Syntax for future extensions.
383 scope-option-name = tagged-ext-label
384 ; No options defined here. Syntax for future extensions.
386 scope-option-value = tagged-ext-val
387 ; No options defined here. Syntax for future extensions.
394Leiba & Melnikov Experimental [Page 7]
396RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
399 scope-options = scope-option *(SP scope-option)
400 ; A given option may only appear once.
401 ; No options defined here. Syntax for future extensions.
403 esearch = "ESEARCH" [SP esearch-source-opts]
404 [SP search-return-opts] SP search-program
406 search-correlator = SP "(" one-correlator *(SP one-correlator) ")"
407 ; Updates definition in IMAP4 ABNF [RFC4466].
409 esearch-source-opts = "IN" SP "(" source-mbox [SP
410 "(" scope-options ")"] ")"
412 source-mbox = filter-mailboxes *(SP filter-mailboxes)
413 ; "filter-mailboxes" is defined in IMAP Notify [RFC5465].
414 ; See updated definition of filter-mailboxes-other, above.
415 ; See updated definition of filter-mailboxes-selected, above.
4175. Security Considerations
419 This new IMAP ESEARCH command allows a single command to search many
420 mailboxes at once. On the one hand, a client could do that by
421 sending many IMAP SEARCH commands. On the other hand, this makes it
422 easier for a client to overwork a server, by sending a single command
423 that results in an expensive search of tens of thousands of
424 mailboxes. Server implementations need to be aware of that, and
425 provide mechanisms that prevent a client from adversely affecting
426 other users. Limitations on the number of mailboxes that may be
427 searched in one command, and/or on the server resources that will be
428 devoted to responding to a single client, are reasonable limitations
429 for an implementation to impose.
431 Implementations MUST, of course, apply access controls appropriately,
432 limiting a user's access to ESEARCH in the same way its access is
433 limited for any other IMAP commands. This extension has no data-
434 access risks beyond what may be there in the unextended IMAP
437 Mailboxes matching the source options for which the logged-in user
438 lacks sufficient rights MUST be ignored by the ESEARCH command
439 processing (see the paragraph about this in Section 2.2). In
440 particular, any attempt to distinguish insufficient access from
441 non-existent mailboxes may expose information about the mailbox
442 hierarchy that isn't otherwise available to the client.
444 If "subtree" is specified, the server MUST defend against loops in
445 the hierarchy (see the paragraph about this in Section 2.2).
450Leiba & Melnikov Experimental [Page 8]
452RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
4556. IANA Considerations
457 IMAP4 capabilities are registered by publishing a Standards Track or
458 IESG-approved Experimental RFC. The "IMAP 4 Capabilities" registry
459 is currently located here:
463 This document defines the IMAP capability "MULTISEARCH", and IANA has
464 added it to the registry.
468 The authors gratefully acknowledge feedback provided by Timo
469 Sirainen, Peter Coates, and Arnt Gulbrandsen.
4718. Normative References
473 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
474 Requirement Levels", BCP 14, RFC 2119, March 1997.
476 [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration
477 Procedures", BCP 19, RFC 2978, October 2000.
479 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
480 4rev1", RFC 3501, March 2003.
482 [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
483 RFC 4314, December 2005.
485 [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
486 ABNF", RFC 4466, April 2006.
488 [RFC4731] Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH
489 Command for Controlling What Kind of Information Is
490 Returned", RFC 4731, November 2006.
492 [RFC5182] Melnikov, A., "IMAP Extension for Referencing the Last
493 SEARCH Result", RFC 5182, March 2008.
495 [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for
496 Syntax Specifications: ABNF", STD 68, RFC 5234,
499 [RFC5267] Cridland, D. and C. King, "Contexts for IMAP4", RFC 5267,
506Leiba & Melnikov Experimental [Page 9]
508RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
511 [RFC5465] Gulbrandsen, A., King, C., and A. Melnikov, "The IMAP
512 NOTIFY Extension", RFC 5465, February 2009.
519 Phone: +1 646 827 0648
520 EMail: barryleiba@computer.org
521 URI: http://internetmessagingtechnology.org/
526 5 Castle Business Village
528 Hampton, Middlesex TW12 2BX
531 EMail: Alexey.Melnikov@isode.com
532 URI: http://www.melnikov.ca/
562Leiba & Melnikov Experimental [Page 10]