1
2
3
4
5
6
7Network Working Group A. Gulbrandsen
8Request for Comments: 5465 Oryx Mail Systems GmbH
9Updates: 5267 C. King
10Category: Standards Track A. Melnikov
11 Isode Ltd.
12 February 2009
13
14
15 The IMAP NOTIFY Extension
16
17Status of This Memo
18
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.
24
25Copyright Notice
26
27 Copyright (c) 2009 IETF Trust and the persons identified as the
28 document authors. All rights reserved.
29
30 This document is subject to BCP 78 and the IETF Trust's Legal
31 Provisions Relating to IETF Documents (http://trustee.ietf.org/
32 license-info) in effect on the date of publication of this document.
33 Please review these documents carefully, as they describe your rights
34 and restrictions with respect to this document.
35
36Abstract
37
38 This document defines an IMAP extension that allows a client to
39 request specific kinds of unsolicited notifications for specified
40 mailboxes, such as messages being added to or deleted from such
41 mailboxes.
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58Gulbrandsen, et al. Standards Track [Page 1]
59
60RFC 5465 IMAP NOTIFY Extension February 2009
61
62
63Table of Contents
64
65 1. Overview and Rationale ..........................................3
66 2. Conventions Used in This Document ...............................4
67 3. The NOTIFY Extension ............................................4
68 3.1. The NOTIFY Command .........................................4
69 4. Interaction with the IDLE Command ...............................8
70 5. Event Types .....................................................8
71 5.1. FlagChange and AnnotationChange ............................9
72 5.2. MessageNew .................................................9
73 5.3. MessageExpunge ............................................10
74 5.4. MailboxName ...............................................11
75 5.5. SubscriptionChange ........................................12
76 5.6. MailboxMetadataChange .....................................12
77 5.7. ServerMetadataChange ......................................13
78 5.8. Notification Overflow .....................................13
79 5.9. ACL (Access Control List) Changes .........................13
80 6. Mailbox Specification ..........................................14
81 6.1. Mailbox Specifiers Affecting the Currently
82 Selected Mailbox ..........................................14
83 6.2. Personal ..................................................15
84 6.3. Inboxes ...................................................15
85 6.4. Subscribed ................................................15
86 6.5. Subtree ...................................................15
87 6.6. Mailboxes .................................................16
88 7. Extension to SEARCH and SORT Commands ..........................16
89 8. Formal Syntax ..................................................16
90 9. Security Considerations ........................................19
91 10. IANA Considerations ...........................................19
92 10.1. Initial LIST-EXTENDED Extended Data Item Registrations ...19
93 11. Acknowledgements ..............................................20
94 12. Normative References ..........................................20
95 13. Informative References ........................................21
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114Gulbrandsen, et al. Standards Track [Page 2]
115
116RFC 5465 IMAP NOTIFY Extension February 2009
117
118
1191. Overview and Rationale
120
121 The IDLE command (defined in [RFC2177]) provides a way for the client
122 to go into a mode where the IMAP server pushes it notifications about
123 IMAP mailstore events for the selected mailbox. However, the IDLE
124 extension doesn't restrict or control which server events can be
125 sent, or what information the server sends in response to each event.
126 Also, IDLE only applies to the selected mailbox, thus requiring an
127 additional TCP connection per mailbox.
128
129 This document defines an IMAP extension that allows clients to
130 express their preferences about unsolicited events generated by the
131 server. The extension allows clients to only receive events that
132 they are interested in, while servers know that they don't need to go
133 to the effort of generating certain types of untagged responses.
134
135 Without the NOTIFY command defined in this document, an IMAP server
136 will only send information about mailstore changes to the client in
137 the following cases:
138
139 - as the result of a client command (e.g., FETCH responses to a
140 FETCH or STORE command),
141 - as unsolicited responses sent just before the end of a command
142 (e.g., EXISTS or EXPUNGE) as the result of changes in other
143 sessions, and
144 - during an IDLE command.
145
146 The NOTIFY command extends what information may be returned in those
147 last two cases, and also permits and requires the server to send
148 information about updates between commands. The NOTIFY command also
149 allows for the client to extend what information is sent unsolicited
150 about the selected mailbox and to request some update information to
151 be sent regarding other mailboxes.
152
153 The interaction between IDLE and NOTIFY commands is described in
154 Section 4.
155
156 For the new messages delivered to or appended to the selected
157 mailbox, the NOTIFY command can be used to request that a set of
158 attributes be sent to the client in an unsolicited FETCH response.
159 This allows a client to be a passive recipient of events and new mail
160 and to be able to maintain full synchronisation without having to
161 issue any subsequent commands except to modify the state of the
162 mailbox on the server.
163
164
165
166
167
168
169
170Gulbrandsen, et al. Standards Track [Page 3]
171
172RFC 5465 IMAP NOTIFY Extension February 2009
173
174
175 Some mobile clients, however, may want mail "pushed" only for mail
176 that matches a SEARCH pattern. To meet that need, [RFC5267] is
177 augmented by this document to extend the UPDATE return option to
178 specify a list of fetch-atts to be returned when a new message is
179 delivered or appended in another session.
180
1812. Conventions Used in This Document
182
183 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
184 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
185 document are to be interpreted as described in [RFC2119].
186
187 The acronym MSN stands for Message Sequence Numbers (see Section
188 2.3.1.2 of [RFC3501]).
189
190 Example lines prefaced by "C:" are sent by the client and ones
191 prefaced by "S:", by the server. "[...]" means elision.
192
1933. The NOTIFY Extension
194
195 IMAP servers that support this extension advertise the NOTIFY
196 capability. This extension adds the NOTIFY command as defined in
197 Section 5.1.
198
199 A server implementing this extension is not required to implement
200 LIST-EXTENDED [RFC5258], even though a NOTIFY-compliant server must
201 be able to return extended LIST responses, defined in [RFC5258].
202
2033.1. The NOTIFY Command
204
205 Arguments: "SET"
206 Optional STATUS indicator
207 Mailboxes to be watched
208 Events about which to notify the client
209
210 Or
211 Arguments: "NONE"
212
213 Responses: Possibly untagged STATUS responses (for SET)
214
215 Result: OK - The server will notify the client as requested.
216 NO - Unsupported NOTIFY event, NOTIFY too complex or
217 expensive, etc.
218 BAD - Command unknown, invalid, unsupported, or has
219 unknown arguments.
220
221
222
223
224
225
226Gulbrandsen, et al. Standards Track [Page 4]
227
228RFC 5465 IMAP NOTIFY Extension February 2009
229
230
231 The NOTIFY command informs the server that the client listens for
232 event notifications all the time (even when no command is in
233 progress), and requests the server to notify it about the specified
234 set of events. The NOTIFY command has two forms. NOTIFY NONE
235 specifies that the client is not interested in any kind of event
236 happening on the server. NOTIFY SET replaces the current list of
237 interesting events with a new list of events.
238
239 Until the NOTIFY command is used for the first time, the server only
240 sends notifications while a command is being processed, and notifies
241 the client about these events on the selected mailbox (see Section 5
242 for definitions): MessageNew, MessageExpunge, or FlagChange. It does
243 not notify the client about any events on other mailboxes.
244
245 The effect of a successful NOTIFY command lasts until the next NOTIFY
246 command or until the IMAP connection is closed.
247
248 A successful NOTIFY SET command MUST cause the server to immediately
249 return any accumulated changes to the currently selected mailbox (if
250 any), such as flag changes and new or expunged messages. Thus, a
251 successful NOTIFY SET command implies an implicit NOOP command.
252
253 The NOTIFY SET command can request notifications of message-related
254 changes to the selected mailbox, whatever that may be at the time the
255 message notifications are being generated. This is done by
256 specifying either the SELECTED or the SELECTED-DELAYED mailbox
257 selector (see Section 6.1) in the NOTIFY SET command. If the
258 SELECTED/SELECTED-DELAYED mailbox selector is not specified in the
259 NOTIFY SET command, this means that the client doesn't want to
260 receive any <message-event>s for the currently selected mailbox.
261 This is the same as specifying SELECTED NONE.
262
263 The client can also request notifications on other mailboxes by name
264 or by a limited mailbox pattern match. Message-related notifications
265 returned for the currently selected mailbox will be those specified
266 by the SELECTED/SELECTED-DELAYED mailbox specifier, even if the
267 selected mailbox also appears by name (or matches a pattern) in the
268 command. Non-message-related notifications are controlled by mailbox
269 specifiers other than SELECTED/SELECTED-DELAYED.
270
271 If the NOTIFY command enables MessageNew, MessageExpunge,
272 AnnotationChange, or FlagChange notifications for a mailbox other
273 than the currently selected mailbox, and the client has specified the
274 STATUS indicator parameter, then the server MUST send a STATUS
275 response for that mailbox before NOTIFY's tagged OK. If MessageNew
276 is enabled, the STATUS response MUST contain MESSAGES, UIDNEXT, and
277 UIDVALIDITY. If MessageExpunge is enabled, the STATUS response MUST
278 contain MESSAGES. If either AnnotationChange or FlagChange are
279
280
281
282Gulbrandsen, et al. Standards Track [Page 5]
283
284RFC 5465 IMAP NOTIFY Extension February 2009
285
286
287 included and the server also supports the CONDSTORE [RFC4551] and/or
288 QRESYNC [RFC5162] extensions, the STATUS response MUST contain
289 UIDVALIDITY and HIGHESTMODSEQ. Absence of the STATUS indicator
290 parameter allows the client to avoid the additional STATUS responses.
291 This might be useful if the client already retrieved this information
292 before issuing the NOTIFY command.
293
294 Clients are advised to limit the number of mailboxes used with
295 NOTIFY. Particularly, if a client asks for events for all accessible
296 mailboxes, the server may swamp the client with updates about shared
297 mailboxes. This may reduce the client's battery life. Also, this
298 wastes both server and network resources.
299
300 For each mailbox specified, the server verifies that the client has
301 access using the following test:
302
303 - If the name does not refer to an existing mailbox, the server MUST
304 ignore it.
305
306 - If the name refers to a mailbox that the client can't LIST, the
307 server MUST ignore it. For a server that implements [RFC4314],
308 this means that if the client doesn't have the 'l' (lookup) right
309 for the name, then the server MUST ignore the mailbox. This
310 behavior prevents disclosure of potentially confidential
311 information to clients who don't have rights to know it.
312
313 - If the name refers to a mailbox that the client can LIST (e.g., it
314 has the 'l' right from [RFC4314]), but the client doesn't have
315 another right required for processing of the specified event(s),
316 then the server MUST respond with an untagged extended LIST
317 response containing the \NoAccess name attribute.
318
319 The server SHOULD return the tagged OK response if the client has
320 access to at least one of the mailboxes specified in the current list
321 of interesting events. The server MAY return the tagged NO response
322 if the client has no access to any of the specified mailboxes and no
323 access can ever be granted in the future (e.g., the client specified
324 an event for 'Subtree Bar/Foo', 'Bar/Foo' doesn't exist, and LIST
325 returns \Noinferiors for the parent 'Bar').
326
327 If the notification would be prohibitively expensive for the server
328 (e.g., "notify me of all flag changes in all mailboxes"), the server
329 MAY refuse the command with a tagged NO [NOTIFICATIONOVERFLOW]
330 response.
331
332
333
334
335
336
337
338Gulbrandsen, et al. Standards Track [Page 6]
339
340RFC 5465 IMAP NOTIFY Extension February 2009
341
342
343 If the client requests information for events of an unsupported type,
344 the server MUST refuse the command with a tagged NO response (not a
345 BAD). This response SHOULD contain the BADEVENT response code, which
346 MUST list names of all events supported by the server.
347
348 Here's an example:
349
350 S: * OK [CAPABILITY IMAP4REV1 NOTIFY]
351 C: a login bob alice
352 S: a OK Password matched
353 C: b notify set status (selected MessageNew (uid
354 body.peek[header.fields (from to subject)]) MessageExpunge)
355 (subtree Lists MessageNew)
356 S: * STATUS Lists/Lemonade (UIDVALIDITY 4 UIDNEXT 9999 MESSAGES
357 500)
358 S: [...]
359 S: * STATUS Lists/Im2000 (UIDVALIDITY 901 UIDNEXT 1 MESSAGES 0)
360 S: b OK done
361 C: c select inbox
362 S: [...] (the usual 7-8 responses to SELECT)
363 S: c OK INBOX selected
364 (Time passes. A new message is delivered to mailbox
365 Lists/Lemonade.)
366 S: * STATUS Lists/Lemonade (UIDVALIDITY 4 UIDNEXT 10000
367 MESSAGES 501)
368 (Time passes. A new message is delivered to inbox.)
369 S: * 127 FETCH (UID 127001 BODY[HEADER.FIELDS (From To
370 Subject)] {75}
371 S: Subject: Re: good morning
372 S: From: alice@example.org
373 S: To: bob@example.org
374 S:
375 S: )
376 (Time passes. The client decides it wants to know about
377 one more mailbox. As the client already knows necessary
378 STATUS information for all mailboxes below the Lists
379 mailbox, and because "notify set status" would cause
380 STATUS responses for *all* mailboxes specified in the
381 NOTIFY command, including the ones for which the client
382 already knows STATUS information, the client issues an
383 explicit STATUS request for the mailbox to be added to
384 the watch list, followed by the NOTIFY SET without the
385 STATUS parameter.)
386 C: d STATUS misc (UIDVALIDITY UIDNEXT MESSAGES)
387 S: * STATUS misc (UIDVALIDITY 1 UIDNEXT 999)
388 S: d STATUS completed
389
390
391
392
393
394Gulbrandsen, et al. Standards Track [Page 7]
395
396RFC 5465 IMAP NOTIFY Extension February 2009
397
398
399 C: e notify set (selected MessageNew (uid
400 body.peek[header.fields (from to subject)]) MessageExpunge)
401 (subtree Lists MessageNew) (mailboxes misc MessageNew)
402 S: e OK done
403
4044. Interaction with the IDLE Command
405
406 If IDLE [RFC2177] (as well as this extension) is supported, then
407 while processing any IDLE command, the server MUST send exactly the
408 same events as instructed by the client using the NOTIFY command.
409
410 NOTIFY makes IDLE unnecessary for some clients. If a client does not
411 use MSNs and '*' in commands, it can request MessageExpunge and
412 MessageNew for the selected mailbox by using the NOTIFY command
413 instead of entering the IDLE mode.
414
415 A client that uses MSNs and '*' in commands can still use the NOTIFY
416 command if it specifies the SELECTED-DELAYED mailbox specifier in the
417 NOTIFY command.
418
4195. Event Types
420
421 Only some of the events in [RFC5423] can be expressed in IMAP, and
422 for some of them there are several possible ways to express the
423 event.
424
425 This section specifies the events of which an IMAP server can notify
426 an IMAP client, and how.
427
428 The server SHOULD omit notifying the client if the event is caused by
429 this client. For example, if the client issues CREATE and has
430 requested a MailboxName event that would cover the newly created
431 mailbox, the server SHOULD NOT notify the client of the MailboxName
432 change.
433
434 All event types described in this document require the 'l' and 'r'
435 rights (see [RFC4314]) on all observed mailboxes. Servers that don't
436 implement [RFC4314] should map the above rights to their access-
437 control model.
438
439 If the FlagChange and/or AnnotationChange events are specified,
440 MessageNew and MessageExpunge MUST also be specified by the client.
441 Otherwise, the server MUST respond with the tagged BAD response.
442
443 If one of MessageNew or MessageExpunge is specified, then both events
444 MUST be specified. Otherwise, the server MUST respond with the
445 tagged BAD response.
446
447
448
449
450Gulbrandsen, et al. Standards Track [Page 8]
451
452RFC 5465 IMAP NOTIFY Extension February 2009
453
454
455 The client can instruct the server not to send an event by omitting
456 the necessary event from the list of events specified in NOTIFY SET,
457 by using the NONE event specifier in the NOTIFY SET, or by using
458 NOTIFY NONE. In particular, NOTIFY SET ... NONE can be used as a
459 snapshot facility by clients.
460
4615.1. FlagChange and AnnotationChange
462
463 If the flag and/or message annotation change happens in the selected
464 mailbox, the server MUST notify the client by sending an unsolicited
465 FETCH response, which MUST include UID and FLAGS/ANNOTATION FETCH
466 data items. It MAY also send new FLAGS and/or OK [PERMANENTFLAGS
467 ...] responses.
468
469 If a search context is in effect as specified in [RFC5267], an
470 ESEARCH ADDTO or ESEARCH REMOVEFROM will also be generated, if
471 appropriate. In this case, the FETCH response MUST precede the
472 ESEARCH response.
473
474 If the change happens in another mailbox, then the server responds
475 with a STATUS response. The exact content of the STATUS response
476 depends on various factors. If CONDSTORE [RFC4551] and/or QRESYNC
477 [RFC5162] are enabled by the client, then the server sends a STATUS
478 response that includes at least HIGHESTMODSEQ and UIDVALIDITY status
479 data items. If the number of messages with the \Seen flag changes,
480 the server MAY also include the UNSEEN data item in the STATUS
481 response. If CONDSTORE/QRESYNC is not enabled by the client and the
482 server chooses not to include the UNSEEN data item, the server does
483 not notify the client. When this event is requested, the server MUST
484 notify the client about mailbox UIDVALIDITY changes. This is done by
485 sending a STATUS response that includes UIDVALIDITY.
486
487 FlagChange covers the MessageRead, MessageTrash, FlagsSet, and
488 FlagsClear events in [RFC5423].
489
490 Example in the selected mailbox:
491 S: * 99 FETCH (UID 9999 FLAGS ($Junk))
492
493 And in another mailbox, with CONDSTORE in use:
494 S: * STATUS Lists/Lemonade (HIGHESTMODSEQ 65666665 UIDVALIDITY
495 101)
496
497
498
499
500
501
502
503
504
505
506Gulbrandsen, et al. Standards Track [Page 9]
507
508RFC 5465 IMAP NOTIFY Extension February 2009
509
510
5115.2. MessageNew
512
513 This covers both MessageNew and MessageAppend in [RFC5423].
514
515 If the new/appended message is in the selected mailbox, the server
516 notifies the client by sending an unsolicited EXISTS response,
517 followed by an unsolicited FETCH response containing the information
518 requested by the client. A FETCH response SHOULD NOT be generated
519 for a new message created by the client on this particular
520 connection, for instance, as the result of an APPEND or COPY command
521 to the selected mailbox performed by the client itself. The server
522 MAY also send a RECENT response, if the server marks the message as
523 \Recent.
524
525 Note that a single EXISTS response can be returned for multiple
526 MessageAppend/MessageNew events.
527
528 If a search context is in effect as specified in [RFC5267], an
529 ESEARCH ADDTO will also be generated, if appropriate. In this case,
530 the EXISTS response MUST precede the ESEARCH response. Both the
531 NOTIFY command and the SEARCH and SORT commands (see Section 7) can
532 specify attributes to be returned for new messages. These attributes
533 SHOULD be combined into a single FETCH response. The server SHOULD
534 avoid sending duplicate data. The FETCH response(s) MUST follow any
535 ESEARCH ADDTO responses.
536
537 If the new/appended message is in another mailbox, the server sends
538 an unsolicited STATUS (UIDNEXT MESSAGES) response for the relevant
539 mailbox. If the CONDSTORE extension [RFC4551] and/or the QRESYNC
540 extension [RFC5162] is enabled, the HIGHESTMODSEQ status data item
541 MUST be included in the STATUS response.
542
543 The client SHOULD NOT use FETCH attributes that implicitly set the
544 \seen flag, or that presuppose the existence of a given bodypart.
545 UID, MODSEQ, FLAGS, ENVELOPE, BODY.PEEK[HEADER.FIELDS... and
546 BODY/BODYSTRUCTURE may be the most useful attributes.
547
548 Note that if a client asks to be notified of MessageNew events with
549 the SELECTED mailbox specifier, the number of messages can increase
550 at any time, and therefore the client cannot refer to a specific
551 message using the MSN/UID '*'.
552
553 Example in the selected mailbox:
554 S: * 444 EXISTS
555 S: * 444 FETCH (UID 9999)
556
557 And in another mailbox, without CONDSTORE enabled:
558 S: * STATUS Lists/Lemonade (UIDNEXT 10002 MESSAGES 503)
559
560
561
562Gulbrandsen, et al. Standards Track [Page 10]
563
564RFC 5465 IMAP NOTIFY Extension February 2009
565
566
5675.3. MessageExpunge
568
569 If the expunged message or messages are in the selected mailbox, the
570 server notifies the client using EXPUNGE (or VANISHED, if [RFC5162]
571 is supported by the server and enabled by the client).
572
573 If a search context is in effect, as specified in [RFC5267], an
574 ESEARCH REMOVEFROM will also be generated, if appropriate.
575
576 If the expunged message or messages are in another mailbox, the
577 server sends an unsolicited STATUS (UIDNEXT MESSAGES) response for
578 the relevant mailbox. If the QRESYNC [RFC5162] extension is enabled,
579 the HIGHESTMODSEQ data item MUST be included in the STATUS response
580 as well.
581
582 Note that if a client requests MessageExpunge with the SELECTED
583 mailbox specifier, the meaning of an MSN can change at any time, so
584 the client cannot use MSNs in commands anymore. For example, such a
585 client cannot use FETCH, but has to use UID FETCH. The meaning of
586 '*' can also change when messages are added or expunged. A client
587 wishing to keep using MSNs can either use the SELECTED-DELAYED
588 mailbox specifier or can avoid using the MessageExpunge event
589 entirely.
590
591 The MessageExpunge notification covers both MessageExpunge and
592 MessageExpire events from [RFC5423].
593
594 Example in the selected mailbox, without QRESYNC:
595 S: * 444 EXPUNGE
596
597 The same example in the selected mailbox, with QRESYNC:
598 S: * VANISHED 5444
599
600 And in another mailbox, when QRESYNC is not enabled:
601 S: * STATUS misc (UIDNEXT 999 MESSAGES 554)
602
6035.4. MailboxName
604
605 These notifications are sent if an affected mailbox name was created
606 (with CREATE), deleted (with DELETE), or renamed (with RENAME). For
607 a server that implements [RFC4314], granting or revocation of the 'l'
608 right to the current user on the affected mailbox MUST be considered
609 mailbox creation or deletion, respectively. If a mailbox is created
610 or deleted, the mailbox itself and its direct parent (whether it is
611 an existing mailbox or not) are considered to be affected.
612
613
614
615
616
617
618Gulbrandsen, et al. Standards Track [Page 11]
619
620RFC 5465 IMAP NOTIFY Extension February 2009
621
622
623 The server notifies the client by sending an unsolicited LIST
624 response for each affected mailbox name. If, after the event, the
625 mailbox name does not refer to a mailbox accessible to the client,
626 the \Nonexistent flag MUST be included.
627
628 For each LISTable mailbox renamed, the server sends an extended LIST 9051:2726 ../imapserver/server.go:1327 ../imapserver/server.go:2262
629 response [RFC5258] for the new mailbox name, containing the OLDNAME
630 extended data item with the old mailbox name. When a mailbox is
631 renamed, its children are renamed too. No additional MailboxName
632 events are sent for children in this case. When INBOX is renamed, a
633 new INBOX is assumed to be created. No MailboxName event is sent for
634 INBOX in this case.
635
636 If the server automatically subscribes a mailbox when it is created
637 or renamed, then the unsolicited LIST response for each affected
638 subscribed mailbox name MUST include the \Subscribed attribute (see
639 [RFC5258]). The server SHOULD also include \HasChildren or
640 \HasNoChildren attributes [RFC5258] as appropriate.
641
642 Example of a newly created mailbox (or granting of the 'l' right on
643 the mailbox):
644 S: * LIST () "/" "NewMailbox"
645
646 And a deleted mailbox (or revocation of the 'l' right on the
647 mailbox):
648 S: * LIST (\NonExistent) "." "INBOX.DeletedMailbox"
649
650 Example of a renamed mailbox:
651 S: * LIST () "/" "NewMailbox" ("OLDNAME" ("OldMailbox"))
652
6535.5. SubscriptionChange
654
655 The server notifies the client by sending an unsolicited LIST
656 response for each affected mailbox name. If and only if the mailbox
657 is subscribed after the event, the \Subscribed attribute (see
658 [RFC5258]) is included. Note that in the LIST response, all mailbox
659 attributes MUST be accurately computed (this differs from the
660 behavior of the LSUB command).
661
662 Example:
663 S: * LIST (\Subscribed) "/" "SubscribedMailbox"
664
6655.6. MailboxMetadataChange
666
667 Support for this event type is OPTIONAL unless the METADATA extension
668 [RFC5464] is also supported by the server, in which case support for
669 this event type is REQUIRED.
670
671
672
673
674Gulbrandsen, et al. Standards Track [Page 12]
675
676RFC 5465 IMAP NOTIFY Extension February 2009
677
678
679 A client willing to receive unsolicited METADATA responses as a
680 result of using the MailboxMetadataChange event in the NOTIFY command
681 doesn't have to issue ENABLE METADATA.
682
683 The server sends an unsolicited METADATA response (as per Section
684 4.4.2 of [RFC5464]). If possible, only the changed metadata SHOULD
685 be included, but if the server can't detect a change to a single
686 metadata item, it MAY include all metadata items set on the mailbox.
687 If a metadata item is deleted (set to NIL), it MUST always be
688 included in the METADATA response.
689
690 Example:
691 S: * METADATA "INBOX" /shared/comment
692
6935.7. ServerMetadataChange
694
695 Support for this event type is OPTIONAL unless the METADATA or the
696 METADATA-SERVER extension [RFC5464] is also supported by the server,
697 in which case support for this event type is REQUIRED.
698
699 A client willing to receive unsolicited METADATA responses as a
700 result of using the ServerMetadataChange event in the NOTIFY command
701 doesn't have to issue ENABLE METADATA or ENABLE METADATA-SERVER.
702
703 The server sends an unsolicited METADATA response (as per Section
704 4.4.2 of [RFC5464]). Only the names of changed metadata entries
705 SHOULD be returned in such METADATA responses. If a metadata item is
706 deleted (set to NIL), it MUST always be included in the METADATA
707 response.
708
709 Example:
710 S: * METADATA "" /shared/comment
711
7125.8. Notification Overflow
713
714 If the server is unable or unwilling to deliver as many notifications
715 as it is being asked to, it may disable notifications for some or all
716 clients. It MUST notify these clients by sending an untagged "OK
717 [NOTIFICATIONOVERFLOW]" response and behave as if a NOTIFY NONE
718 command had just been received.
719
720 Example:
721 S: * OK [NOTIFICATIONOVERFLOW] ...A comment can go here...
722
723
724
725
726
727
728
729
730Gulbrandsen, et al. Standards Track [Page 13]
731
732RFC 5465 IMAP NOTIFY Extension February 2009
733
734
7355.9. ACL (Access Control List) Changes
736
737 Even if NOTIFY succeeds, it is still possible to lose access to the
738 mailboxes being monitored at a later time. If this happens, the
739 server MUST stop monitoring these mailboxes. If access is later
740 granted, the server MUST restart event monitoring.
741
742 The server SHOULD return the LIST response with the \NoAccess name
743 attribute if and when the mailbox loses the 'l' right. Similarly,
744 the server SHOULD return the LIST response with no \NoAccess name
745 attribute if the mailbox was previously reported as having \NoAccess
746 and the 'l' right is later granted.
747
7486. Mailbox Specification
749
750 Mailboxes to be monitored can be specified in several different ways.
751
752 Only 'SELECTED' and 'SELECTED-DELAYED' (Section 6.1) match the
753 currently selected mailbox. All other mailbox specifications affect
754 other (non-selected) mailboxes.
755
756 Note that multiple <event-group>s can apply to the same mailbox. The
757 following example demonstrates this. In this example, MessageNew and
758 MessageExpunge events are reported for INBOX, due to the first
759 <event-group>. A SubscriptionChange event will also be reported for
760 INBOX, due to the second <event-group>.
761
762 C: a notify set (mailboxes INBOX (Messagenew messageExpunge))
763 (personal (SubscriptionChange))
764
765 A typical client that supports the NOTIFY extension would ask for
766 events on the selected mailbox and some named mailboxes.
767
768 In the next example, the client asks for FlagChange events for all
769 personal mailboxes except the currently selected mailbox. This is
770 different from the previous example because SELECTED overrides all
771 other message event definitions for the currently selected mailbox
772 (see Section 3.1).
773
774 C: a notify set (selected (Messagenew (uid flags) messageExpunge))
775 (personal (MessageNew FlagChange MessageExpunge))
776
7776.1. Mailbox Specifiers Affecting the Currently Selected Mailbox
778
779 Only one of the mailbox specifiers affecting the currently selected
780 mailbox can be specified in any NOTIFY command. The two such mailbox
781 specifiers (SELECTED and SELECTED-DELAYED) are described below.
782
783
784
785
786Gulbrandsen, et al. Standards Track [Page 14]
787
788RFC 5465 IMAP NOTIFY Extension February 2009
789
790
791 Both refer to the mailbox that was selected using either SELECT or
792 EXAMINE (see [RFC3501], Sections 6.3.1 and 6.3.2). When the IMAP
793 connection is not in the selected state, such mailbox specifiers
794 don't refer to any mailbox.
795
796 The mailbox specifiers only apply to <message-event>s. It is an
797 error to specify other types of events with either the SELECTED or
798 the SELECTED-DELAYED selector.
799
8006.1.1. Selected
801
802 The SELECTED mailbox specifier requires the server to send immediate
803 notifications for the currently selected mailbox about all specified
804 <message-event>s.
805
8066.1.2. Selected-Delayed
807
808 The SELECTED-DELAYED mailbox specifier requires the server to delay a
809 MessageExpunge event until the client issues a command that allows
810 returning information about expunged messages (see Section 7.4.1 of
811 [RFC3501] for more details), for example, till a NOOP or an IDLE
812 command has been issued. When SELECTED-DELAYED is specified, the
813 server MAY also delay returning other <message-event>s until the
814 client issues one of the commands specified above, or it MAY return
815 them immediately.
816
8176.2. Personal
818
819 Personal refers to all selectable mailboxes in the user's personal
820 namespace(s), as defined in [RFC2342].
821
8226.3. Inboxes
823
824 Inboxes refers to all selectable mailboxes in the user's personal
825 namespace(s) to which messages may be delivered by a Message Delivery
826 Agent (MDA) (see [EMAIL-ARCH], particularly Section 4.3.3).
827
828 If the IMAP server cannot easily compute this set, it MUST treat
829 "inboxes" as equivalent to "personal".
830
8316.4. Subscribed
832
833 Subscribed refers to all mailboxes subscribed to by the user.
834
835 If the subscription list changes, the server MUST reevaluate the
836 list.
837
838
839
840
841
842Gulbrandsen, et al. Standards Track [Page 15]
843
844RFC 5465 IMAP NOTIFY Extension February 2009
845
846
8476.5. Subtree
848
849 Subtree is followed by a mailbox name or list of mailbox names. A
850 subtree refers to all selectable mailboxes that are subordinate to
851 the specified mailbox plus the specified mailbox itself.
852
8536.6. Mailboxes
854
855 Mailboxes is followed by a mailbox name or a list of mailbox names.
856 The server MUST NOT do a wildcard expansion. This means there is no
857 special treatment for the LIST wildcard characters ('*' and '%') if
858 they are present in mailbox names.
859
8607. Extension to SEARCH and SORT Commands
861
862 If the server that supports the NOTIFY extension also supports
863 CONTEXT=SEARCH and/or CONTEXT=SORT as defined in [RFC5267], the
864 UPDATE return option is extended so that a client can request that
865 FETCH attributes be returned when a new message is added to the
866 context result set.
867
868 For example:
869
870 C: a00 SEARCH RETURN (COUNT UPDATE (UID BODY[HEADER.FIELDS (TO
871 FROM SUBJECT)])) FROM "boss"
872 S: * ESEARCH (TAG "a00") (COUNT 17)
873 S: a00 OK
874 [...a new message is delivered...]
875 S: * EXISTS 93
876 S: * 93 FETCH (UID 127001 BODY[HEADER.FIELDS (FROM TO SUBJECT)]
877 {76}
878 S: Subject: Re: good morning
879 S: From: myboss@example.org
880 S: To: bob@example.org
881 S:
882 S: )
883 S: * ESEARCH (TAG "a00") ADDTO (0 93)
884
885 Note that the EXISTS response MUST precede any FETCH responses, and
886 together they MUST precede the ESEARCH response.
887
888 No untagged FETCH response SHOULD be returned if a message becomes a
889 member of UPDATE SEARCH due to flag or annotation changes.
890
891
892
893
894
895
896
897
898Gulbrandsen, et al. Standards Track [Page 16]
899
900RFC 5465 IMAP NOTIFY Extension February 2009
901
902
9038. Formal Syntax
904
905 The following syntax specification uses the Augmented Backus-Naur
906 Form (ABNF) notation as specified in [RFC5234]. [RFC3501] defines
907 the non-terminals "capability", "command-auth", "mailbox", "mailbox-
908 data", "resp-text-code", and "search-key". The "modifier-update"
909 non-terminal is defined in [RFC5267]. "mbx-list-oflag" is defined in
910 [RFC3501] and updated by [RFC5258].
911
912 Except as noted otherwise, all alphabetic characters are case-
913 insensitive. The use of upper or lower case characters to define
914 token strings is for editorial clarity only. Implementations MUST
915 accept these strings in a case-insensitive fashion. For example, the
916 <filter-mailboxes-selected> non-terminal value "SELECTED" must be
917 treated in the same way as "Selected" or "selected".
918
919 capability =/ "NOTIFY"
920
921 command-auth =/ notify
922
923 notify = "NOTIFY" SP
924 (notify-set / notify-none)
925
926 notify-set = "SET" [status-indicator] SP event-groups
927 ; Replace registered notification events
928 ; with the specified list of events
929
930 notify-none = "NONE"
931 ; Cancel all registered notification
932 ; events. The client is not interested
933 ; in receiving any events.
934
935 status-indicator = SP "STATUS"
936
937 one-or-more-mailbox = mailbox / many-mailboxes
938
939 many-mailboxes = "(" mailbox *(SP mailbox) ")"
940
941 event-groups = event-group *(SP event-group)
942
943 event-group = "(" filter-mailboxes SP events ")"
944 ;; Only <message-event>s are allowed in <events>
945 ;; when <filter-mailboxes-selected> is used.
946
947 filter-mailboxes = filter-mailboxes-selected /
948 filter-mailboxes-other
949
950
951
952
953
954Gulbrandsen, et al. Standards Track [Page 17]
955
956RFC 5465 IMAP NOTIFY Extension February 2009
957
958
959 filter-mailboxes-other = "inboxes" / "personal" / "subscribed" /
960 ( "subtree" SP one-or-more-mailbox ) /
961 ( "mailboxes" SP one-or-more-mailbox )
962
963 filter-mailboxes-selected = "selected" / "selected-delayed"
964 ;; Apply to the currently selected mailbox only.
965 ;; Only one of them can be specified in a NOTIFY
966 ;; command.
967
968 events = ( "(" event *(SP event) ")" ) / "NONE"
969 ;; As in [MSGEVENT].
970 ;; "NONE" means that the client does not wish
971 ;; to receive any events for the specified
972 ;; mailboxes.
973
974 event = message-event /
975 mailbox-event / user-event / event-ext
976
977 message-event = ( "MessageNew" [SP
978 "(" fetch-att *(SP fetch-att) ")" ] )
979 / "MessageExpunge"
980 / "FlagChange"
981 / "AnnotationChange"
982 ;; "MessageNew" includes "MessageAppend" from
983 ;; [MSGEVENT]. "FlagChange" is any of
984 ;; "MessageRead", "MessageTrash", "FlagsSet",
985 ;; "FlagsClear" [MSGEVENT]. "MessageExpunge"
986 ;; includes "MessageExpire" [MSGEVENT].
987 ;; MessageNew and MessageExpunge MUST always
988 ;; be specified together. If FlagChange is
989 ;; specified, then MessageNew and MessageExpunge
990 ;; MUST be specified as well.
991 ;; The fett-att list may only be present for the
992 ;; SELECTED/SELECTED-DELAYED mailbox filter
993 ;; (<filter-mailboxes>).
994
995 mailbox-event = "MailboxName" /
996 "SubscriptionChange" / "MailboxMetadataChange"
997 ; "SubscriptionChange" includes
998 ; MailboxSubscribe and MailboxUnSubscribe.
999 ; "MailboxName" includes MailboxCreate,
1000 ; "MailboxDelete" and "MailboxRename".
1001
1002 user-event = "ServerMetadataChange"
1003
1004 event-ext = atom
1005 ;; For future extensions
1006
1007
1008
1009
1010Gulbrandsen, et al. Standards Track [Page 18]
1011
1012RFC 5465 IMAP NOTIFY Extension February 2009
1013
1014
1015 oldname-extended-item = "OLDNAME" SP "(" mailbox ")"
1016 ;; Extended data item (mbox-list-extended-item)
1017 ;; returned in a LIST response when a mailbox is
1018 ;; renamed.
1019 ;; Note 1: the OLDNAME tag can be returned
1020 ;; with or without surrounding quotes, as per
1021 ;; mbox-list-extended-item-tag production.
1022
1023 resp-text-code =/ "NOTIFICATIONOVERFLOW" /
1024 unsupported-events-code
1025
1026 message-event-name = "MessageNew" /
1027 "MessageExpunge" / "FlagChange" /
1028 "AnnotationChange"
1029
1030 event-name = message-event-name / mailbox-event /
1031 user-event
1032
1033 unsupported-events-code = "BADEVENT"
1034 SP "(" event-name *(SP event-name) ")"
1035
1036 modifier-update = "UPDATE"
1037 [ "(" fetch-att *(SP fetch-att) ")" ]
1038
1039 mbx-list-oflag =/ "\NoAccess"
1040
10419. Security Considerations
1042
1043 It is very easy for a client to deny itself service using NOTIFY.
1044 Asking for all events on all mailboxes may work on a small server,
1045 but with a big server, can swamp the client's network connection or
1046 processing capability. In the worst case, the server's processing
1047 could also degrade the service it offers to other clients.
1048
1049 Server authors should be aware that if a client issues requests and
1050 does not listen to the resulting responses, the TCP window can easily
1051 fill up, and a careless server might block. This problem also exists
1052 in plain IMAP; however, this extension magnifies the problem.
1053
1054 This extension makes it possible to retrieve messages immediately
1055 when they are added to the mailbox. This makes it wholly impractical
1056 to delete sensitive messages using programs like imapfilter. Using
1057 SIEVE [RFC5228] or similar is much better.
1058
1059
1060
1061
1062
1063
1064
1065
1066Gulbrandsen, et al. Standards Track [Page 19]
1067
1068RFC 5465 IMAP NOTIFY Extension February 2009
1069
1070
107110. IANA Considerations
1072
1073 The IANA has added NOTIFY to the list of IMAP extensions.
1074
107510.1. Initial LIST-EXTENDED Extended Data Item Registrations
1076
1077 The following entry has been added to the LIST-EXTENDED response
1078 registry [RFC5258]:
1079
1080 To: iana@iana.org
1081 Subject: Registration of OLDNAME LIST-EXTENDED extended data item
1082
1083 LIST-EXTENDED extended data item tag: OLDNAME
1084
1085 LIST-EXTENDED extended data item description: The OLDNAME extended
1086 data item describes the old mailbox name for the mailbox
1087 identified by the LIST response.
1088
1089 Which LIST-EXTENDED option(s) (and their types) causes this extended
1090 data item to be returned (if any): none
1091
1092 Published specification : RFC 5465, Section 5.4.
1093
1094 Security considerations: none
1095
1096 Intended usage: COMMON
1097
1098 Person and email address to contact for further information: Alexey
1099 Melnikov <Alexey.Melnikov@isode.com>
1100
1101 Owner/Change controller: iesg@ietf.org
1102
110311. Acknowledgments
1104
1105 The authors gratefully acknowledge the help of Peter Coates, Dave
1106 Cridland, Mark Crispin, Cyrus Daboo, Abhijit Menon-Sen, Timo
1107 Sirainen, and Eric Burger. In particular, Peter Coates contributed
1108 lots of text and useful suggestions to this document.
1109
1110 Various examples are copied from other RFCs.
1111
1112 This document builds on one published and two unpublished drafts by
1113 the same authors.
1114
1115
1116
1117
1118
1119
1120
1121
1122Gulbrandsen, et al. Standards Track [Page 20]
1123
1124RFC 5465 IMAP NOTIFY Extension February 2009
1125
1126
112712. Normative References
1128
1129 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1130 Requirement Levels", BCP 14, RFC 2119, March 1997.
1131
1132 [RFC2177] Leiba, B., "IMAP4 IDLE command", RFC 2177, June 1997.
1133
1134 [RFC2342] Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342,
1135 May 1998.
1136
1137 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
1138 4rev1", RFC 3501, March 2003.
1139
1140 [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL)
1141 Extension", RFC 4314, December 2005.
1142
1143 [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to
1144 IMAP4 ABNF", RFC 4466, April 2006.
1145
1146 [RFC4551] Melnikov, A. and S. Hole, "IMAP Extension for
1147 Conditional STORE Operation or Quick Flag Changes
1148 Resynchronization", RFC 4551, June 2006.
1149
1150 [RFC5162] Melnikov, A., Cridland, D., and C. Wilson, "IMAP4
1151 Extensions for Quick Mailbox Resynchronization", RFC
1152 5162, March 2008.
1153
1154 [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for
1155 Syntax Specifications: ABNF", STD 68, RFC 5234, January
1156 2008.
1157
1158 [RFC5258] Leiba, B. and A. Melnikov, "Internet Message Access
1159 Protocol version 4 - LIST Command Extensions", RFC 5258,
1160 June 2008.
1161
1162 [RFC5267] Cridland, D. and C. King, "Contexts for IMAP4", RFC
1163 5267, July 2008.
1164
1165 [RFC5423] Newman, C. and R. Gellens, "Internet Message Store
1166 Events", RFC 5423, Month 2009.
1167
1168 [RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464,
1169 February 2009.
1170
117113. Informative References
1172
1173 [RFC5228] Guenther, P., Ed., and T. Showalter, Ed., "Sieve: An
1174 Email Filtering Language", RFC 5228, January 2008.
1175
1176
1177
1178Gulbrandsen, et al. Standards Track [Page 21]
1179
1180RFC 5465 IMAP NOTIFY Extension February 2009
1181
1182
1183 [EMAIL-ARCH] Crocker, D., "Internet Mail Architecture", Work in
1184 Progress, October 2008.
1185
1186Authors' Addresses
1187
1188 Arnt Gulbrandsen
1189 Oryx Mail Systems GmbH
1190 Schweppermannstr. 8
1191 D-81671 Muenchen
1192 Germany
1193
1194 EMail: arnt@oryx.com
1195
1196
1197 Curtis King
1198 Isode Ltd
1199 5 Castle Business Village
1200 36 Station Road
1201 Hampton, Middlesex TW12 2BX
1202 UK
1203
1204 EMail: Curtis.King@isode.com
1205
1206
1207 Alexey Melnikov
1208 Isode Ltd
1209 5 Castle Business Village
1210 36 Station Road
1211 Hampton, Middlesex TW12 2BX
1212 UK
1213
1214 EMail: Alexey.Melnikov@isode.com
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234Gulbrandsen, et al. Standards Track [Page 22]
1235
1236