5Internet Engineering Task Force (IETF) A. Melnikov
6Request for Comments: 9394 Isode
7Updates: 4731, 5267 A. P. Achuthan
8Category: Standards Track V. Nagulakonda
14 IMAP PARTIAL Extension for Paged SEARCH and FETCH
18 The PARTIAL extension of the Internet Message Access Protocol (see
19 RFCs 3501 and 9051) allows clients to limit the number of SEARCH
20 results returned, as well as to perform incremental (paged) searches.
21 This also helps servers to optimize resource usage when performing
24 This document extends the PARTIAL SEARCH return option originally
25 specified in RFC 5267. It also clarifies some interactions between
26 RFC 5267 and RFCs 4731 and 9051.
28 This document updates RFCs 4731 and 5267.
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 7841.
40 Information about the current status of this document, any errata,
41 and how to provide feedback on it may be obtained at
42 https://www.rfc-editor.org/info/rfc9394.
46 Copyright (c) 2023 IETF Trust and the persons identified as the
47 document authors. All rights reserved.
49 This document is subject to BCP 78 and the IETF Trust's Legal
50 Provisions Relating to IETF Documents
51 (https://trustee.ietf.org/license-info) in effect on the date of
52 publication of this document. Please review these documents
53 carefully, as they describe your rights and restrictions with respect
54 to this document. Code Components extracted from this document must
55 include Revised BSD License text as described in Section 4.e of the
56 Trust Legal Provisions and are provided without warranty as described
57 in the Revised BSD License.
59 This document may contain material from IETF Documents or IETF
60 Contributions published or made publicly available before November
61 10, 2008. The person(s) controlling the copyright in some of this
62 material may not have granted the IETF Trust the right to allow
63 modifications of such material outside the IETF Standards Process.
64 Without obtaining an adequate license from the person(s) controlling
65 the copyright in such materials, this document may not be modified
66 outside the IETF Standards Process, and derivative works of it may
67 not be created outside the IETF Standards Process, except to format
68 it for publication as an RFC or to translate it into languages other
73 1. Introduction and Overview
74 2. Document Conventions
75 3. The PARTIAL Extension
76 3.1. Incremental SEARCH and Partial Results
77 3.2. Interaction between PARTIAL, MIN, MAX, and SAVE SEARCH
79 3.3. Extension to UID FETCH
80 3.4. Use of "PARTIAL" and "CONDSTORE" IMAP Extensions Together
82 5. Security Considerations
83 6. IANA Considerations
84 6.1. Changes/Additions to the IMAP Capabilities Registry
86 7.1. Normative References
87 7.2. Informative References
911. Introduction and Overview
93 This document defines an extension to the Internet Message Access
94 Protocol [RFC3501] [RFC9051] for performing incremental searches and
95 fetches. This extension is compatible with both IMAP4rev1 [RFC3501]
96 and IMAP4rev2 [RFC9051]. This extension uses IMAP extensibility
97 rules defined in [RFC4466].
99 The PARTIAL extension of the Internet Message Access Protocol allows
100 clients to limit the number of SEARCH results returned, as well as to
101 perform incremental (paged) searches. This also helps servers to
102 optimize resource usage when performing searches.
104 This document extends the PARTIAL SEARCH return option originally
105 specified in RFC 5267. It also clarifies some interactions between
106 RFC 5267 and RFCs 4731 and 9051.
1082. Document Conventions
110 In protocol examples, this document uses a prefix of "C: " to denote
111 lines sent by the client to the server and "S: " for lines sent by
112 the server to the client. Lines prefixed with "// " are comments
113 explaining the previous protocol line. These prefixes and comments
114 are not part of the protocol. Lines without any of these prefixes
115 are continuations of the previous line, and no line breaks are
116 present in the protocol unless specifically mentioned.
118 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
119 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
120 "OPTIONAL" in this document are to be interpreted as described in
121 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
122 capitals, as shown here.
124 Other capitalized words are IMAP key words [RFC3501] [RFC9051] or key
125 words from this document.
1273. The PARTIAL Extension
129 An IMAP server advertises support for the PARTIAL extension by
130 including the "PARTIAL" capability in the CAPABILITY response /
1333.1. Incremental SEARCH and Partial Results
135 The PARTIAL SEARCH return option causes the server to provide in an
136 ESEARCH response [RFC4731] [RFC9051] a subset of the results denoted
137 by the sequence range given as the mandatory argument. The first
138 result (message with the lowest matching Unique Identifier (UID)) is
139 1; thus, the first 500 results would be obtained by a return option
140 of "PARTIAL 1:500" and the second 500 by "PARTIAL 501:1000". This
141 intentionally mirrors message sequence numbers.
143 It is also possible to direct the server to start the SEARCH from the
144 latest matching (with the highest UID) message. This can be done by
145 prepending "-" to the index. For example, -1 is the last message, -2
146 is next to the last, and so on. Using this syntax helps server
147 implementations to optimize their SEARCHes.
149 A single command MUST NOT contain more than one PARTIAL or ALL search
150 return option; that is, either one PARTIAL, one ALL, or neither
151 PARTIAL nor ALL is allowed.
153 For SEARCH results, the entire list of results MUST be ordered in
154 mailbox order -- that is, in UID or message sequence number order.
156 In cases where a PARTIAL SEARCH return option references results that
157 do not exist by using a range that starts or ends higher (or lower)
158 than the current number of results, the server returns the results
159 that are in the set. This yields a PARTIAL return data item that
160 has, as payload, the original range and a potentially missing set of
161 results that may be shorter than the extent of the range. If the
162 whole range references results that do not exist, a special value
163 "NIL" is returned by the server instead of the sequence set.
165 Clients need not request PARTIAL results in any particular order.
166 Because mailboxes may change, clients might wish to use PARTIAL in
167 combination with UPDATE (see [RFC5267]) if the server also advertises
168 the "CONTEXT=SEARCH" capability, especially if the intent is to walk
169 a large set of results; however, these return options do not interact
170 -- the UPDATE will provide notifications for all matching results.
172 // Let's assume that the A01 SEARCH without PARTIAL would return
174 C: A01 UID SEARCH RETURN (PARTIAL -1:-100) UNDELETED
176 S: * ESEARCH (TAG "A01") UID PARTIAL (-1:-100 ...)
177 // 100 most recent results in set syntax elided.
180 // Let's assume that the A02 SEARCH without PARTIAL would return
182 C: A02 UID SEARCH RETURN (PARTIAL 23500:24000) UNDELETED
184 C: A03 UID SEARCH RETURN (PARTIAL 1:500) UNDELETED
186 C: A04 UID SEARCH RETURN (PARTIAL 24000:24500) UNDELETED
188 S: * ESEARCH (TAG "A02") UID PARTIAL (23500:24000 ...)
189 // 264 results in set syntax elided;
190 // this spans the end of the results.
192 S: * ESEARCH (TAG "A03") UID PARTIAL (1:500 ...)
193 // 500 results in set syntax elided.
195 S: * ESEARCH (TAG "A04") UID PARTIAL (24000:24500 NIL)
196 // No results are present; this is beyond the end of the results.
1993.2. Interaction between PARTIAL, MIN, MAX, and SAVE SEARCH Return
202 This section only applies if the server advertises the "PARTIAL" IMAP
203 capability or "CONTEXT=SEARCH" [RFC5267], together with "ESEARCH"
204 [RFC4731] and/or IMAP4rev2 [RFC9051].
206 The SAVE result option doesn't change whether the server would return
207 items corresponding to PARTIAL SEARCH result options.
209 As specified in Section 3.1, it is an error to specify both the
210 PARTIAL and ALL result options in the same SEARCH command.
212 When the SAVE result option is combined with the PARTIAL result
213 option and none of the MIN/MAX/COUNT result options are present, the
214 corresponding PARTIAL is returned, and the "$" marker would contain
215 references to all messages returned by the PARTIAL result option.
217 When the SAVE and PARTIAL result options are combined with the MIN or
218 MAX result option and the COUNT result option is absent, the
219 corresponding PARTIAL result and MIN/MAX are returned (if the SEARCH
220 result is not empty), and the "$" marker would contain references to
221 all messages returned by the PARTIAL result option together with the
222 corresponding MIN/MAX message.
224 If the SAVE and PARTIAL result options are combined with both the MIN
225 and MAX result options and the COUNT result option is absent, the
226 PARTIAL, MIN, and MAX result options are returned (if the SEARCH
227 result is not empty), and the "$" marker would contain references to
228 all messages returned by the PARTIAL result option together with the
229 MIN and MAX messages.
231 If the SAVE and PARTIAL result options are combined with the COUNT
232 result option, the PARTIAL and COUNT result options are returned, and
233 the "$" marker would always contain references to all messages found
234 by the SEARCH or UID SEARCH command.
236 Table 1 summarizes additional requirements for ESEARCH server
237 implementations described in this section.
239 Note regarding Table 1: "[m]" means optional "MIN" and/or "MAX".
241 +===============================+=====================+
242 | Combination of Result Options | "$" Marker Value |
243 +===============================+=====================+
244 | SAVE PARTIAL | PARTIAL |
245 +-------------------------------+---------------------+
246 | SAVE PARTIAL MIN | PARTIAL & MIN |
247 +-------------------------------+---------------------+
248 | SAVE PARTIAL MAX | PARTIAL & MAX |
249 +-------------------------------+---------------------+
250 | SAVE PARTIAL MIN MAX | PARTIAL & MIN & MAX |
251 +-------------------------------+---------------------+
252 | SAVE PARTIAL COUNT [m] | all found messages |
253 +-------------------------------+---------------------+
2573.3. Extension to UID FETCH
259 The PARTIAL extension also extends the UID FETCH command with a
260 PARTIAL FETCH modifier. The PARTIAL FETCH modifier has the same
261 syntax as the PARTIAL SEARCH result option. The presence of the
262 PARTIAL FETCH modifier instructs the server to only return FETCH
263 results for messages in the specified range. It is useful when the
264 sequence-set (first) parameter in the UID FETCH command includes an
265 unknown number of messages.
267 // Returning information for the last 3 messages in the UID range
268 C: 10 UID FETCH 25900:26600 (UID FLAGS) (PARTIAL -1:-3)
269 S: * 12888 FETCH (FLAGS (\Seen) UID 25996)
270 S: * 12889 FETCH (FLAGS (\Flagged \Answered) UID 25997)
271 S: * 12890 FETCH (FLAGS () UID 26600)
272 S: 10 OK FETCH completed
274 // Returning information for the first 5 messages in the UID range
275 C: 11 UID FETCH 25900:26600 (UID FLAGS) (PARTIAL 1:5)
276 S: * 12591 FETCH (FLAGS (\Seen) UID 25900)
277 S: * 12592 FETCH (FLAGS (\Flagged) UID 25902)
278 S: * 12593 FETCH (FLAGS (\Answered) UID 26310)
279 S: * 12594 FETCH (FLAGS () UID 26311)
280 S: * 12595 FETCH (FLAGS (\Answered) UID 26498)
281 S: 11 OK FETCH completed
2833.4. Use of "PARTIAL" and "CONDSTORE" IMAP Extensions Together
285 This section is informative.
287 The PARTIAL FETCH modifier can be combined with the CHANGEDSINCE
288 FETCH modifier [RFC7162].
290 // Returning information for the last 30 messages in the UID range
291 // that have any flags/keywords modified since MODSEQ 98305
292 C: 101 UID FETCH 25900:26600 (UID FLAGS
293 ) (PARTIAL -1:-30 CHANGEDSINCE 98305)
294 S: * 12888 FETCH (FLAGS (\Flagged \Answered
295 ) MODSEQ (98306) UID 25997)
296 S: * 12890 FETCH (FLAGS () MODSEQ (98312) UID 26600)
297 S: 101 OK FETCH completed
299 The above example causes the server to first select the last 30
300 messages and then only return flag changes for a subset of those
301 messages that have MODSEQ higher than 98305.
303 Note that the order of PARTIAL and CHANGEDSINCE FETCH modifiers in
304 the UID FETCH command is not important, i.e., the above example can
305 also use the "UID FETCH 25900:26600 (UID FLAGS) (CHANGEDSINCE 98305
306 PARTIAL -1:-30)" command and it would result in the same responses.
310 The following syntax specification uses the Augmented Backus-Naur
311 Form (ABNF) notation as specified in [ABNF].
313 Non-terminals referenced but not defined below are as defined by
314 IMAP4rev1 [RFC3501] or IMAP4rev2 [RFC9051].
316 Except as noted otherwise, all alphabetic characters are case
317 insensitive. The use of uppercase or lowercase characters to define
318 token strings is for editorial clarity only. Implementations MUST
319 accept these strings in a case-insensitive fashion.
321 SP = <Defined in RFC 5234>
324 capability =/ "PARTIAL"
325 ;; <capability> from [RFC3501].
327 modifier-partial = "PARTIAL" SP partial-range
329 partial-range-first = nz-number ":" nz-number
330 ;; Request to search from oldest (lowest UIDs) to
331 ;; more recent messages.
332 ;; A range 500:400 is the same as 400:500.
333 ;; This is similar to <seq-range> from [RFC3501]
334 ;; but cannot contain "*".
336 partial-range-last = MINUS nz-number ":" MINUS nz-number
337 ;; Request to search from newest (highest UIDs) to
339 ;; A range -500:-400 is the same as -400:-500.
341 partial-range = partial-range-first / partial-range-last
343 search-return-opt =/ modifier-partial
344 ;; All conform to <search-return-opt> from
345 ;; [RFC4466] and [RFC9051].
347 search-return-data =/ ret-data-partial
349 ret-data-partial = "PARTIAL"
350 SP "(" partial-range SP partial-results ")"
351 ;; <partial-range> is the requested range.
353 partial-results = sequence-set / "NIL"
354 ;; <sequence-set> from [RFC3501].
355 ;; NIL indicates that no results correspond to
356 ;; the requested range.
358 tagged-ext-simple =/ partial-range-last
360 fetch-modifier =/ modifier-partial
361 ;; <fetch-modifier> from [RFC4466].
3635. Security Considerations
365 This document defines an additional IMAP4 capability. As such, it
366 does not change the underlying security considerations of IMAP4rev1
367 [RFC3501] and IMAP4rev2 [RFC9051]. The authors and reviewers believe
368 that no new security issues are introduced with these additional
371 This document defines an optimization that can reduce both the amount
372 of work performed by the server and the amount of data returned to
373 the client. Use of this extension is likely to cause the server and
374 the client to use less memory than when the extension is not used.
375 However, as this is going to be new code in both the client and the
376 server, rigorous testing of such code is required in order to avoid
377 introducing new implementation bugs.
3796. IANA Considerations
3816.1. Changes/Additions to the IMAP Capabilities Registry
383 IMAP4 capabilities are registered by publishing a Standards Track or
384 IESG-approved Informational or Experimental RFC. The registry is
385 currently located at <https://www.iana.org/assignments/imap-
388 IANA has added the PARTIAL extension to the "IMAP Capabilities"
389 registry with RFC 9394 as the reference.
3937.1. Normative References
395 [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
396 Specifications: ABNF", STD 68, RFC 5234,
397 DOI 10.17487/RFC5234, January 2008,
398 <https://www.rfc-editor.org/info/rfc5234>.
400 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
401 Requirement Levels", BCP 14, RFC 2119,
402 DOI 10.17487/RFC2119, March 1997,
403 <https://www.rfc-editor.org/info/rfc2119>.
405 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
406 4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003,
407 <https://www.rfc-editor.org/info/rfc3501>.
409 [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
410 ABNF", RFC 4466, DOI 10.17487/RFC4466, April 2006,
411 <https://www.rfc-editor.org/info/rfc4466>.
413 [RFC4731] Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH
414 Command for Controlling What Kind of Information Is
415 Returned", RFC 4731, DOI 10.17487/RFC4731, November 2006,
416 <https://www.rfc-editor.org/info/rfc4731>.
418 [RFC5267] Cridland, D. and C. King, "Contexts for IMAP4", RFC 5267,
419 DOI 10.17487/RFC5267, July 2008,
420 <https://www.rfc-editor.org/info/rfc5267>.
422 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
423 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
424 May 2017, <https://www.rfc-editor.org/info/rfc8174>.
426 [RFC9051] Melnikov, A., Ed. and B. Leiba, Ed., "Internet Message
427 Access Protocol (IMAP) - Version 4rev2", RFC 9051,
428 DOI 10.17487/RFC9051, August 2021,
429 <https://www.rfc-editor.org/info/rfc9051>.
4317.2. Informative References
433 [RFC7162] Melnikov, A. and D. Cridland, "IMAP Extensions: Quick Flag
434 Changes Resynchronization (CONDSTORE) and Quick Mailbox
435 Resynchronization (QRESYNC)", RFC 7162,
436 DOI 10.17487/RFC7162, May 2014,
437 <https://www.rfc-editor.org/info/rfc7162>.
441 This document was motivated by the Yahoo! team and their questions
442 about best client practices for dealing with large mailboxes.
444 The authors of this document would like to thank the following
445 people, who provided useful comments or participated in discussions
446 of this document: Timo Sirainen and Barry Leiba.
448 This document uses a lot of text from RFC 5267. Thus, the work of
449 the RFC 5267 authors -- Dave Cridland and Curtis King -- is
456 Email: alexey.melnikov@isode.com
457 URI: https://www.isode.com
460 Arun Prakash Achuthan
462 Email: arunprakash@myyahoo.com
467 Email: nvikram_imap@yahoo.com
471 Email: luis.alves@lafaspot.com