imapext-2007
view docs/rfc/rfc4551.txt @ 0:ada5e610ab86
imap-2007e
| author | yuuji@gentei.org |
|---|---|
| date | Mon, 14 Sep 2009 15:17:45 +0900 |
| parents | |
| children |
line source
7 Network Working Group A. Melnikov
8 Request for Comments: 4551 Isode Ltd.
9 Updates: 3501 S. Hole
10 Category: Standards Track ACI WorldWide/MessagingDirect
11 June 2006
14 IMAP Extension for Conditional STORE Operation
15 or Quick Flag Changes Resynchronization
17 Status of This Memo
19 This document specifies an Internet standards track protocol for the
20 Internet community, and requests discussion and suggestions for
21 improvements. Please refer to the current edition of the "Internet
22 Official Protocol Standards" (STD 1) for the standardization state
23 and status of this protocol. Distribution of this memo is unlimited.
25 Copyright Notice
27 Copyright (C) The Internet Society (2006).
29 Abstract
31 Often, multiple IMAP (RFC 3501) clients need to coordinate changes to
32 a common IMAP mailbox. Examples include different clients working on
33 behalf of the same user, and multiple users accessing shared
34 mailboxes. These clients need a mechanism to synchronize state
35 changes for messages within the mailbox. They must be able to
36 guarantee that only one client can change message state (e.g.,
37 message flags) at any time. An example of such an application is use
38 of an IMAP mailbox as a message queue with multiple dequeueing
39 clients.
41 The Conditional Store facility provides a protected update mechanism
42 for message state information that can detect and resolve conflicts
43 between multiple writing mail clients.
45 The Conditional Store facility also allows a client to quickly
46 resynchronize mailbox flag changes.
48 This document defines an extension to IMAP (RFC 3501).
58 Melnikov & Hole Standards Track [Page 1]
60 RFC 4551 IMAP Extension for Conditional STORE June 2006
63 Table of Contents
65 1. Introduction and Overview ................................. 3
66 2. Conventions Used in This Document ......................... 5
67 3. IMAP Protocol Changes ..................................... 6
68 3.1. New OK untagged responses for SELECT and EXAMINE ......... 6
69 3.1.1. HIGHESTMODSEQ response code ............................ 6
70 3.1.2. NOMODSEQ response code ................................. 7
71 3.2. STORE and UID STORE Commands ............................. 7
72 3.3 FETCH and UID FETCH Commands ..............................13
73 3.3.1. CHANGEDSINCE FETCH modifier ............................13
74 3.3.2. MODSEQ message data item in FETCH Command ..............14
75 3.4. MODSEQ search criterion in SEARCH ........................16
76 3.5. Modified SEARCH untagged response ........................17
77 3.6. HIGHESTMODSEQ status data items ..........................17
78 3.7. CONDSTORE parameter to SELECT and EXAMINE ................18
79 3.8. Additional quality of implementation issues ..............18
80 4. Formal Syntax .............................................19
81 5. Server implementation considerations ......................21
82 6. Security Considerations ...................................22
83 7. IANA Considerations .......................................22
84 8. References ................................................23
85 8.1. Normative References .....................................23
86 8.2. Informative References ...................................23
87 9. Acknowledgements ..........................................23
114 Melnikov & Hole Standards Track [Page 2]
116 RFC 4551 IMAP Extension for Conditional STORE June 2006
119 1. Introduction and Overview
121 The Conditional STORE extension is present in any IMAP4
122 implementation that returns "CONDSTORE" as one of the supported
123 capabilities in the CAPABILITY command response.
125 An IMAP server that supports this extension MUST associate a positive
126 unsigned 64-bit value called a modification sequence (mod-sequence)
127 with every IMAP message. This is an opaque value updated by the
128 server whenever a metadata item is modified. The server MUST
129 guarantee that each STORE command performed on the same mailbox
130 (including simultaneous stores to different metadata items from
131 different connections) will get a different mod-sequence value.
132 Also, for any two successful STORE operations performed in the same
133 session on the same mailbox, the mod-sequence of the second completed
134 operation MUST be greater than the mod-sequence of the first
135 completed. Note that the latter rule disallows the use of the system
136 clock as a mod-sequence, because if system time changes (e.g., an NTP
137 [NTP] client adjusting the time), the next generated value might be
138 less than the previous one.
140 Mod-sequences allow a client that supports the CONDSTORE extension to
141 determine if a message metadata has changed since some known moment.
142 Whenever the state of a flag changes (i.e., the flag is added where
143 previously it wasn't set, or the flag is removed and before it was
144 set) the value of the modification sequence for the message MUST be
145 updated. Adding the flag when it is already present or removing when
146 it is not present SHOULD NOT change the mod-sequence.
148 When a message is appended to a mailbox (via the IMAP APPEND command,
149 COPY to the mailbox, or using an external mechanism) the server
150 generates a new modification sequence that is higher than the highest
151 modification sequence of all messages in the mailbox and assigns it
152 to the appended message.
154 The server MAY store separate (per-message) modification sequence
155 values for different metadata items. If the server does so, per-
156 message mod-sequence is the highest mod-sequence of all metadata
157 items for the specified message.
159 The server that supports this extension is not required to be able to
160 store mod-sequences for every available mailbox. Section 3.1.2
161 describes how the server may act if a particular mailbox doesn't
162 support the persistent storage of mod-sequences.
170 Melnikov & Hole Standards Track [Page 3]
172 RFC 4551 IMAP Extension for Conditional STORE June 2006
175 This extension makes the following changes to the IMAP4 protocol:
177 a) adds UNCHANGEDSINCE STORE modifier.
179 b) adds the MODIFIED response code which should be used with an OK
180 response to the STORE command. (It can also be used in a NO
181 response.)
183 c) adds a new MODSEQ message data item for use with the FETCH
184 command.
186 d) adds CHANGEDSINCE FETCH modifier.
188 e) adds a new MODSEQ search criterion.
190 f) extends the syntax of untagged SEARCH responses to include
191 mod-sequence.
193 g) adds new OK untagged responses for the SELECT and EXAMINE
194 commands.
196 h) defines an additional parameter to SELECT/EXAMINE commands.
198 i) adds the HIGHESTMODSEQ status data item to the STATUS command.
200 A client supporting CONDSTORE extension indicates its willingness to
201 receive mod-sequence updates in all untagged FETCH responses by
202 issuing:
204 - a SELECT or EXAMINE command with the CONDSTORE parameter,
205 - a STATUS (HIGHESTMODSEQ) command,
206 - a FETCH or SEARCH command that includes the MODSEQ message data
207 item,
208 - a FETCH command with the CHANGEDSINCE modifier, or
209 - a STORE command with the UNCHANGEDSINCE modifier.
211 The server MUST include mod-sequence data in all subsequent untagged
212 FETCH responses (until the connection is closed), whether they were
213 caused by a regular STORE, a STORE with UNCHANGEDSINCE modifier, or
214 an external agent.
216 This document uses the term "CONDSTORE-aware client" to refer to a
217 client that announces its willingness to receive mod-sequence updates
218 as described above. The term "CONDSTORE enabling command" will refer
219 any of the commands listed above. A future extension to this
220 document may extend the list of CONDSTORE enabling commands. A first
221 CONDSTORE enabling command executed in the session MUST cause the
226 Melnikov & Hole Standards Track [Page 4]
228 RFC 4551 IMAP Extension for Conditional STORE June 2006
231 server to return HIGHESTMODSEQ (Section 3.1.1) unless the server has
232 sent NOMODSEQ (Section 3.1.2) response code when the currently
233 selected mailbox was selected.
235 The rest of this document describes the protocol changes more
236 rigorously.
238 2. Conventions Used in This Document
240 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
241 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
242 document are to be interpreted as described in RFC 2119 [KEYWORDS].
244 In examples, lines beginning with "S:" are sent by the IMAP server,
245 and lines beginning with "C:" are sent by the client. Line breaks
246 may appear in example commands solely for editorial clarity; when
247 present in the actual message, they are represented by "CRLF".
249 Formal syntax is defined using ABNF [ABNF].
251 The term "metadata" or "metadata item" is used throughout this
252 document. It refers to any system or user-defined keyword. Future
253 documents may extend "metadata" to include other dynamic message
254 data.
256 Some IMAP mailboxes are private, accessible only to the owning user.
257 Other mailboxes are not, either because the owner has set an Access
258 Control List [ACL] that permits access by other users, or because it
259 is a shared mailbox. Let's call a metadata item "shared" for the
260 mailbox if any changes to the metadata items are persistent and
261 visible to all other users accessing the mailbox. Otherwise, the
262 metadata item is called "private". Note that private metadata items
263 are still visible to all sessions accessing the mailbox as the same
264 user. Also note that different mailboxes may have different metadata
265 items as shared.
267 See Section 1 for the definition of a "CONDSTORE-aware client" and a
268 "CONDSTORE enabling command".
282 Melnikov & Hole Standards Track [Page 5]
284 RFC 4551 IMAP Extension for Conditional STORE June 2006
287 3. IMAP Protocol Changes
289 3.1. New OK Untagged Responses for SELECT and EXAMINE
291 This document adds two new response codes, HIGHESTMODSEQ and
292 NOMODSEQ. One of those response codes MUST be returned in the OK
293 untagged response for a successful SELECT/EXAMINE command.
295 When opening a mailbox, the server must check if the mailbox supports
296 the persistent storage of mod-sequences. If the mailbox supports the
297 persistent storage of mod-sequences and the mailbox open operation
298 succeeds, the server MUST send the OK untagged response including
299 HIGHESTMODSEQ response code. If the persistent storage for the
300 mailbox is not supported, the server MUST send the OK untagged
301 response including NOMODSEQ response code instead.
303 3.1.1. HIGHESTMODSEQ Response Code
305 This document adds a new response code that is returned in the OK
306 untagged response for the SELECT and EXAMINE commands. A server
307 supporting the persistent storage of mod-sequences for the mailbox
308 MUST send the OK untagged response including HIGHESTMODSEQ response
309 code with every successful SELECT or EXAMINE command:
311 OK [HIGHESTMODSEQ <mod-sequence-value>]
313 where <mod-sequence-value> is the highest mod-sequence value of
314 all messages in the mailbox. When the server changes UIDVALIDITY
315 for a mailbox, it doesn't have to keep the same HIGHESTMODSEQ for
316 the mailbox.
318 A disconnected client can use the value of HIGHESTMODSEQ to check if
319 it has to refetch metadata from the server. If the UIDVALIDITY value
320 has changed for the selected mailbox, the client MUST delete the
321 cached value of HIGHESTMODSEQ. If UIDVALIDITY for the mailbox is the
322 same, and if the HIGHESTMODSEQ value stored in the client's cache is
323 less than the value returned by the server, then some metadata items
324 on the server have changed since the last synchronization, and the
325 client needs to update its cache. The client MAY use SEARCH MODSEQ
326 (Section 3.4) to find out exactly which metadata items have changed.
327 Alternatively, the client MAY issue FETCH with the CHANGEDSINCE
328 modifier (Section 3.3.1) in order to fetch data for all messages that
329 have metadata items changed since some known modification sequence.
331 Example 1:
333 C: A142 SELECT INBOX
334 S: * 172 EXISTS
338 Melnikov & Hole Standards Track [Page 6]
340 RFC 4551 IMAP Extension for Conditional STORE June 2006
343 S: * 1 RECENT
344 S: * OK [UNSEEN 12] Message 12 is first unseen
345 S: * OK [UIDVALIDITY 3857529045] UIDs valid
346 S: * OK [UIDNEXT 4392] Predicted next UID
347 S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
348 S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited
349 S: * OK [HIGHESTMODSEQ 715194045007]
350 S: A142 OK [READ-WRITE] SELECT completed
352 3.1.2. NOMODSEQ Response Code
354 A server that doesn't support the persistent storage of mod-sequences
355 for the mailbox MUST send the OK untagged response including NOMODSEQ
356 response code with every successful SELECT or EXAMINE command. A
357 server that returned NOMODSEQ response code for a mailbox, which
358 subsequently receives one of the following commands while the mailbox
359 is selected:
361 - a FETCH command with the CHANGEDSINCE modifier,
362 - a FETCH or SEARCH command that includes the MODSEQ message data
363 item, or
364 - a STORE command with the UNCHANGEDSINCE modifier
366 MUST reject any such command with the tagged BAD response.
368 Example 2:
370 C: A142 SELECT INBOX
371 S: * 172 EXISTS
372 S: * 1 RECENT
373 S: * OK [UNSEEN 12] Message 12 is first unseen
374 S: * OK [UIDVALIDITY 3857529045] UIDs valid
375 S: * OK [UIDNEXT 4392] Predicted next UID
376 S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
377 S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited
378 S: * OK [NOMODSEQ] Sorry, this mailbox format doesn't support
379 modsequences
380 S: A142 OK [READ-WRITE] SELECT completed
382 3.2. STORE and UID STORE Commands
384 This document defines the following STORE modifier (see Section 2.5
385 of [IMAPABNF]):
387 UNCHANGEDSINCE <mod-sequence>
389 For each message specified in the message set, the server performs
390 the following. If the mod-sequence of any metadata item of the
394 Melnikov & Hole Standards Track [Page 7]
396 RFC 4551 IMAP Extension for Conditional STORE June 2006
399 message is equal or less than the specified UNCHANGEDSINCE value,
400 then the requested operation (as described by the message data
401 item) is performed. If the operation is successful, the server
402 MUST update the mod-sequence attribute of the message. An
403 untagged FETCH response MUST be sent, even if the .SILENT suffix
404 is specified, and the response MUST include the MODSEQ message
405 data item. This is required to update the client's cache with the
406 correct mod-sequence values. See Section 3.3.2 for more details.
408 However, if the mod-sequence of any metadata item of the message
409 is greater than the specified UNCHANGEDSINCE value, then the
410 requested operation MUST NOT be performed. In this case, the
411 mod-sequence attribute of the message is not updated, and the
412 message number (or unique identifier in the case of the UID STORE
413 command) is added to the list of messages that failed the
414 UNCHANGESINCE test.
416 When the server finished performing the operation on all the
417 messages in the message set, it checks for a non-empty list of
418 messages that failed the UNCHANGESINCE test. If this list is
419 non-empty, the server MUST return in the tagged response a
420 MODIFIED response code. The MODIFIED response code includes the
421 message set (for STORE) or set of UIDs (for UID STORE) of all
422 messages that failed the UNCHANGESINCE test.
424 Example 3:
426 All messages pass the UNCHANGESINCE test.
428 C: a103 UID STORE 6,4,8 (UNCHANGEDSINCE 12121230045)
429 +FLAGS.SILENT (\Deleted)
430 S: * 1 FETCH (UID 4 MODSEQ (12121231000))
431 S: * 2 FETCH (UID 6 MODSEQ (12121230852))
432 S: * 4 FETCH (UID 8 MODSEQ (12121130956))
433 S: a103 OK Conditional Store completed
435 Example 4:
437 C: a104 STORE * (UNCHANGEDSINCE 12121230045) +FLAGS.SILENT
438 (\Deleted $Processed)
439 S: * 50 FETCH (MODSEQ (12111230047))
440 S: a104 OK Store (conditional) completed
442 Example 5:
444 C: c101 STORE 1 (UNCHANGEDSINCE 12121230045) -FLAGS.SILENT
445 (\Deleted)
446 S: * OK [HIGHESTMODSEQ 12111230047]
450 Melnikov & Hole Standards Track [Page 8]
452 RFC 4551 IMAP Extension for Conditional STORE June 2006
455 S: * 50 FETCH (MODSEQ (12111230048))
456 S: c101 OK Store (conditional) completed
458 HIGHESTMODSEQ response code was sent by the server presumably
459 because this was the first CONDSTORE enabling command.
461 Example 6:
463 In spite of the failure of the conditional STORE operation for
464 message 7, the server continues to process the conditional STORE
465 in order to find all messages that fail the test.
467 C: d105 STORE 7,5,9 (UNCHANGEDSINCE 320162338)
468 +FLAGS.SILENT (\Deleted)
469 S: * 5 FETCH (MODSEQ (320162350))
470 S: d105 OK [MODIFIED 7,9] Conditional STORE failed
472 Example 7:
474 Same as above, but the server follows the SHOULD recommendation in
475 Section 6.4.6 of [IMAP4].
477 C: d105 STORE 7,5,9 (UNCHANGEDSINCE 320162338)
478 +FLAGS.SILENT (\Deleted)
479 S: * 7 FETCH (MODSEQ (320162342) FLAGS (\Seen \Deleted))
480 S: * 5 FETCH (MODSEQ (320162350))
481 S: * 9 FETCH (MODSEQ (320162349) FLAGS (\Answered))
482 S: d105 OK [MODIFIED 7,9] Conditional STORE failed
484 Use of UNCHANGEDSINCE with a modification sequence of 0 always
485 fails if the metadata item exists. A system flag MUST always be
486 considered existent, whether it was set or not.
488 Example 8:
490 C: a102 STORE 12 (UNCHANGEDSINCE 0)
491 +FLAGS.SILENT ($MDNSent)
492 S: a102 OK [MODIFIED 12] Conditional STORE failed
494 The client has tested the presence of the $MDNSent user-defined
495 keyword.
497 Note: A client trying to make an atomic change to the state of a
498 particular metadata item (or a set of metadata items) should be
499 prepared to deal with the case when the server returns the MODIFIED
500 response code if the state of the metadata item being watched hasn't
501 changed (but the state of some other metadata item has). This is
502 necessary, because some servers don't store separate mod-sequences
506 Melnikov & Hole Standards Track [Page 9]
508 RFC 4551 IMAP Extension for Conditional STORE June 2006
511 for different metadata items. However, a server implementation
512 SHOULD avoid generating spurious MODIFIED responses for +FLAGS/-FLAGS
513 STORE operations, even when the server stores a single mod-sequence
514 per message. Section 5 describes how this can be achieved.
516 Unless the server has included an unsolicited FETCH to update
517 client's knowledge about messages that have failed the UNCHANGEDSINCE
518 test, upon receipt of the MODIFIED response code, the client SHOULD
519 try to figure out if the required metadata items have indeed changed
520 by issuing FETCH or NOOP command. It is RECOMMENDED that the server
521 avoids the need for the client to do that by sending an unsolicited
522 FETCH response (Examples 9 and 10).
524 If the required metadata items haven't changed, the client SHOULD
525 retry the command with the new mod-sequence. The client SHOULD allow
526 for a configurable but reasonable number of retries (at least 2).
528 Example 9:
530 In the example below, the server returns the MODIFIED response
531 code without sending information describing why the STORE
532 UNCHANGEDSINCE operation has failed.
534 C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000)
535 +FLAGS.SILENT ($Processed)
536 S: * 100 FETCH (MODSEQ (303181230852))
537 S: * 102 FETCH (MODSEQ (303181230852))
538 ...
539 S: * 150 FETCH (MODSEQ (303181230852))
540 S: a106 OK [MODIFIED 101] Conditional STORE failed
542 The flag $Processed was set on the message 101...
544 C: a107 NOOP
545 S: * 101 FETCH (MODSEQ (303011130956) FLAGS ($Processed))
546 S: a107 OK
548 Or the flag hasn't changed, but another has (note that this server
549 behaviour is discouraged. Server implementers should also see
550 Section 5)...
552 C: b107 NOOP
553 S: * 101 FETCH (MODSEQ (303011130956) FLAGS (\Deleted \Answered))
554 S: b107 OK
556 ...and the client retries the operation for the message 101 with
557 the updated UNCHANGEDSINCE value
562 Melnikov & Hole Standards Track [Page 10]
564 RFC 4551 IMAP Extension for Conditional STORE June 2006
567 C: b108 STORE 101 (UNCHANGEDSINCE 303011130956)
568 +FLAGS.SILENT ($Processed)
569 S: * 101 FETCH (MODSEQ (303181230852))
570 S: b108 OK Conditional Store completed
572 Example 10:
574 Same as above, but the server avoids the need for the client to
575 poll for changes.
577 The flag $Processed was set on the message 101 by another
578 client...
580 C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000)
581 +FLAGS.SILENT ($Processed)
582 S: * 100 FETCH (MODSEQ (303181230852))
583 S: * 101 FETCH (MODSEQ (303011130956) FLAGS ($Processed))
584 S: * 102 FETCH (MODSEQ (303181230852))
585 ...
586 S: * 150 FETCH (MODSEQ (303181230852))
587 S: a106 OK [MODIFIED 101] Conditional STORE failed
589 Or the flag hasn't changed, but another has (note that this server
590 behaviour is discouraged. Server implementers should also see
591 Section 5)...
593 C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000)
594 +FLAGS.SILENT ($Processed)
595 S: * 100 FETCH (MODSEQ (303181230852))
596 S: * 101 FETCH (MODSEQ (303011130956) FLAGS (\Deleted \Answered))
597 S: * 102 FETCH (MODSEQ (303181230852))
598 ...
599 S: * 150 FETCH (MODSEQ (303181230852))
600 S: a106 OK [MODIFIED 101] Conditional STORE failed
602 ...and the client retries the operation for the message 101 with
603 the updated UNCHANGEDSINCE value
605 C: b108 STORE 101 (UNCHANGEDSINCE 303011130956)
606 +FLAGS.SILENT ($Processed)
607 S: * 101 FETCH (MODSEQ (303181230852))
608 S: b108 OK Conditional Store completed
610 Or the flag hasn't changed, but another has (nice server
611 behaviour. Server implementers should also see Section 5)...
613 C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000)
614 +FLAGS.SILENT ($Processed)
618 Melnikov & Hole Standards Track [Page 11]
620 RFC 4551 IMAP Extension for Conditional STORE June 2006
623 S: * 100 FETCH (MODSEQ (303181230852))
624 S: * 101 FETCH (MODSEQ (303011130956) FLAGS ($Processed \Deleted
625 \Answered))
626 S: * 102 FETCH (MODSEQ (303181230852))
627 ...
628 S: * 150 FETCH (MODSEQ (303181230852))
629 S: a106 OK Conditional STORE completed
631 Example 11:
633 The following example is based on the example from the Section
634 4.2.3 of [RFC-2180] and demonstrates that the MODIFIED response
635 code may be also returned in the tagged NO response.
637 Client tries to conditionally STORE flags on a mixture of expunged
638 and non-expunged messages; one message fails the UNCHANGEDSINCE
639 test.
641 C: B001 STORE 1:7 (UNCHANGEDSINCE 320172338) +FLAGS (\SEEN)
642 S: * 1 FETCH (MODSEQ (320172342) FLAGS (\SEEN))
643 S: * 3 FETCH (MODSEQ (320172342) FLAGS (\SEEN))
644 S: B001 NO [MODIFIED 2] Some of the messages no longer exist.
646 C: B002 NOOP
647 S: * 4 EXPUNGE
648 S: * 4 EXPUNGE
649 S: * 4 EXPUNGE
650 S: * 4 EXPUNGE
651 S: * 2 FETCH (MODSEQ (320172340) FLAGS (\Deleted \Answered))
652 S: B002 OK NOOP Completed.
654 By receiving FETCH responses for messages 1 and 3, and EXPUNGE
655 responses that indicate that messages 4 through 7 have been
656 expunged, the client retries the operation only for the message 2.
657 The updated UNCHANGEDSINCE value is used.
659 C: b003 STORE 2 (UNCHANGEDSINCE 320172340) +FLAGS (\Seen)
660 S: * 2 FETCH (MODSEQ (320180050))
661 S: b003 OK Conditional Store completed
663 Note: If a message is specified multiple times in the message set,
664 and the server doesn't internally eliminate duplicates from the
665 message set, it MUST NOT fail the conditional STORE operation for the
666 second (or subsequent) occurrence of the message if the operation
667 completed successfully for the first occurrence. For example, if the
668 client specifies:
674 Melnikov & Hole Standards Track [Page 12]
676 RFC 4551 IMAP Extension for Conditional STORE June 2006
679 e105 STORE 7,3:9 (UNCHANGEDSINCE 12121230045)
680 +FLAGS.SILENT (\Deleted)
682 the server must not fail the operation for message 7 as part of
683 processing "3:9" if it succeeded when message 7 was processed the
684 first time.
686 Once the client specified the UNCHANGEDSINCE modifier in a STORE
687 command, the server MUST include the MODSEQ fetch response data items
688 in all subsequent unsolicited FETCH responses.
690 This document also changes the behaviour of the server when it has
691 performed a STORE or UID STORE command and the UNCHANGEDSINCE
692 modifier is not specified. If the operation is successful for a
693 message, the server MUST update the mod-sequence attribute of the
694 message. The server is REQUIRED to include the mod-sequence value
695 whenever it decides to send the unsolicited FETCH response to all
696 CONDSTORE-aware clients that have opened the mailbox containing the
697 message.
699 Server implementers should also see Section 3.8 for additional
700 quality of implementation issues related to the STORE command.
702 3.3. FETCH and UID FETCH Commands
704 3.3.1. CHANGEDSINCE FETCH Modifier
706 This document defines the following FETCH modifier (see Section 2.4
707 of [IMAPABNF]):
709 CHANGEDSINCE <mod-sequence>
711 CHANGEDSINCE FETCH modifier allows to create a further subset of
712 the list of messages described by sequence set. The information
713 described by message data items is only returned for messages that
714 have mod-sequence bigger than <mod-sequence>.
716 When CHANGEDSINCE FETCH modifier is specified, it implicitly adds
717 MODSEQ FETCH message data item (Section 3.3.2).
719 Example 12:
721 C: s100 UID FETCH 1:* (FLAGS) (CHANGEDSINCE 12345)
722 S: * 1 FETCH (UID 4 MODSEQ (65402) FLAGS (\Seen))
723 S: * 2 FETCH (UID 6 MODSEQ (75403) FLAGS (\Deleted))
724 S: * 4 FETCH (UID 8 MODSEQ (29738) FLAGS ($NoJunk $AutoJunk
725 $MDNSent))
726 S: s100 OK FETCH completed
730 Melnikov & Hole Standards Track [Page 13]
732 RFC 4551 IMAP Extension for Conditional STORE June 2006
735 3.3.2. MODSEQ Message Data Item in FETCH Command
737 This extension adds a MODSEQ message data item to the FETCH command.
738 The MODSEQ message data item allows clients to retrieve mod-sequence
739 values for a range of messages in the currently selected mailbox.
741 Once the client specified the MODSEQ message data item in a FETCH
742 request, the server MUST include the MODSEQ fetch response data items
743 in all subsequent unsolicited FETCH responses.
745 Syntax: MODSEQ
747 The MODSEQ message data item causes the server to return MODSEQ
748 fetch response data items.
750 Syntax: MODSEQ ( <permsg-modsequence> )
752 MODSEQ response data items contain per-message mod-sequences.
754 The MODSEQ response data item is returned if the client issued
755 FETCH with MODSEQ message data item. It also allows the server to
756 notify the client about mod-sequence changes caused by conditional
757 STOREs (Section 3.2) and/or changes caused by external sources.
759 Example 13:
761 C: a FETCH 1:3 (MODSEQ)
762 S: * 1 FETCH (MODSEQ (624140003))
763 S: * 2 FETCH (MODSEQ (624140007))
764 S: * 3 FETCH (MODSEQ (624140005))
765 S: a OK Fetch complete
767 In this example, the client requests per-message mod-sequences for
768 a set of messages.
770 When a flag for a message is modified in a different session, the
771 server sends an unsolicited FETCH response containing the mod-
772 sequence for the message.
774 Example 14:
776 (Session 1, authenticated as a user "alex"). The user adds a
777 shared flag \Deleted:
779 C: A142 SELECT INBOX
780 ...
781 S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
782 S: * OK [PERMANENTFLAGS (\Answered \Deleted \Seen \*)] Limited
786 Melnikov & Hole Standards Track [Page 14]
788 RFC 4551 IMAP Extension for Conditional STORE June 2006
791 ...
793 C: A160 STORE 7 +FLAGS.SILENT (\Deleted)
794 S: * 7 FETCH (MODSEQ (2121231000))
795 S: A160 OK Store completed
797 (Session 2, also authenticated as the user "alex"). Any changes
798 to flags are always reported to all sessions authenticated as the
799 same user as in the session 1.
801 C: C180 NOOP
802 S: * 7 FETCH (FLAGS (\Deleted \Answered) MODSEQ (12121231000))
803 S: C180 OK Noop completed
805 (Session 3, authenticated as a user "andrew"). As \Deleted is a
806 shared flag, changes in session 1 are also reported in session 3:
808 C: D210 NOOP
809 S: * 7 FETCH (FLAGS (\Deleted \Answered) MODSEQ (12121231000))
810 S: D210 OK Noop completed
812 The user modifies a private flag \Seen in session 1...
814 C: A240 STORE 7 +FLAGS.SILENT (\Seen)
815 S: * 7 FETCH (MODSEQ (12121231777))
816 S: A240 OK Store completed
818 ...which is only reported in session 2...
820 C: C270 NOOP
821 S: * 7 FETCH (FLAGS (\Deleted \Answered \Seen) MODSEQ
822 (12121231777))
823 S: C270 OK Noop completed
825 ...but not in session 3.
827 C: D300 NOOP
828 S: D300 OK Noop completed
830 And finally, the user removes flags \Answered (shared) and \Seen
831 (private) in session 1.
833 C: A330 STORE 7 -FLAGS.SILENT (\Answered \Seen)
834 S: * 7 FETCH (MODSEQ (12121245160))
835 S: A330 OK Store completed
842 Melnikov & Hole Standards Track [Page 15]
844 RFC 4551 IMAP Extension for Conditional STORE June 2006
847 Both changes are reported in the session 2...
849 C: C360 NOOP
850 S: * 7 FETCH (FLAGS (\Deleted) MODSEQ (12121245160))
851 S: C360 OK Noop completed
853 ...and only changes to shared flags are reported in session 3.
855 C: D390 NOOP
856 S: * 7 FETCH (FLAGS (\Deleted) MODSEQ (12121245160))
857 S: D390 OK Noop completed
859 Server implementers should also see Section 3.8 for additional
860 quality of implementation issues related to the FETCH command.
862 3.4. MODSEQ Search Criterion in SEARCH
864 The MODSEQ criterion for the SEARCH command allows a client to search
865 for the metadata items that were modified since a specified moment.
867 Syntax: MODSEQ [<entry-name> <entry-type-req>] <mod-sequence-valzer>
869 Messages that have modification values that are equal to or
870 greater than <mod-sequence-valzer>. This allows a client, for
871 example, to find out which messages contain metadata items that
872 have changed since the last time it updated its disconnected
873 cache. The client may also specify <entry-name> (name of metadata
874 item) and <entry-type-req> (type of metadata item) before
875 <mod-sequence-valzer>. <entry-type-req> can be one of "shared",
876 "priv" (private), or "all". The latter means that the server
877 should use the biggest value among "priv" and "shared" mod-
878 sequences for the metadata item. If the server doesn't store
879 internally separate mod-sequences for different metadata items, it
880 MUST ignore <entry-name> and <entry-type-req>. Otherwise, the
881 server should use them to narrow down the search.
883 For a flag <flagname>, the corresponding <entry-name> has a form
884 "/flags/<flagname>" as defined in [IMAPABNF]. Note that the
885 leading "\" character that denotes a system flag has to be escaped
886 as per Section 4.3 of [IMAP4], as the <entry-name> uses syntax for
887 quoted strings.
889 If client specifies a MODSEQ criterion in a SEARCH command and the
890 server returns a non-empty SEARCH result, the server MUST also append
891 (to the end of the untagged SEARCH response) the highest mod-sequence
892 for all messages being returned. See also Section 3.5.
898 Melnikov & Hole Standards Track [Page 16]
900 RFC 4551 IMAP Extension for Conditional STORE June 2006
903 Example 15:
905 C: a SEARCH MODSEQ "/flags/\\draft" all 620162338
906 S: * SEARCH 2 5 6 7 11 12 18 19 20 23 (MODSEQ 917162500)
907 S: a OK Search complete
909 In the above example, the message numbers of any messages
910 containing the string "IMAP4" in the "value" attribute of the
911 "/comment" entry and having a mod-sequence equal to or greater
912 than 620162338 for the "\Draft" flag are returned in the search
913 results.
915 Example 16:
917 C: t SEARCH OR NOT MODSEQ 720162338 LARGER 50000
918 S: * SEARCH
919 S: t OK Search complete, nothing found
921 3.5. Modified SEARCH Untagged Response
923 Data: zero or more numbers
924 mod-sequence value (omitted if no match)
926 This document extends syntax of the untagged SEARCH response to
927 include the highest mod-sequence for all messages being returned.
929 If a client specifies a MODSEQ criterion in a SEARCH (or UID SEARCH)
930 command and the server returns a non-empty SEARCH result, the server
931 MUST also append (to the end of the untagged SEARCH response) the
932 highest mod-sequence for all messages being returned. See Section
933 3.4 for examples.
935 3.6. HIGHESTMODSEQ Status Data Items
937 This document defines a new status data item:
939 HIGHESTMODSEQ
941 The highest mod-sequence value of all messages in the mailbox.
942 This is the same value that is returned by the server in the
943 HIGHESTMODSEQ response code in an OK untagged response (see
944 Section 3.1.1). If the server doesn't support the persistent
945 storage of mod-sequences for the mailbox (see Section 3.1.2), the
946 server MUST return 0 as the value of HIGHESTMODSEQ status data
947 item.
954 Melnikov & Hole Standards Track [Page 17]
956 RFC 4551 IMAP Extension for Conditional STORE June 2006
959 Example 17:
961 C: A042 STATUS blurdybloop (UIDNEXT MESSAGES HIGHESTMODSEQ)
962 S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292
963 HIGHESTMODSEQ 7011231777)
964 S: A042 OK STATUS completed
966 3.7. CONDSTORE Parameter to SELECT and EXAMINE
968 The CONDSTORE extension defines a single optional select parameter,
969 "CONDSTORE", which tells the server that it MUST include the MODSEQ
970 fetch response data items in all subsequent unsolicited FETCH
971 responses.
973 The CONDSTORE parameter to SELECT/EXAMINE helps avoid a race
974 condition that might arise when one or more metadata items are
975 modified in another session after the server has sent the
976 HIGHESTMODSEQ response code and before the client was able to issue a
977 CONDSTORE enabling command.
979 Example 18:
981 C: A142 SELECT INBOX (CONDSTORE)
982 S: * 172 EXISTS
983 S: * 1 RECENT
984 S: * OK [UNSEEN 12] Message 12 is first unseen
985 S: * OK [UIDVALIDITY 3857529045] UIDs valid
986 S: * OK [UIDNEXT 4392] Predicted next UID
987 S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
988 S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited
989 S: * OK [HIGHESTMODSEQ 715194045007]
990 S: A142 OK [READ-WRITE] SELECT completed, CONDSTORE is now enabled
992 3.8. Additional Quality-of-Implementation Issues
994 Server implementations should follow the following rule, which
995 applies to any successfully completed STORE/UID STORE (with and
996 without UNCHANGEDSINCE modifier), as well as to a FETCH command that
997 implicitly sets \Seen flag:
999 Adding the flag when it is already present or removing when it is
1000 not present SHOULD NOT change the mod-sequence.
1002 This will prevent spurious client synchronization requests.
1010 Melnikov & Hole Standards Track [Page 18]
1012 RFC 4551 IMAP Extension for Conditional STORE June 2006
1015 However, note that client implementers MUST NOT rely on this server
1016 behavior. A client can't distinguish between the case when a server
1017 has violated the SHOULD mentioned above, and that when one or more
1018 clients set and unset (or unset and set) the flag in another session.
1020 4. Formal Syntax
1022 The following syntax specification uses the Augmented Backus-Naur
1023 Form (ABNF) [ABNF] notation. Elements not defined here can be found
1024 in the formal syntax of the ABNF [ABNF], IMAP [IMAP4], and IMAP ABNF
1025 extensions [IMAPABNF] specifications.
1027 Except as noted otherwise, all alphabetic characters are case-
1028 insensitive. The use of upper- or lowercase characters to define
1029 token strings is for editorial clarity only. Implementations MUST
1030 accept these strings in a case-insensitive fashion.
1032 capability =/ "CONDSTORE"
1034 status-att =/ "HIGHESTMODSEQ"
1035 ;; extends non-terminal defined in RFC 3501.
1037 status-att-val =/ "HIGHESTMODSEQ" SP mod-sequence-valzer
1038 ;; extends non-terminal defined in [IMAPABNF].
1039 ;; Value 0 denotes that the mailbox doesn't
1040 ;; support persistent mod-sequences
1041 ;; as described in Section 3.1.2
1043 store-modifier =/ "UNCHANGEDSINCE" SP mod-sequence-valzer
1044 ;; Only a single "UNCHANGEDSINCE" may be
1045 ;; specified in a STORE operation
1047 fetch-modifier =/ chgsince-fetch-mod
1048 ;; conforms to the generic "fetch-modifier"
1049 ;; syntax defined in [IMAPABNF].
1051 chgsince-fetch-mod = "CHANGEDSINCE" SP mod-sequence-value
1052 ;; CHANGEDSINCE FETCH modifier conforms to
1053 ;; the fetch-modifier syntax
1055 fetch-att =/ fetch-mod-sequence
1056 ;; modifies original IMAP4 fetch-att
1058 fetch-mod-sequence = "MODSEQ"
1060 fetch-mod-resp = "MODSEQ" SP "(" permsg-modsequence ")"
1062 msg-att-dynamic =/ fetch-mod-resp
1066 Melnikov & Hole Standards Track [Page 19]
1068 RFC 4551 IMAP Extension for Conditional STORE June 2006
1071 search-key =/ search-modsequence
1072 ;; modifies original IMAP4 search-key
1073 ;;
1074 ;; This change applies to all commands
1075 ;; referencing this non-terminal, in
1076 ;; particular SEARCH.
1078 search-modsequence = "MODSEQ" [search-modseq-ext] SP
1079 mod-sequence-valzer
1081 search-modseq-ext = SP entry-name SP entry-type-req
1083 resp-text-code =/ "HIGHESTMODSEQ" SP mod-sequence-value /
1084 "NOMODSEQ" /
1085 "MODIFIED" SP set
1087 entry-name = entry-flag-name
1089 entry-flag-name = DQUOTE "/flags/" attr-flag DQUOTE
1090 ;; each system or user defined flag <flag>
1091 ;; is mapped to "/flags/<flag>".
1092 ;;
1093 ;; <entry-flag-name> follows the escape rules
1094 ;; used by "quoted" string as described in
1095 ;; Section 4.3 of [IMAP4], e.g., for the flag
1096 ;; \Seen the corresponding <entry-name> is
1097 ;; "/flags/\\seen", and for the flag
1098 ;; $MDNSent, the corresponding <entry-name>
1099 ;; is "/flags/$mdnsent".
1101 entry-type-resp = "priv" / "shared"
1102 ;; metadata item type
1104 entry-type-req = entry-type-resp / "all"
1105 ;; perform SEARCH operation on private
1106 ;; metadata item, shared metadata item or both
1108 permsg-modsequence = mod-sequence-value
1109 ;; per message mod-sequence
1111 mod-sequence-value = 1*DIGIT
1112 ;; Positive unsigned 64-bit integer
1113 ;; (mod-sequence)
1114 ;; (1 <= n < 18,446,744,073,709,551,615)
1116 mod-sequence-valzer = "0" / mod-sequence-value
1118 search-sort-mod-seq = "(" "MODSEQ" SP mod-sequence-value ")"
1122 Melnikov & Hole Standards Track [Page 20]
1124 RFC 4551 IMAP Extension for Conditional STORE June 2006
1127 select-param =/ condstore-param
1128 ;; conforms to the generic "select-param"
1129 ;; non-terminal syntax defined in [IMAPABNF].
1131 condstore-param = "CONDSTORE"
1133 mailbox-data =/ "SEARCH" [1*(SP nz-number) SP
1134 search-sort-mod-seq]
1136 attr-flag = "\\Answered" / "\\Flagged" / "\\Deleted" /
1137 "\\Seen" / "\\Draft" / attr-flag-keyword /
1138 attr-flag-extension
1139 ;; Does not include "\\Recent"
1141 attr-flag-extension = "\\" atom
1142 ;; Future expansion. Client implementations
1143 ;; MUST accept flag-extension flags. Server
1144 ;; implementations MUST NOT generate
1145 ;; flag-extension flags except as defined by
1146 ;; future standard or standards-track
1147 ;; revisions of [IMAP4].
1149 attr-flag-keyword = atom
1151 5. Server Implementation Considerations
1153 This section describes how a server implementation that doesn't store
1154 separate per-metadata mod-sequences for different metadata items can
1155 avoid sending the MODIFIED response to any of the following
1156 conditional STORE operations:
1158 +FLAGS
1159 -FLAGS
1160 +FLAGS.SILENT
1161 -FLAGS.SILENT
1163 Note that the optimization described in this section can't be
1164 performed in case of a conditional STORE FLAGS operation.
1166 Let's use the following example. The client has issued
1168 C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000)
1169 +FLAGS.SILENT ($Processed)
1171 When the server receives the command and parses it successfully, it
1172 iterates through the message set and tries to execute the conditional
1173 STORE command for each message.
1178 Melnikov & Hole Standards Track [Page 21]
1180 RFC 4551 IMAP Extension for Conditional STORE June 2006
1183 Each server internally works as a client, i.e., it has to cache the
1184 current state of all IMAP flags as it is known to the client. In
1185 order to report flag changes to the client, the server compares the
1186 cached values with the values in its database for IMAP flags.
1188 Imagine that another client has changed the state of a flag \Deleted
1189 on the message 101 and that the change updated the mod-sequence for
1190 the message. The server knows that the mod-sequence for the mailbox
1191 has changed; however, it also knows that:
1193 a) the client is not interested in \Deleted flag, as it hasn't
1194 included it in +FLAGS.SILENT operation; and
1196 b) the state of the flag $Processed hasn't changed (the server can
1197 determine this by comparing cached flag state with the state of
1198 the flag in the database).
1200 Therefore, the server doesn't have to report MODIFIED to the client.
1201 Instead, the server may set $Processed flag, update the mod-sequence
1202 for the message 101 once again and send an untagged FETCH response
1203 with new mod-sequence and flags:
1205 S: * 101 FETCH (MODSEQ (303011130956)
1206 FLAGS ($Processed \Deleted \Answered))
1208 See also Section 3.8 for additional quality-of-implementation issues.
1210 6. Security Considerations
1212 It is believed that the Conditional STORE extension doesn't raise any
1213 new security concerns that are not already discussed in [IMAP4].
1214 However, the availability of this extension may make it possible for
1215 IMAP4 to be used in critical applications it could not be used for
1216 previously, making correct IMAP server implementation and operation
1217 even more important.
1219 7. IANA Considerations
1221 IMAP4 capabilities are registered by publishing a standards track or
1222 IESG approved experimental RFC. The registry is currently located
1223 at:
1225 http://www.iana.org/assignments/imap4-capabilities
1227 This document defines the CONDSTORE IMAP capability. IANA has added
1228 it to the registry accordingly.
1234 Melnikov & Hole Standards Track [Page 22]
1236 RFC 4551 IMAP Extension for Conditional STORE June 2006
1239 8. References
1241 8.1. Normative References
1243 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
1244 Requirement Levels", BCP 14, RFC 2119, March 1997.
1246 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
1247 Specifications: ABNF", RFC 4234, October 2005.
1249 [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
1250 4rev1", RFC 3501, March 2003.
1252 [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
1253 ABNF", RFC 4466, April 2006.
1255 8.2. Informative References
1257 [ACAP] Newman, C. and J. Myers, "ACAP -- Application
1258 Configuration Access Protocol", RFC 2244, November 1997.
1260 [ACL] Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
1261 RFC 4314, December 2005.
1263 [ANN] Daboo, C. and R. Gellens, "IMAP ANNOTATE Extension", Work
1264 in Progress, March 2006.
1266 [NTP] Mills, D., "Network Time Protocol (Version 3)
1267 Specification, Implementation and Analysis", RFC 1305,
1268 March 1992.
1270 [RFC-2180] Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC
1271 2180, July 1997.
1273 9. Acknowledgements
1275 Some text was borrowed from "IMAP ANNOTATE Extension" [ANN] by
1276 Randall Gellens and Cyrus Daboo and from "ACAP -- Application
1277 Configuration Access Protocol" [ACAP] by Chris Newman and John Myers.
1279 Many thanks to Randall Gellens for his thorough review of the
1280 document.
1282 The authors also acknowledge the feedback provided by Cyrus Daboo,
1283 Larry Greenfield, Chris Newman, Harrie Hazewinkel, Arnt Gulbrandsen,
1284 Timo Sirainen, Mark Crispin, Ned Freed, Ken Murchison, and Dave
1285 Cridland.
1290 Melnikov & Hole Standards Track [Page 23]
1292 RFC 4551 IMAP Extension for Conditional STORE June 2006
1295 Authors' Addresses
1297 Alexey Melnikov
1298 Isode Limited
1299 5 Castle Business Village
1300 36 Station Road
1301 Hampton, Middlesex
1302 TW12 2BX,
1303 United Kingdom
1305 EMail: Alexey.Melnikov@isode.com
1308 Steve Hole
1309 ACI WorldWide/MessagingDirect
1310 #1807, 10088 102 Ave
1311 Edmonton, AB
1312 T5J 2Z1
1313 Canada
1315 EMail: Steve.Hole@messagingdirect.com
1346 Melnikov & Hole Standards Track [Page 24]
1348 RFC 4551 IMAP Extension for Conditional STORE June 2006
1351 Full Copyright Statement
1353 Copyright (C) The Internet Society (2006).
1355 This document is subject to the rights, licenses and restrictions
1356 contained in BCP 78, and except as set forth therein, the authors
1357 retain all their rights.
1359 This document and the information contained herein are provided on an
1360 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
1361 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
1362 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
1363 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
1364 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
1365 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1367 Intellectual Property
1369 The IETF takes no position regarding the validity or scope of any
1370 Intellectual Property Rights or other rights that might be claimed to
1371 pertain to the implementation or use of the technology described in
1372 this document or the extent to which any license under such rights
1373 might or might not be available; nor does it represent that it has
1374 made any independent effort to identify any such rights. Information
1375 on the procedures with respect to rights in RFC documents can be
1376 found in BCP 78 and BCP 79.
1378 Copies of IPR disclosures made to the IETF Secretariat and any
1379 assurances of licenses to be made available, or the result of an
1380 attempt made to obtain a general license or permission for the use of
1381 such proprietary rights by implementers or users of this
1382 specification can be obtained from the IETF on-line IPR repository at
1383 http://www.ietf.org/ipr.
1385 The IETF invites any interested party to bring to its attention any
1386 copyrights, patents or patent applications, or other proprietary
1387 rights that may cover technology that may be required to implement
1388 this standard. Please address the information to the IETF at
1389 ietf-ipr@ietf.org.
1391 Acknowledgement
1393 Funding for the RFC Editor function is provided by the IETF
1394 Administrative Support Activity (IASA).
1402 Melnikov & Hole Standards Track [Page 25]