7Network Working Group D. Cridland
8Request for Comments: 5267 C. King
9Category: Standards Track Isode Limited
17 This document specifies an Internet standards track protocol for the
18 Internet community, and requests discussion and suggestions for
19 improvements. Please refer to the current edition of the "Internet
20 Official Protocol Standards" (STD 1) for the standardization state
21 and status of this protocol. Distribution of this memo is unlimited.
25 The IMAP4rev1 protocol has powerful search facilities as part of the
26 core protocol, but lacks the ability to create live, updated results
27 that can be easily handled. This memo provides such an extension,
28 and shows how it can be used to provide a facility similar to virtual
58Cridland & King Standards Track [Page 1]
60RFC 5267 IMAP CONTEXT July 2008
65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
66 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
67 3. Extended Sort Syntax . . . . . . . . . . . . . . . . . . . . . 3
68 3.1. ESORT Extension . . . . . . . . . . . . . . . . . . . . . 4
69 3.2. Ranges in Extended Sort Results . . . . . . . . . . . . . 4
70 3.3. Extended SORT Example . . . . . . . . . . . . . . . . . . 4
71 4. Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
72 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5
73 4.2. Context Hint . . . . . . . . . . . . . . . . . . . . . . . 5
74 4.3. Notifications of Changes . . . . . . . . . . . . . . . . . 6
75 4.3.1. Refusing to Update Contexts . . . . . . . . . . . . . 7
76 4.3.2. Common Features of ADDTO and REMOVEFROM . . . . . . . 8
77 4.3.3. ADDTO Return Data Item . . . . . . . . . . . . . . . . 8
78 4.3.4. REMOVEFROM Return Data Item . . . . . . . . . . . . . 9
79 4.3.5. The CANCELUPDATE Command . . . . . . . . . . . . . . . 10
80 4.4. Partial Results . . . . . . . . . . . . . . . . . . . . . 10
81 4.5. Caching Results . . . . . . . . . . . . . . . . . . . . . 11
82 5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 12
83 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13
84 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
85 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 13
86 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14
87 9.1. Normative References . . . . . . . . . . . . . . . . . . . 14
88 9.2. Informative References . . . . . . . . . . . . . . . . . . 14
89 Appendix A. Cookbook . . . . . . . . . . . . . . . . . . . . . . 15
90 A.1. Virtual Mailboxes . . . . . . . . . . . . . . . . . . . . 15
91 A.2. Trash Mailboxes . . . . . . . . . . . . . . . . . . . . . 15
92 A.3. Immediate EXPUNGE Notifications . . . . . . . . . . . . . 15
93 A.4. Monitoring Counts . . . . . . . . . . . . . . . . . . . . 15
94 A.5. Resynchronizing Contexts . . . . . . . . . . . . . . . . . 16
95 Appendix B. Server Implementation Notes . . . . . . . . . . . . . 16
114Cridland & King Standards Track [Page 2]
116RFC 5267 IMAP CONTEXT July 2008
121 Although the basic SEARCH command defined in [IMAP], and as enhanced
122 by [ESEARCH], is relatively compact in its representation, this
123 reduction saves only a certain amount of data, and huge mailboxes
124 might overwhelm the storage available for results on even relatively
125 high-end desktop machines.
127 The SORT command defined in [SORT] provides useful features, but is
128 hard to use effectively on changing mailboxes over low-bandwidth
131 This memo borrows concepts from [ACAP], such as providing a windowed
132 view onto search or sort results, and making updates that are
133 bandwidth and round-trip efficient. These are provided by two
134 extensions: "ESORT" and "CONTEXT".
1362. Conventions Used in This Document
138 In examples, "C:" and "S:" indicate lines sent by the client
139 messaging user agent and IMAP4rev1 ([IMAP]) server, respectively.
140 "//" indicates inline comments not part of the protocol exchange.
141 Line breaks are liberally inserted for clarity. Examples are
142 intended to be read in order, such that the state remains from one
145 Although the examples show a server that supports [ESEARCH], this is
146 not a strict requirement of this specification.
148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
150 document are to be interpreted as described in [KEYWORDS].
152 Other capitalized words are typically names of IMAP extensions or
153 commands -- these are uppercased for clarity only, and are case-
1563. Extended Sort Syntax
158 Servers implementing the extended SORT provide a suite of extensions
159 to the SORT and UID SORT commands defined in [SORT]. This allows for
160 return options, as used with SEARCH and specified in [IMAP-ABNF], to
161 be used with SORT in a similar manner.
163 The SORT and UID SORT commands are extended by the addition of an
164 optional list of return options that follow a RETURN atom immediately
165 after the command. If this is missing, the server will return
166 results as specified in [SORT].
170Cridland & King Standards Track [Page 3]
172RFC 5267 IMAP CONTEXT July 2008
175 The extended SORT command always returns results in the requested
176 sort order, but is otherwise identical in its behaviour to the
177 extended SEARCH command defined in [IMAP-ABNF], as extended by
178 [ESEARCH]. In particular, the extended SORT command returns results
179 in an ESEARCH response.
183 Servers advertising the capability "ESORT" support the return options
184 specified in [ESEARCH] in the SORT command. These return options are
188 Return the message number/UID of the lowest sorted message
189 satisfying the search criteria.
192 Return the message number/UID of the highest sorted message
193 satisfying the search criteria.
196 Return all message numbers/UIDs which match the search criteria,
197 in the requested sort order, using a sequence-set. Note the use
198 of ranges described below in Section 3.2.
2033.2. Ranges in Extended Sort Results
205 Any ranges given by the server, including those given as part of the
206 sequence-set, in an ESEARCH response resulting from an extended SORT
207 or UID SORT command, MUST be ordered in increasing numerical order
208 after expansion, as per usual [IMAP] rules.
210 In particular this means that 10:12 is equivalent to 12:10, and
211 10,11,12. To avoid confusion, servers SHOULD present ranges only
212 when the first seq-number is lower than the second; that is, either
213 of the forms 10:12 or 10,11,12 is acceptable, but 12:10 SHOULD be
2163.3. Extended SORT Example
218 If the list of return options is present but empty, then the server
219 provides the ALL return data item in an ESEARCH response. This is
220 functionally equivalent to an unextended UID SORT command, but can
221 use a smaller representation:
226Cridland & King Standards Track [Page 4]
228RFC 5267 IMAP CONTEXT July 2008
231 C: E01 UID SORT RETURN () (REVERSE DATE) UTF-8 UNDELETED
233 S: * ESEARCH (TAG "E01") UID ALL 23765,23764,23763,23761,[...]
234 S: E01 OK Sort completed
236 Note that the initial three results are not represented as the range
237 23765:23763 as mandated in Section 3.2.
243 The Contexts extension is present in any IMAP4rev1 server that
244 includes the string "CONTEXT=SEARCH", and/or "CONTEXT=SORT", within
245 its advertised capabilities.
247 In the case of CONTEXT=SEARCH, the server supports the extended
248 SEARCH command syntax described in [IMAP-ABNF], and accepts three
249 additional return options.
251 Servers advertising CONTEXT=SORT also advertise the SORT capability,
252 as described in [SORT], support the extended SORT command syntax
253 described in Section 3, and accept three additional return options
254 for this extended SORT.
256 These additional return options allow for notifications of changes to
257 the results of SEARCH or SORT commands, and also allow for access to
260 A server advertising the CONTEXT=SEARCH extension will order all
261 SEARCH results, whether from a UID SEARCH or SEARCH command, in
262 mailbox order -- that is, by message number and UID. Therefore, the
263 UID SEARCH, SEARCH, UID SORT, or SORT command used -- collectively
264 known as the searching command -- will always have an order, the
265 requested order, which will be the mailbox order for UID SEARCH and
268 All of the return specifiers have no interaction with either each
269 other or any return specifiers defined in [ESEARCH] or Section 3.1;
270 however, it is believed that implementations supporting CONTEXT will
271 also support ESEARCH and ESORT.
275 The return option CONTEXT SHOULD be used by a client to indicate that
276 subsequent use of the search criteria are likely. Servers MAY ignore
277 this return option or use it as a hint to maintain a full result
282Cridland & King Standards Track [Page 5]
284RFC 5267 IMAP CONTEXT July 2008
287 A client might choose to obtain a count of matching messages prior to
288 obtaining actual results. Here, the client signals its intention to
289 fetch the results themselves:
291 C: A01 SEARCH RETURN (CONTEXT COUNT) UNDELETED
293 S: * ESEARCH (TAG "A01") COUNT 23765
294 S: A01 OK Search completed.
2964.3. Notifications of Changes
298 The search return option UPDATE, if used by a client, causes the
299 server to issue unsolicited notifications containing updates to the
300 results that would be returned by an unmodified searching command.
301 These update sets are carried in ADDTO and REMOVEFROM data items in
304 These ESEARCH responses carry a search correlator of the searching
305 command, hence clients MUST NOT reuse tags, as already specified in
306 Section 2.2.1 of [IMAP]. An attempt to use UPDATE where a tag is
307 already in use with a previous searching command that itself used
308 UPDATE SHALL result in the server rejecting the searching command
311 Both ADDTO and REMOVEFROM data items SHOULD be delivered to clients
312 in a timely manner, as and when results change, whether by new
313 messages arriving in the mailbox, metadata such as flags being
314 changed, or messages being expunged.
316 Typically, this would occur at the same time as the FETCH, EXISTS, or
317 EXPUNGE responses carrying the source of the change.
319 Updates will cease when the mailbox is no longer selected, or when
320 the CANCELUPDATE command, defined in Section 4.3.5, is issued by the
321 client, whichever is sooner.
323 Unlike [ACAP], there is no requirement that a context need be created
324 with CONTEXT to use UPDATE, and in addition, the lack of UPDATE with
325 a CONTEXT does not affect the results caused by later searching
326 commands -- there is no snapshot facility.
328 There is no interaction between UPDATE and any other return options;
329 therefore, use of RETURN (UPDATE MIN), for example, does not notify
330 about the minimum UID or sequence number, but notifies instead about
331 all changes to the set of matching messages. In particular, this
332 means that a client using UPDATE and PARTIAL on the same search
333 program could receive notifications about messages that do not
334 currently interest it.
338Cridland & King Standards Track [Page 6]
340RFC 5267 IMAP CONTEXT July 2008
343 Finally, as specified in the errata to [IMAP], any message sequence
344 numbers used in the search program are evaluated at the time the
345 command is received; therefore, if the messages referred to by such
346 message sequence numbers change, no notifications will be emitted.
348 This time, the client will require notifications of updates and
349 chooses to obtain a count:
351 C: B01 UID SEARCH RETURN (UPDATE COUNT) DELETED
353 S: * ESEARCH (TAG "B01") COUNT 74
354 S: B01 OK Search completed, will notify.
355 // Note that the following is rejected, and has no effect:
356 C: B01 SORT RETURN (UPDATE) FLAGGED
3594.3.1. Refusing to Update Contexts
361 In some cases, the server MAY refuse to provide updates, such as if
362 an internal limit on the number of update contexts is reached. In
363 such a case, an untagged NO is generated during processing of the
364 command with a response-code of NOUPDATE. The response-code
365 contains, as argument, the tag of the search command for which the
366 server is refusing to honour the UPDATE request.
368 Other return options specified SHALL still be honoured.
370 Servers MUST provide at least one updating context per client, and
371 SHOULD provide more -- see Appendix B for strategies on reducing the
372 impact of additional updating contexts. Since sorted contexts
373 require a higher implementation cost than unsorted contexts, refusal
374 to provide updates for a SORT command does not imply that SEARCH
375 contexts will also be refused.
377 This time, the client will require notifications of updates, and
378 chooses to obtain a count:
380 C: B02 UID SORT RETURN (UPDATE COUNT) UTF-8
382 S: * ESEARCH (TAG "B02") COUNT 74
383 S: * NO [NOUPDATE "B02"] Too many contexts
384 S: B02 OK Search completed, will not notify.
386 Client handling might be to retry with a UID SEARCH command, or else
387 cancel an existing context; see Section 4.3.5.
394Cridland & King Standards Track [Page 7]
396RFC 5267 IMAP CONTEXT July 2008
3994.3.2. Common Features of ADDTO and REMOVEFROM
401 The result update set included in the return data item is specified
402 as UIDs or message numbers, depending on how the UPDATE was
403 specified. If the UPDATE was present in a SEARCH or SORT command,
404 the results will be message numbers; in a UID SEARCH or UID SORT
405 command, they will be UIDs.
407 The client MUST process ADDTO and REMOVEFROM return data items in the
408 order they appear, including those within a single ESEARCH response.
409 Correspondingly, servers MUST generate ADDTO and REMOVEFROM responses
410 such that the results are maintained in the requested order.
412 As with any response aside from EXPUNGE, ESEARCH responses carrying
413 ADDTO and/or REMOVEFROM return data items MAY be sent at any time.
414 In particular, servers MAY send such responses when no command is in
415 progress, during the processing of any command, or when the client is
416 using the IDLE facility described in [IDLE]. Implementors are
417 recommended to read [NOTIFY] as a mechanism for clients to signal
418 servers that they are willing to process responses at any time, and
419 are also recommended to pay close attention to Section 5.3 of [IMAP].
421 It is anticipated that typical server implementations will emit ADDTO
422 when they normally emit the causal FETCH or EXISTS, and similarly
423 emit REMOVEFROM when they normally emit the causal FETCH or EXPUNGE.
4254.3.3. ADDTO Return Data Item
427 The ADDTO return data item contains, as payload, a list containing
428 pairs of a context position and a set of result updates in the
429 requested order to be inserted at the context position. Where the
430 searching command is a SEARCH or UID SEARCH command, the context
431 position MAY be zero. Each pair is processed in the order that it
434 Note that an ADDTO containing message sequence numbers added as a
435 result of those messages being delivered or appended MUST be sent
436 after the EXISTS notification itself, in order that those sequence
439 If the context position is non-zero, the result update is inserted at
440 the given context position, meaning that the first result in the set
441 will occupy the new context position after insertion, and any prior
442 existing result at that context position will be shifted to a later
450Cridland & King Standards Track [Page 8]
452RFC 5267 IMAP CONTEXT July 2008
455 Where the context position is zero, the client MAY insert the message
456 numbers or UIDs in the result list such that the result list is
457 maintained in mailbox order. In this case, servers are RECOMMENDED
458 to order the result update into mailbox order to produce the shortest
459 representation in set-syntax.
462 S: * 23762 FETCH (FLAGS (\Deleted \Seen))
463 S: * 23763 FETCH (FLAGS ($Junk \Seen))
464 S: * ESEARCH (TAG "B01") UID ADDTO (0 32768:32769)
466 Note that this example assumes messages 23762 and 23763 with UIDs
467 32768 and 32769 (respectively) previously had neither \Deleted nor
468 $Junk set. Also note that only the ADDTO is included, and not the
471 If the searching command "C01" initially generated a result list of
472 2734:2735, then the following three responses are equivalent, and
473 yield a result list of 2731:2735:
476 S: * ESEARCH (TAG "C01") UID ADDTO (1 2733 1 2732 1 2731)
477 S: * ESEARCH (TAG "C01") UID ADDTO (1 2733) ADDTO (1 2731:2732)
478 S: * ESEARCH (TAG "C01") UID ADDTO (1 2731:2733)
480 The last is the preferred representation.
4824.3.4. REMOVEFROM Return Data Item
484 The REMOVEFROM return data item contains, as payload, a list
485 containing pairs of a context position and a set of result updates in
486 the requested order to be removed starting from the context position.
487 Where the searching command is a SEARCH or UID SEARCH command, the
488 context position MAY be zero. Each pair is processed in the order
491 If the context position is non-zero, the results are removed at the
492 given context position, meaning that the first result in the set will
493 occupy the given context position before removal, and any prior
494 existing result at that context position will be shifted to an
495 earlier context position.
497 Where the context position is zero, the client removes the message
498 numbers or UIDs in the result list wherever they occur, and servers
499 are RECOMMENDED to order the result list in mailbox order to obtain
500 the best benefit from the set-syntax.
506Cridland & King Standards Track [Page 9]
508RFC 5267 IMAP CONTEXT July 2008
511 Note that a REMOVEFROM containing message sequence numbers removed as
512 a result of those messages being expunged MUST be sent prior to the
513 expunge notification itself, in order that those sequence numbers
516 Here, a message in the result list is expunged. The REMOVEFROM is
517 shown to happen without any command in progress; see Section 4.3.2.
518 Note that EXPUNGE responses do not have this property.
521 S: * ESEARCH (TAG "B01") UID REMOVEFROM (0 32768)
524 S: B03 OK Nothing done.
5264.3.5. The CANCELUPDATE Command
528 When a client no longer wishes to receive updates, it may issue the
529 CANCELUPDATE command, which will prevent all updates to the contexts
530 named in the arguments from being transmitted by the server. The
531 command takes, as arguments, one or more tags of the commands used to
534 The server MAY free any resource associated with a context so
535 disabled -- however, the client is free to issue further searching
536 commands with the same criteria and requested order, including
539 C: B04 CANCELUPDATE "B01"
540 S: B04 OK No further updates.
544 The PARTIAL search return option causes the server to provide in an
545 ESEARCH response a subset of the results denoted by the sequence
546 range given as the mandatory argument. The first result is 1; thus,
547 the first 500 results would be obtained by a return option of
548 "PARTIAL 1:500", and the second 500 by "PARTIAL 501:1000". This
549 intentionally mirrors message sequence numbers.
551 A single command MUST NOT contain more than one PARTIAL or ALL search
552 return option -- that is, either one PARTIAL, one ALL, or neither
553 PARTIAL nor ALL is allowed.
555 For SEARCH results, the entire result list MUST be ordered in mailbox
556 order, that is, in UID or message sequence number order.
562Cridland & King Standards Track [Page 10]
564RFC 5267 IMAP CONTEXT July 2008
567 Where a PARTIAL search return option references results that do not
568 exist, by using a range which starts or ends higher than the current
569 number of results, then the server returns the results that are in
570 the set. This yields a PARTIAL return data item that has, as
571 payload, the original range and a potentially missing set of results
572 that may be shorter than the extent of the range.
574 Clients need not request PARTIAL results in any particular order.
575 Because mailboxes may change, clients will often wish to use PARTIAL
576 in combination with UPDATE, especially if the intent is to walk a
577 large set of results; however, these return options do not interact
578 -- the UPDATE will provide notifications for all matching results.
580 // Recall from A01 that there are 23764 results.
581 C: A02 UID SEARCH RETURN (PARTIAL 23500:24000) UNDELETED
583 C: A03 UID SEARCH RETURN (PARTIAL 1:500) UNDELETED
585 C: A04 UID SEARCH RETURN (PARTIAL 24000:24500) UNDELETED
587 S: * ESEARCH (TAG "A02") UID PARTIAL (23500:24000 ...)
588 // 264 results in set syntax elided,
589 // this spans the end of the results.
591 S: * ESEARCH (TAG "A03") UID PARTIAL (1:500 ...)
592 // 500 results in set syntax elided.
594 S: * ESEARCH (TAG "A04") UID PARTIAL (24000:24500 NIL)
595 // No results are present, this is beyond the end of the results.
600 Server implementations MAY cache results from a SEARCH or SORT,
601 whether or not hinted to by CONTEXT, in order to make subsequent
602 searches more efficient, perhaps by recommencing a subsequent PARTIAL
603 search where a previous search left off. However, servers MUST
604 behave identically whether or not internal caching is taking place;
605 therefore, any such cache is required to be updated as changes to the
606 mailbox occur. An alternate strategy would be to discard results
607 when any change occurs to the mailbox.
618Cridland & King Standards Track [Page 11]
620RFC 5267 IMAP CONTEXT July 2008
625 The collected formal syntax. This uses ABNF as defined in [ABNF].
626 It includes definitions from [IMAP], [IMAP-ABNF], and [SORT].
628 capability =/ "CONTEXT=SEARCH" / "CONTEXT=SORT" / "ESORT"
629 ;; <capability> from [IMAP]
631 command-select =/ "CANCELUPDATE" 1*(SP quoted)
632 ;; <command-select> from [IMAP]
634 context-position = number
635 ;; Context position may be 0 for SEARCH result additions.
636 ;; <number> from [IMAP]
638 modifier-context = "CONTEXT"
640 modifier-partial = "PARTIAL" SP partial-range
642 partial-range = nz-number ":" nz-number
643 ;; A range 500:400 is the same as 400:500.
644 ;; This is similar to <seq-range> from [IMAP],
645 ;; but cannot contain "*".
647 modifier-update = "UPDATE"
649 search-return-opt =/ modifier-context / modifier-partial /
651 ;; All conform to <search-return-opt>, from [IMAP-ABNF]
653 resp-text-code =/ "NOUPDATE" SP quoted
654 ;; <resp-text-code> from [IMAP]
656 ret-data-addto = "ADDTO"
657 SP "(" context-position SP sequence-set
658 *(SP context-position SP sequence-set)
660 ;; <sequence-set> from [IMAP]
662 ret-data-partial = "PARTIAL"
663 SP "(" partial-range SP partial-results ")"
664 ;; <partial-range> is the requested range.
666 partial-results = sequence-set / "NIL"
667 ;; <sequence-set> from [IMAP]
668 ;; NIL indicates no results correspond to the requested range.
674Cridland & King Standards Track [Page 12]
676RFC 5267 IMAP CONTEXT July 2008
679 ret-data-removefrom = "REMOVEFROM"
680 SP "(" context-position SP sequence-set
681 *(SP context-position SP sequence-set)
683 ;; <sequence-set> from [IMAP]
685 search-return-data =/ ret-data-partial / ret-data-addto /
687 ;; All conform to <search-return-data>, from [IMAP-ABNF]
689 sort =/ extended-sort
690 ;; <sort> from [SORT]
692 extended-sort = ["UID" SP] "SORT" search-return-opts
693 SP sort-criteria SP search-criteria
694 ;; <search-return-opts> from [IMAP-ABNF]
695 ;; <sort-criteria> and <search-criteria> from [SORT]
6976. Security Considerations
699 This document defines additional IMAP4 capabilities. As such, it
700 does not change the underlying security considerations of [IMAP].
701 The authors and reviewers believe that no new security issues are
702 introduced with these additional IMAP4 capabilities.
704 Creation of a large number of contexts may provide an avenue for
705 denial-of-service attacks by authorized users. Implementors may
706 reduce this by limiting the number of contexts possible to create,
707 via the protocol features described in Section 4.3.1; by reducing the
708 impact of contexts by the implementation strategies described in
709 Appendix B; and by logging context creation and usage so that
710 administrative remedies may be applied.
7127. IANA Considerations
714 IMAP4 capabilities are registered by publishing a Standards Track or
715 IESG-approved Experimental RFC.
717 This document defines the ESORT, CONTEXT=SEARCH, and CONTEXT=SORT
718 IMAP capabilities. IANA has added them to the registry accordingly.
722 Much of the design of this extension can be found in ACAP. Valuable
723 comments, both in agreement and in dissent, were received from Alexey
724 Melnikov, Arnt Gulbrandsen, Cyrus Daboo, Filip Navara, Mark Crispin,
725 Peter Coates, Philip Van Hoof, Randall Gellens, Timo Sirainen, Zoltan
730Cridland & King Standards Track [Page 13]
732RFC 5267 IMAP CONTEXT July 2008
735 Ordogh, and others, and many of these comments have had significant
736 influence on the design or the text. The authors are grateful to all
737 those involved, including those not mentioned here.
7419.1. Normative References
743 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
744 Specifications: ABNF", STD 68, RFC 5234, January 2008.
746 [ESEARCH] Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH
747 Command for Controlling What Kind of Information Is
748 Returned", RFC 4731, November 2006.
750 [IMAP] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
751 4rev1", RFC 3501, March 2003.
753 [IMAP-ABNF] Melnikov, A. and C. Daboo, "Collected Extensions to
754 IMAP4 ABNF", RFC 4466, April 2006.
756 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
757 Requirement Levels", BCP 14, RFC 2119, March 1997.
759 [SORT] Crispin, M. and K. Murchison, "Internet Message Access
760 Protocol - SORT and THREAD Extensions", RFC 5256,
7639.2. Informative References
765 [ACAP] Newman, C. and J. Myers, "ACAP -- Application
766 Configuration Access Protocol", RFC 2244, November 1997.
768 [IDLE] Leiba, B., "IMAP4 IDLE command", RFC 2177, June 1997.
770 [NOTIFY] Melnikov, A., Gulbrandsen, A., and C. King, "The IMAP
771 NOTIFY Extension", Work in Progress, March 2008.
786Cridland & King Standards Track [Page 14]
788RFC 5267 IMAP CONTEXT July 2008
793A.1. Virtual Mailboxes
795 It is possible to use the facilities described within this memo to
796 create a facility largely similar to a virtual mailbox, but handled
799 Initially, the client SELECTs the real "backing" mailbox. Next, it
800 can switch to a filtered view at any time by issuing a RETURN (COUNT
801 UPDATE CONTEXT), and using RETURN (PARTIAL x:y) as the user scrolls,
802 feeding the results into a FETCH as required to populate summary
805 A typically useful view is "UID SORT (DATE) RETURN (...) UTF-8
806 UNSEEN UNDELETED", which can be used to show the mailbox sorted into
807 INTERNALDATE order, filtered to only show messages which are unread
812 Certain contexts are particularly useful for client developers
813 wishing to present something similar to the common trash mailbox
814 metaphor in limited bandwidth. The simple criteria of UNDELETED only
815 matches undeleted messages, and the corresponding DELETED search key
816 can be used to display a per-mailbox trash-like virtual mailbox.
818A.3. Immediate EXPUNGE Notifications
820 The command "SEARCH RETURN (UPDATE) ALL" can be used to create a
821 context that notifies immediately about expunged messages, yet will
822 not affect message sequence numbers until the normal EXPUNGE message
823 can be sent. This may be useful for clients wishing to show this
824 behavior without losing the benefit of sequence numbering.
826A.4. Monitoring Counts
828 A client need not maintain any result cache at all, but instead it
829 can maintain a simple count of messages matching the search criteria.
830 Typically, this would use the SEARCH command, as opposed to UID
831 SEARCH, due to its smaller representation. Such usage might prove
832 useful in monitoring the number of flagged, but unanswered, messages,
833 for example, with "SEARCH RETURN (UPDATE COUNT) FLAGGED UNANSWERED".
842Cridland & King Standards Track [Page 15]
844RFC 5267 IMAP CONTEXT July 2008
847A.5. Resynchronizing Contexts
849 The creation of a context, and immediate access to it, can all be
850 accomplished in a single round-trip. Therefore, whilst it is
851 possible to elide resynchronization if no changes have occurred, it
852 is simpler in most cases to resynchronize by simply recreating the
855Appendix B. Server Implementation Notes
857 Although a server may cache the results, this is neither mandated nor
858 required, especially when the client uses SEARCH or UID SEARCH
859 commands. UPDATE processing, for example, can be achieved
860 efficiently by comparison of the old flag state (if any) and the new,
861 and PARTIAL can be achieved by re-running the search until the
862 suitable window is required. This is a result of there being no
865 For example, on a new message, the server can simply test for matches
866 against all current UPDATE context search programs, and for any that
867 match, send the ADDTO return data.
869 Similarly, for a flag change on an existing message, the server can
870 check whether the message matched with its old flags, whether it
871 matches with new flags, and provide ADDTO or REMOVEFROM return data
872 accordingly if these results differ.
874 For PARTIAL requests, the server can perform a full search,
875 discarding results until the lower bound is hit, and stopping the
876 search when sufficient results have been obtained.
878 With some additional state, it is possible to restart PARTIAL
879 searches, thus avoiding performing the initial discard phase.
881 For the best performance, however, caching the full search results is
882 needed, which can allow for faster responses at the expense of
883 memory. One reasonable strategy would be to balance this trade-off
884 at run-time, discarding search results after a suitable timeout, and
885 regenerating them as required.
887 This yields state requirements of storing the search program for any
888 UPDATE contexts, and optionally storing both search program and
889 (updated) results for further contexts as required.
898Cridland & King Standards Track [Page 16]
900RFC 5267 IMAP CONTEXT July 2008
903 Note that in the absence of a server-side results cache, it may be
904 impossible to know if an expunged message previously matched unless
905 the original message is still available. Therefore, some
906 implementations may be forced into using a results cache in many
909 UPDATE contexts created with SORT or UID SORT will almost certainly
910 require some form of results caching, however.
916 5 Castle Business Village
918 Hampton, Middlesex TW12 2BX
921 EMail: dave.cridland@isode.com
926 5 Castle Business Village
928 Hampton, Middlesex TW12 2BX
931 EMail: cking@mumbo.ca
954Cridland & King Standards Track [Page 17]
956RFC 5267 IMAP CONTEXT July 2008
959Full Copyright Statement
961 Copyright (C) The IETF Trust (2008).
963 This document is subject to the rights, licenses and restrictions
964 contained in BCP 78, and except as set forth therein, the authors
965 retain all their rights.
967 This document and the information contained herein are provided on an
968 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
969 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
970 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
971 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
972 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
973 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
977 The IETF takes no position regarding the validity or scope of any
978 Intellectual Property Rights or other rights that might be claimed to
979 pertain to the implementation or use of the technology described in
980 this document or the extent to which any license under such rights
981 might or might not be available; nor does it represent that it has
982 made any independent effort to identify any such rights. Information
983 on the procedures with respect to rights in RFC documents can be
984 found in BCP 78 and BCP 79.
986 Copies of IPR disclosures made to the IETF Secretariat and any
987 assurances of licenses to be made available, or the result of an
988 attempt made to obtain a general license or permission for the use of
989 such proprietary rights by implementers or users of this
990 specification can be obtained from the IETF on-line IPR repository at
991 http://www.ietf.org/ipr.
993 The IETF invites any interested party to bring to its attention any
994 copyrights, patents or patent applications, or other proprietary
995 rights that may cover technology that may be required to implement
996 this standard. Please address the information to the IETF at
1010Cridland & King Standards Track [Page 18]