summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc5465.txt
blob: 3fe5bcfb51f3efea2fca9bf5069f42764ce187d1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
Network Working Group                                     A. Gulbrandsen
Request for Comments: 5465                        Oryx Mail Systems GmbH
Updates: 5267                                                    C. King
Category: Standards Track                                    A. Melnikov
                                                              Isode Ltd.
                                                           February 2009


                       The IMAP NOTIFY Extension

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (c) 2009 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (http://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.

Abstract

   This document defines an IMAP extension that allows a client to
   request specific kinds of unsolicited notifications for specified
   mailboxes, such as messages being added to or deleted from such
   mailboxes.
















Gulbrandsen, et al.         Standards Track                     [Page 1]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


Table of Contents

   1. Overview and Rationale ..........................................3
   2. Conventions Used in This Document ...............................4
   3. The NOTIFY Extension ............................................4
      3.1. The NOTIFY Command .........................................4
   4. Interaction with the IDLE Command ...............................8
   5. Event Types .....................................................8
      5.1. FlagChange and AnnotationChange ............................9
      5.2. MessageNew .................................................9
      5.3. MessageExpunge ............................................10
      5.4. MailboxName ...............................................11
      5.5. SubscriptionChange ........................................12
      5.6. MailboxMetadataChange .....................................12
      5.7. ServerMetadataChange ......................................13
      5.8. Notification Overflow .....................................13
      5.9. ACL (Access Control List) Changes .........................13
   6. Mailbox Specification ..........................................14
      6.1. Mailbox Specifiers Affecting the Currently
           Selected Mailbox ..........................................14
      6.2. Personal ..................................................15
      6.3. Inboxes ...................................................15
      6.4. Subscribed ................................................15
      6.5. Subtree ...................................................15
      6.6. Mailboxes .................................................16
   7. Extension to SEARCH and SORT Commands ..........................16
   8. Formal Syntax ..................................................16
   9. Security Considerations ........................................19
   10. IANA Considerations ...........................................19
      10.1. Initial LIST-EXTENDED Extended Data Item Registrations ...19
   11. Acknowledgements ..............................................20
   12. Normative References ..........................................20
   13. Informative References ........................................21


















Gulbrandsen, et al.         Standards Track                     [Page 2]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


1.  Overview and Rationale

   The IDLE command (defined in [RFC2177]) provides a way for the client
   to go into a mode where the IMAP server pushes it notifications about
   IMAP mailstore events for the selected mailbox.  However, the IDLE
   extension doesn't restrict or control which server events can be
   sent, or what information the server sends in response to each event.
   Also, IDLE only applies to the selected mailbox, thus requiring an
   additional TCP connection per mailbox.

   This document defines an IMAP extension that allows clients to
   express their preferences about unsolicited events generated by the
   server.  The extension allows clients to only receive events that
   they are interested in, while servers know that they don't need to go
   to the effort of generating certain types of untagged responses.

   Without the NOTIFY command defined in this document, an IMAP server
   will only send information about mailstore changes to the client in
   the following cases:

   -  as the result of a client command (e.g., FETCH responses to a
      FETCH or STORE command),
   -  as unsolicited responses sent just before the end of a command
      (e.g., EXISTS or EXPUNGE) as the result of changes in other
      sessions, and
   -  during an IDLE command.

   The NOTIFY command extends what information may be returned in those
   last two cases, and also permits and requires the server to send
   information about updates between commands.  The NOTIFY command also
   allows for the client to extend what information is sent unsolicited
   about the selected mailbox and to request some update information to
   be sent regarding other mailboxes.

   The interaction between IDLE and NOTIFY commands is described in
   Section 4.

   For the new messages delivered to or appended to the selected
   mailbox, the NOTIFY command can be used to request that a set of
   attributes be sent to the client in an unsolicited FETCH response.
   This allows a client to be a passive recipient of events and new mail
   and to be able to maintain full synchronisation without having to
   issue any subsequent commands except to modify the state of the
   mailbox on the server.







Gulbrandsen, et al.         Standards Track                     [Page 3]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


   Some mobile clients, however, may want mail "pushed" only for mail
   that matches a SEARCH pattern.  To meet that need, [RFC5267] is
   augmented by this document to extend the UPDATE return option to
   specify a list of fetch-atts to be returned when a new message is
   delivered or appended in another session.

2.  Conventions Used in This Document

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

   The acronym MSN stands for Message Sequence Numbers (see Section
   2.3.1.2 of [RFC3501]).

   Example lines prefaced by "C:" are sent by the client and ones
   prefaced by "S:", by the server.  "[...]" means elision.

3.  The NOTIFY Extension

   IMAP servers that support this extension advertise the NOTIFY
   capability.  This extension adds the NOTIFY command as defined in
   Section 5.1.

   A server implementing this extension is not required to implement
   LIST-EXTENDED [RFC5258], even though a NOTIFY-compliant server must
   be able to return extended LIST responses, defined in [RFC5258].

3.1.  The NOTIFY Command

   Arguments:  "SET"
               Optional STATUS indicator
               Mailboxes to be watched
               Events about which to notify the client

   Or
   Arguments:  "NONE"

   Responses:  Possibly untagged STATUS responses (for SET)

   Result:     OK - The server will notify the client as requested.
               NO -  Unsupported NOTIFY event, NOTIFY too complex or
                     expensive, etc.
               BAD - Command unknown, invalid, unsupported, or has
                     unknown arguments.






Gulbrandsen, et al.         Standards Track                     [Page 4]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


   The NOTIFY command informs the server that the client listens for
   event notifications all the time (even when no command is in
   progress), and requests the server to notify it about the specified
   set of events.  The NOTIFY command has two forms.  NOTIFY NONE
   specifies that the client is not interested in any kind of event
   happening on the server.  NOTIFY SET replaces the current list of
   interesting events with a new list of events.

   Until the NOTIFY command is used for the first time, the server only
   sends notifications while a command is being processed, and notifies
   the client about these events on the selected mailbox (see Section 5
   for definitions): MessageNew, MessageExpunge, or FlagChange.  It does
   not notify the client about any events on other mailboxes.

   The effect of a successful NOTIFY command lasts until the next NOTIFY
   command or until the IMAP connection is closed.

   A successful NOTIFY SET command MUST cause the server to immediately
   return any accumulated changes to the currently selected mailbox (if
   any), such as flag changes and new or expunged messages.  Thus, a
   successful NOTIFY SET command implies an implicit NOOP command.

   The NOTIFY SET command can request notifications of message-related
   changes to the selected mailbox, whatever that may be at the time the
   message notifications are being generated.  This is done by
   specifying either the SELECTED or the SELECTED-DELAYED mailbox
   selector (see Section 6.1) in the NOTIFY SET command.  If the
   SELECTED/SELECTED-DELAYED mailbox selector is not specified in the
   NOTIFY SET command, this means that the client doesn't want to
   receive any <message-event>s for the currently selected mailbox.
   This is the same as specifying SELECTED NONE.

   The client can also request notifications on other mailboxes by name
   or by a limited mailbox pattern match.  Message-related notifications
   returned for the currently selected mailbox will be those specified
   by the SELECTED/SELECTED-DELAYED mailbox specifier, even if the
   selected mailbox also appears by name (or matches a pattern) in the
   command.  Non-message-related notifications are controlled by mailbox
   specifiers other than SELECTED/SELECTED-DELAYED.

   If the NOTIFY command enables MessageNew, MessageExpunge,
   AnnotationChange, or FlagChange notifications for a mailbox other
   than the currently selected mailbox, and the client has specified the
   STATUS indicator parameter, then the server MUST send a STATUS
   response for that mailbox before NOTIFY's tagged OK.  If MessageNew
   is enabled, the STATUS response MUST contain MESSAGES, UIDNEXT, and
   UIDVALIDITY.  If MessageExpunge is enabled, the STATUS response MUST
   contain MESSAGES.  If either AnnotationChange or FlagChange are



Gulbrandsen, et al.         Standards Track                     [Page 5]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


   included and the server also supports the CONDSTORE [RFC4551] and/or
   QRESYNC [RFC5162] extensions, the STATUS response MUST contain
   UIDVALIDITY and HIGHESTMODSEQ.  Absence of the STATUS indicator
   parameter allows the client to avoid the additional STATUS responses.
   This might be useful if the client already retrieved this information
   before issuing the NOTIFY command.

   Clients are advised to limit the number of mailboxes used with
   NOTIFY.  Particularly, if a client asks for events for all accessible
   mailboxes, the server may swamp the client with updates about shared
   mailboxes.  This may reduce the client's battery life.  Also, this
   wastes both server and network resources.

   For each mailbox specified, the server verifies that the client has
   access using the following test:

   -  If the name does not refer to an existing mailbox, the server MUST
      ignore it.

   -  If the name refers to a mailbox that the client can't LIST, the
      server MUST ignore it.  For a server that implements [RFC4314],
      this means that if the client doesn't have the 'l' (lookup) right
      for the name, then the server MUST ignore the mailbox.  This
      behavior prevents disclosure of potentially confidential
      information to clients who don't have rights to know it.

   -  If the name refers to a mailbox that the client can LIST (e.g., it
      has the 'l' right from [RFC4314]), but the client doesn't have
      another right required for processing of the specified event(s),
      then the server MUST respond with an untagged extended LIST
      response containing the \NoAccess name attribute.

   The server SHOULD return the tagged OK response if the client has
   access to at least one of the mailboxes specified in the current list
   of interesting events.  The server MAY return the tagged NO response
   if the client has no access to any of the specified mailboxes and no
   access can ever be granted in the future (e.g., the client specified
   an event for 'Subtree Bar/Foo', 'Bar/Foo' doesn't exist, and LIST
   returns \Noinferiors for the parent 'Bar').

   If the notification would be prohibitively expensive for the server
   (e.g., "notify me of all flag changes in all mailboxes"), the server
   MAY refuse the command with a tagged NO [NOTIFICATIONOVERFLOW]
   response.







Gulbrandsen, et al.         Standards Track                     [Page 6]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


   If the client requests information for events of an unsupported type,
   the server MUST refuse the command with a tagged NO response (not a
   BAD).  This response SHOULD contain the BADEVENT response code, which
   MUST list names of all events supported by the server.

   Here's an example:

         S: * OK [CAPABILITY IMAP4REV1 NOTIFY]
         C: a login bob alice
         S: a OK Password matched
         C: b notify set status (selected MessageNew (uid
            body.peek[header.fields (from to subject)]) MessageExpunge)
            (subtree Lists MessageNew)
         S: * STATUS Lists/Lemonade (UIDVALIDITY 4 UIDNEXT 9999 MESSAGES
            500)
         S: [...]
         S: * STATUS Lists/Im2000 (UIDVALIDITY 901 UIDNEXT 1 MESSAGES 0)
         S: b OK done
         C: c select inbox
         S: [...] (the usual 7-8 responses to SELECT)
         S: c OK INBOX selected
               (Time passes.  A new message is delivered to mailbox
               Lists/Lemonade.)
         S: * STATUS Lists/Lemonade (UIDVALIDITY 4 UIDNEXT 10000
            MESSAGES 501)
               (Time passes.  A new message is delivered to inbox.)
         S: * 127 FETCH (UID 127001 BODY[HEADER.FIELDS (From To
            Subject)] {75}
         S: Subject: Re: good morning
         S: From: alice@example.org
         S: To: bob@example.org
         S:
         S: )
               (Time passes.  The client decides it wants to know about
               one more mailbox.  As the client already knows necessary
               STATUS information for all mailboxes below the Lists
               mailbox, and because "notify set status" would cause
               STATUS responses for *all* mailboxes specified in the
               NOTIFY command, including the ones for which the client
               already knows STATUS information, the client issues an
               explicit STATUS request for the mailbox to be added to
               the watch list, followed by the NOTIFY SET without the
               STATUS parameter.)
         C: d STATUS misc (UIDVALIDITY UIDNEXT MESSAGES)
         S: * STATUS misc (UIDVALIDITY 1 UIDNEXT 999)
         S: d STATUS completed





Gulbrandsen, et al.         Standards Track                     [Page 7]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


         C: e notify set (selected MessageNew (uid
            body.peek[header.fields (from to subject)]) MessageExpunge)
            (subtree Lists MessageNew) (mailboxes misc MessageNew)
         S: e OK done

4.  Interaction with the IDLE Command

   If IDLE [RFC2177] (as well as this extension) is supported, then
   while processing any IDLE command, the server MUST send exactly the
   same events as instructed by the client using the NOTIFY command.

   NOTIFY makes IDLE unnecessary for some clients.  If a client does not
   use MSNs and '*' in commands, it can request MessageExpunge and
   MessageNew for the selected mailbox by using the NOTIFY command
   instead of entering the IDLE mode.

   A client that uses MSNs and '*' in commands can still use the NOTIFY
   command if it specifies the SELECTED-DELAYED mailbox specifier in the
   NOTIFY command.

5.  Event Types

   Only some of the events in [RFC5423] can be expressed in IMAP, and
   for some of them there are several possible ways to express the
   event.

   This section specifies the events of which an IMAP server can notify
   an IMAP client, and how.

   The server SHOULD omit notifying the client if the event is caused by
   this client.  For example, if the client issues CREATE and has
   requested a MailboxName event that would cover the newly created
   mailbox, the server SHOULD NOT notify the client of the MailboxName
   change.

   All event types described in this document require the 'l' and 'r'
   rights (see [RFC4314]) on all observed mailboxes.  Servers that don't
   implement [RFC4314] should map the above rights to their access-
   control model.

   If the FlagChange and/or AnnotationChange events are specified,
   MessageNew and MessageExpunge MUST also be specified by the client.
   Otherwise, the server MUST respond with the tagged BAD response.

   If one of MessageNew or MessageExpunge is specified, then both events
   MUST be specified.  Otherwise, the server MUST respond with the
   tagged BAD response.




Gulbrandsen, et al.         Standards Track                     [Page 8]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


   The client can instruct the server not to send an event by omitting
   the necessary event from the list of events specified in NOTIFY SET,
   by using the NONE event specifier in the NOTIFY SET, or by using
   NOTIFY NONE.  In particular, NOTIFY SET ... NONE can be used as a
   snapshot facility by clients.

5.1.  FlagChange and AnnotationChange

   If the flag and/or message annotation change happens in the selected
   mailbox, the server MUST notify the client by sending an unsolicited
   FETCH response, which MUST include UID and FLAGS/ANNOTATION FETCH
   data items.  It MAY also send new FLAGS and/or OK [PERMANENTFLAGS
   ...] responses.

   If a search context is in effect as specified in [RFC5267], an
   ESEARCH ADDTO or ESEARCH REMOVEFROM will also be generated, if
   appropriate.  In this case, the FETCH response MUST precede the
   ESEARCH response.

   If the change happens in another mailbox, then the server responds
   with a STATUS response.  The exact content of the STATUS response
   depends on various factors.  If CONDSTORE [RFC4551] and/or QRESYNC
   [RFC5162] are enabled by the client, then the server sends a STATUS
   response that includes at least HIGHESTMODSEQ and UIDVALIDITY status
   data items.  If the number of messages with the \Seen flag changes,
   the server MAY also include the UNSEEN data item in the STATUS
   response.  If CONDSTORE/QRESYNC is not enabled by the client and the
   server chooses not to include the UNSEEN data item, the server does
   not notify the client.  When this event is requested, the server MUST
   notify the client about mailbox UIDVALIDITY changes.  This is done by
   sending a STATUS response that includes UIDVALIDITY.

   FlagChange covers the MessageRead, MessageTrash, FlagsSet, and
   FlagsClear events in [RFC5423].

   Example in the selected mailbox:
      S: * 99 FETCH (UID 9999 FLAGS ($Junk))

   And in another mailbox, with CONDSTORE in use:
      S: * STATUS Lists/Lemonade (HIGHESTMODSEQ 65666665 UIDVALIDITY
      101)










Gulbrandsen, et al.         Standards Track                     [Page 9]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


5.2.  MessageNew

   This covers both MessageNew and MessageAppend in [RFC5423].

   If the new/appended message is in the selected mailbox, the server
   notifies the client by sending an unsolicited EXISTS response,
   followed by an unsolicited FETCH response containing the information
   requested by the client.  A FETCH response SHOULD NOT be generated
   for a new message created by the client on this particular
   connection, for instance, as the result of an APPEND or COPY command
   to the selected mailbox performed by the client itself.  The server
   MAY also send a RECENT response, if the server marks the message as
   \Recent.

   Note that a single EXISTS response can be returned for multiple
   MessageAppend/MessageNew events.

   If a search context is in effect as specified in [RFC5267], an
   ESEARCH ADDTO will also be generated, if appropriate.  In this case,
   the EXISTS response MUST precede the ESEARCH response.  Both the
   NOTIFY command and the SEARCH and SORT commands (see Section 7) can
   specify attributes to be returned for new messages.  These attributes
   SHOULD be combined into a single FETCH response.  The server SHOULD
   avoid sending duplicate data.  The FETCH response(s) MUST follow any
   ESEARCH ADDTO responses.

   If the new/appended message is in another mailbox, the server sends
   an unsolicited STATUS (UIDNEXT MESSAGES) response for the relevant
   mailbox.  If the CONDSTORE extension [RFC4551] and/or the QRESYNC
   extension [RFC5162] is enabled, the HIGHESTMODSEQ status data item
   MUST be included in the STATUS response.

   The client SHOULD NOT use FETCH attributes that implicitly set the
   \seen flag, or that presuppose the existence of a given bodypart.
   UID, MODSEQ, FLAGS, ENVELOPE, BODY.PEEK[HEADER.FIELDS... and
   BODY/BODYSTRUCTURE may be the most useful attributes.

   Note that if a client asks to be notified of MessageNew events with
   the SELECTED mailbox specifier, the number of messages can increase
   at any time, and therefore the client cannot refer to a specific
   message using the MSN/UID '*'.

   Example in the selected mailbox:
      S: * 444 EXISTS
      S: * 444 FETCH (UID 9999)

   And in another mailbox, without CONDSTORE enabled:
      S: * STATUS Lists/Lemonade (UIDNEXT 10002 MESSAGES 503)



Gulbrandsen, et al.         Standards Track                    [Page 10]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


5.3.  MessageExpunge

   If the expunged message or messages are in the selected mailbox, the
   server notifies the client using EXPUNGE (or VANISHED, if [RFC5162]
   is supported by the server and enabled by the client).

   If a search context is in effect, as specified in [RFC5267], an
   ESEARCH REMOVEFROM will also be generated, if appropriate.

   If the expunged message or messages are in another mailbox, the
   server sends an unsolicited STATUS (UIDNEXT MESSAGES) response for
   the relevant mailbox.  If the QRESYNC [RFC5162] extension is enabled,
   the HIGHESTMODSEQ data item MUST be included in the STATUS response
   as well.

   Note that if a client requests MessageExpunge with the SELECTED
   mailbox specifier, the meaning of an MSN can change at any time, so
   the client cannot use MSNs in commands anymore.  For example, such a
   client cannot use FETCH, but has to use UID FETCH.  The meaning of
   '*' can also change when messages are added or expunged.  A client
   wishing to keep using MSNs can either use the SELECTED-DELAYED
   mailbox specifier or can avoid using the MessageExpunge event
   entirely.

   The MessageExpunge notification covers both MessageExpunge and
   MessageExpire events from [RFC5423].

   Example in the selected mailbox, without QRESYNC:
      S: * 444 EXPUNGE

   The same example in the selected mailbox, with QRESYNC:
      S: * VANISHED 5444

   And in another mailbox, when QRESYNC is not enabled:
      S: * STATUS misc (UIDNEXT 999 MESSAGES 554)

5.4.  MailboxName

   These notifications are sent if an affected mailbox name was created
   (with CREATE), deleted (with DELETE), or renamed (with RENAME).  For
   a server that implements [RFC4314], granting or revocation of the 'l'
   right to the current user on the affected mailbox MUST be considered
   mailbox creation or deletion, respectively.  If a mailbox is created
   or deleted, the mailbox itself and its direct parent (whether it is
   an existing mailbox or not) are considered to be affected.






Gulbrandsen, et al.         Standards Track                    [Page 11]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


   The server notifies the client by sending an unsolicited LIST
   response for each affected mailbox name.  If, after the event, the
   mailbox name does not refer to a mailbox accessible to the client,
   the \Nonexistent flag MUST be included.

   For each LISTable mailbox renamed, the server sends an extended LIST
   response [RFC5258] for the new mailbox name, containing the OLDNAME
   extended data item with the old mailbox name.  When a mailbox is
   renamed, its children are renamed too.  No additional MailboxName
   events are sent for children in this case.  When INBOX is renamed, a
   new INBOX is assumed to be created.  No MailboxName event is sent for
   INBOX in this case.

   If the server automatically subscribes a mailbox when it is created
   or renamed, then the unsolicited LIST response for each affected
   subscribed mailbox name MUST include the \Subscribed attribute (see
   [RFC5258]).  The server SHOULD also include \HasChildren or
   \HasNoChildren attributes [RFC5258] as appropriate.

   Example of a newly created mailbox (or granting of the 'l' right on
   the mailbox):
      S: * LIST () "/" "NewMailbox"

   And a deleted mailbox (or revocation of the 'l' right on the
   mailbox):
      S: * LIST (\NonExistent) "." "INBOX.DeletedMailbox"

   Example of a renamed mailbox:
      S: * LIST () "/" "NewMailbox" ("OLDNAME" ("OldMailbox"))

5.5.  SubscriptionChange

   The server notifies the client by sending an unsolicited LIST
   response for each affected mailbox name.  If and only if the mailbox
   is subscribed after the event, the \Subscribed attribute (see
   [RFC5258]) is included.  Note that in the LIST response, all mailbox
   attributes MUST be accurately computed (this differs from the
   behavior of the LSUB command).

   Example:
      S: * LIST (\Subscribed) "/" "SubscribedMailbox"

5.6.  MailboxMetadataChange

   Support for this event type is OPTIONAL unless the METADATA extension
   [RFC5464] is also supported by the server, in which case support for
   this event type is REQUIRED.




Gulbrandsen, et al.         Standards Track                    [Page 12]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


   A client willing to receive unsolicited METADATA responses as a
   result of using the MailboxMetadataChange event in the NOTIFY command
   doesn't have to issue ENABLE METADATA.

   The server sends an unsolicited METADATA response (as per Section
   4.4.2 of [RFC5464]).  If possible, only the changed metadata SHOULD
   be included, but if the server can't detect a change to a single
   metadata item, it MAY include all metadata items set on the mailbox.
   If a metadata item is deleted (set to NIL), it MUST always be
   included in the METADATA response.

   Example:
      S: * METADATA "INBOX" /shared/comment

5.7.  ServerMetadataChange

   Support for this event type is OPTIONAL unless the METADATA or the
   METADATA-SERVER extension [RFC5464] is also supported by the server,
   in which case support for this event type is REQUIRED.

   A client willing to receive unsolicited METADATA responses as a
   result of using the ServerMetadataChange event in the NOTIFY command
   doesn't have to issue ENABLE METADATA or ENABLE METADATA-SERVER.

   The server sends an unsolicited METADATA response (as per Section
   4.4.2 of [RFC5464]).  Only the names of changed metadata entries
   SHOULD be returned in such METADATA responses.  If a metadata item is
   deleted (set to NIL), it MUST always be included in the METADATA
   response.

   Example:
      S: * METADATA "" /shared/comment

5.8.  Notification Overflow

   If the server is unable or unwilling to deliver as many notifications
   as it is being asked to, it may disable notifications for some or all
   clients.  It MUST notify these clients by sending an untagged "OK
   [NOTIFICATIONOVERFLOW]" response and behave as if a NOTIFY NONE
   command had just been received.

   Example:
      S: * OK [NOTIFICATIONOVERFLOW] ...A comment can go here...








Gulbrandsen, et al.         Standards Track                    [Page 13]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


5.9.  ACL (Access Control List) Changes

   Even if NOTIFY succeeds, it is still possible to lose access to the
   mailboxes being monitored at a later time.  If this happens, the
   server MUST stop monitoring these mailboxes.  If access is later
   granted, the server MUST restart event monitoring.

   The server SHOULD return the LIST response with the \NoAccess name
   attribute if and when the mailbox loses the 'l' right.  Similarly,
   the server SHOULD return the LIST response with no \NoAccess name
   attribute if the mailbox was previously reported as having \NoAccess
   and the 'l' right is later granted.

6.  Mailbox Specification

   Mailboxes to be monitored can be specified in several different ways.

   Only 'SELECTED' and 'SELECTED-DELAYED' (Section 6.1) match the
   currently selected mailbox.  All other mailbox specifications affect
   other (non-selected) mailboxes.

   Note that multiple <event-group>s can apply to the same mailbox.  The
   following example demonstrates this.  In this example, MessageNew and
   MessageExpunge events are reported for INBOX, due to the first
   <event-group>.  A SubscriptionChange event will also be reported for
   INBOX, due to the second <event-group>.

      C: a notify set (mailboxes INBOX (Messagenew messageExpunge))
         (personal (SubscriptionChange))

   A typical client that supports the NOTIFY extension would ask for
   events on the selected mailbox and some named mailboxes.

   In the next example, the client asks for FlagChange events for all
   personal mailboxes except the currently selected mailbox.  This is
   different from the previous example because SELECTED overrides all
   other message event definitions for the currently selected mailbox
   (see Section 3.1).

      C: a notify set (selected (Messagenew (uid flags) messageExpunge))
         (personal (MessageNew FlagChange MessageExpunge))

6.1.  Mailbox Specifiers Affecting the Currently Selected Mailbox

   Only one of the mailbox specifiers affecting the currently selected
   mailbox can be specified in any NOTIFY command.  The two such mailbox
   specifiers (SELECTED and SELECTED-DELAYED) are described below.




Gulbrandsen, et al.         Standards Track                    [Page 14]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


   Both refer to the mailbox that was selected using either SELECT or
   EXAMINE (see [RFC3501], Sections 6.3.1 and 6.3.2).  When the IMAP
   connection is not in the selected state, such mailbox specifiers
   don't refer to any mailbox.

   The mailbox specifiers only apply to <message-event>s.  It is an
   error to specify other types of events with either the SELECTED or
   the SELECTED-DELAYED selector.

6.1.1.  Selected

   The SELECTED mailbox specifier requires the server to send immediate
   notifications for the currently selected mailbox about all specified
   <message-event>s.

6.1.2.  Selected-Delayed

   The SELECTED-DELAYED mailbox specifier requires the server to delay a
   MessageExpunge event until the client issues a command that allows
   returning information about expunged messages (see Section 7.4.1 of
   [RFC3501] for more details), for example, till a NOOP or an IDLE
   command has been issued.  When SELECTED-DELAYED is specified, the
   server MAY also delay returning other <message-event>s until the
   client issues one of the commands specified above, or it MAY return
   them immediately.

6.2.  Personal

   Personal refers to all selectable mailboxes in the user's personal
   namespace(s), as defined in [RFC2342].

6.3.  Inboxes

   Inboxes refers to all selectable mailboxes in the user's personal
   namespace(s) to which messages may be delivered by a Message Delivery
   Agent (MDA) (see [EMAIL-ARCH], particularly Section 4.3.3).

   If the IMAP server cannot easily compute this set, it MUST treat
   "inboxes" as equivalent to "personal".

6.4.  Subscribed

   Subscribed refers to all mailboxes subscribed to by the user.

   If the subscription list changes, the server MUST reevaluate the
   list.





Gulbrandsen, et al.         Standards Track                    [Page 15]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


6.5.  Subtree

   Subtree is followed by a mailbox name or list of mailbox names.  A
   subtree refers to all selectable mailboxes that are subordinate to
   the specified mailbox plus the specified mailbox itself.

6.6.  Mailboxes

   Mailboxes is followed by a mailbox name or a list of mailbox names.
   The server MUST NOT do a wildcard expansion.  This means there is no
   special treatment for the LIST wildcard characters ('*' and '%') if
   they are present in mailbox names.

7.  Extension to SEARCH and SORT Commands

   If the server that supports the NOTIFY extension also supports
   CONTEXT=SEARCH and/or CONTEXT=SORT as defined in [RFC5267], the
   UPDATE return option is extended so that a client can request that
   FETCH attributes be returned when a new message is added to the
   context result set.

   For example:

         C: a00 SEARCH RETURN (COUNT UPDATE (UID BODY[HEADER.FIELDS (TO
            FROM SUBJECT)])) FROM "boss"
         S: * ESEARCH (TAG "a00") (COUNT 17)
         S: a00 OK
            [...a new message is delivered...]
         S: * EXISTS 93
         S: * 93 FETCH (UID 127001 BODY[HEADER.FIELDS (FROM TO SUBJECT)]
            {76}
         S: Subject: Re: good morning
         S: From: myboss@example.org
         S: To: bob@example.org
         S:
         S: )
         S: * ESEARCH (TAG "a00") ADDTO (0 93)

   Note that the EXISTS response MUST precede any FETCH responses, and
   together they MUST precede the ESEARCH response.

   No untagged FETCH response SHOULD be returned if a message becomes a
   member of UPDATE SEARCH due to flag or annotation changes.








Gulbrandsen, et al.         Standards Track                    [Page 16]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


8.  Formal Syntax

   The following syntax specification uses the Augmented Backus-Naur
   Form (ABNF) notation as specified in [RFC5234].  [RFC3501] defines
   the non-terminals "capability", "command-auth", "mailbox", "mailbox-
   data", "resp-text-code", and "search-key".  The "modifier-update"
   non-terminal is defined in [RFC5267].  "mbx-list-oflag" is defined in
   [RFC3501] and updated by [RFC5258].

   Except as noted otherwise, all alphabetic characters are case-
   insensitive.  The use of upper or lower case characters to define
   token strings is for editorial clarity only.  Implementations MUST
   accept these strings in a case-insensitive fashion.  For example, the
   <filter-mailboxes-selected> non-terminal value "SELECTED" must be
   treated in the same way as "Selected" or "selected".

      capability      =/ "NOTIFY"

      command-auth    =/ notify

      notify          = "NOTIFY" SP
                      (notify-set / notify-none)

      notify-set      = "SET" [status-indicator] SP event-groups
                      ; Replace registered notification events
                      ; with the specified list of events

      notify-none     = "NONE"
                      ; Cancel all registered notification
                      ; events.  The client is not interested
                      ; in receiving any events.

      status-indicator = SP "STATUS"

      one-or-more-mailbox = mailbox / many-mailboxes

      many-mailboxes  = "(" mailbox *(SP mailbox) ")"

      event-groups    = event-group *(SP event-group)

      event-group     = "(" filter-mailboxes SP events ")"
                      ;; Only <message-event>s are allowed in <events>
                      ;; when <filter-mailboxes-selected> is used.

      filter-mailboxes = filter-mailboxes-selected /
                      filter-mailboxes-other





Gulbrandsen, et al.         Standards Track                    [Page 17]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


      filter-mailboxes-other = "inboxes" / "personal" / "subscribed" /
                      ( "subtree" SP one-or-more-mailbox ) /
                      ( "mailboxes" SP one-or-more-mailbox )

      filter-mailboxes-selected = "selected" / "selected-delayed"
                      ;; Apply to the currently selected mailbox only.
                      ;; Only one of them can be specified in a NOTIFY
                      ;; command.

      events          = ( "(" event *(SP event) ")" ) / "NONE"
                      ;; As in [MSGEVENT].
                      ;; "NONE" means that the client does not wish
                      ;; to receive any events for the specified
                      ;; mailboxes.

      event           = message-event /
                      mailbox-event / user-event / event-ext

      message-event   = ( "MessageNew" [SP
                          "(" fetch-att *(SP fetch-att) ")" ] )
                      / "MessageExpunge"
                      / "FlagChange"
                      / "AnnotationChange"
                      ;; "MessageNew" includes "MessageAppend" from
                      ;; [MSGEVENT]. "FlagChange" is any of
                      ;; "MessageRead", "MessageTrash", "FlagsSet",
                      ;; "FlagsClear" [MSGEVENT]. "MessageExpunge"
                      ;; includes "MessageExpire" [MSGEVENT].
                      ;; MessageNew and MessageExpunge MUST always
                      ;; be specified together.  If FlagChange is
                      ;; specified, then MessageNew and MessageExpunge
                      ;; MUST be specified as well.
                      ;; The fett-att list may only be present for the
                      ;; SELECTED/SELECTED-DELAYED mailbox filter
                      ;; (<filter-mailboxes>).

      mailbox-event   = "MailboxName" /
                      "SubscriptionChange" / "MailboxMetadataChange"
                      ; "SubscriptionChange" includes
                      ; MailboxSubscribe and MailboxUnSubscribe.
                      ; "MailboxName" includes MailboxCreate,
                      ; "MailboxDelete" and "MailboxRename".

      user-event      = "ServerMetadataChange"

      event-ext       = atom
                      ;; For future extensions




Gulbrandsen, et al.         Standards Track                    [Page 18]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


      oldname-extended-item =  "OLDNAME" SP "(" mailbox ")"
                      ;; Extended data item (mbox-list-extended-item)
                      ;; returned in a LIST response when a mailbox is
                      ;; renamed.
                      ;; Note 1: the OLDNAME tag can be returned
                      ;; with or without surrounding quotes, as per
                      ;; mbox-list-extended-item-tag production.

      resp-text-code  =/ "NOTIFICATIONOVERFLOW" /
                      unsupported-events-code

      message-event-name   = "MessageNew" /
                      "MessageExpunge" / "FlagChange" /
                      "AnnotationChange"

      event-name = message-event-name / mailbox-event /
                      user-event

      unsupported-events-code = "BADEVENT"
                      SP "(" event-name *(SP event-name) ")"

      modifier-update = "UPDATE"
                      [ "(" fetch-att *(SP fetch-att) ")" ]

      mbx-list-oflag =/ "\NoAccess"

9.  Security Considerations

   It is very easy for a client to deny itself service using NOTIFY.
   Asking for all events on all mailboxes may work on a small server,
   but with a big server, can swamp the client's network connection or
   processing capability.  In the worst case, the server's processing
   could also degrade the service it offers to other clients.

   Server authors should be aware that if a client issues requests and
   does not listen to the resulting responses, the TCP window can easily
   fill up, and a careless server might block.  This problem also exists
   in plain IMAP; however, this extension magnifies the problem.

   This extension makes it possible to retrieve messages immediately
   when they are added to the mailbox.  This makes it wholly impractical
   to delete sensitive messages using programs like imapfilter.  Using
   SIEVE [RFC5228] or similar is much better.








Gulbrandsen, et al.         Standards Track                    [Page 19]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


10.  IANA Considerations

   The IANA has added NOTIFY to the list of IMAP extensions.

10.1.  Initial LIST-EXTENDED Extended Data Item Registrations

   The following entry has been added to the LIST-EXTENDED response
   registry [RFC5258]:

   To: iana@iana.org
   Subject: Registration of OLDNAME LIST-EXTENDED extended data item

   LIST-EXTENDED extended data item tag: OLDNAME

   LIST-EXTENDED extended data item description: The OLDNAME extended
      data item describes the old mailbox name for the mailbox
      identified by the LIST response.

   Which LIST-EXTENDED option(s) (and their types) causes this extended
      data item to be returned (if any): none

   Published specification : RFC 5465, Section 5.4.

   Security considerations: none

   Intended usage: COMMON

   Person and email address to contact for further information:  Alexey
      Melnikov <Alexey.Melnikov@isode.com>

   Owner/Change controller: iesg@ietf.org

11.  Acknowledgments

   The authors gratefully acknowledge the help of Peter Coates, Dave
   Cridland, Mark Crispin, Cyrus Daboo, Abhijit Menon-Sen, Timo
   Sirainen, and Eric Burger.  In particular, Peter Coates contributed
   lots of text and useful suggestions to this document.

   Various examples are copied from other RFCs.

   This document builds on one published and two unpublished drafts by
   the same authors.








Gulbrandsen, et al.         Standards Track                    [Page 20]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


12.  Normative References

   [RFC2119]    Bradner, S., "Key words for use in RFCs to Indicate
                Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2177]    Leiba, B., "IMAP4 IDLE command", RFC 2177, June 1997.

   [RFC2342]    Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342,
                May 1998.

   [RFC3501]    Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
                4rev1", RFC 3501, March 2003.

   [RFC4314]    Melnikov, A., "IMAP4 Access Control List (ACL)
                Extension", RFC 4314, December 2005.

   [RFC4466]    Melnikov, A. and C. Daboo, "Collected Extensions to
                IMAP4 ABNF", RFC 4466, April 2006.

   [RFC4551]    Melnikov, A. and S. Hole, "IMAP Extension for
                Conditional STORE Operation or Quick Flag Changes
                Resynchronization", RFC 4551, June 2006.

   [RFC5162]    Melnikov, A., Cridland, D., and C. Wilson, "IMAP4
                Extensions for Quick Mailbox Resynchronization", RFC
                5162, March 2008.

   [RFC5234]    Crocker, D., Ed., and P. Overell, "Augmented BNF for
                Syntax Specifications: ABNF", STD 68, RFC 5234, January
                2008.

   [RFC5258]    Leiba, B. and A. Melnikov, "Internet Message Access
                Protocol version 4 - LIST Command Extensions", RFC 5258,
                June 2008.

   [RFC5267]    Cridland, D. and C. King, "Contexts for IMAP4", RFC
                5267, July 2008.

   [RFC5423]    Newman, C. and R. Gellens, "Internet Message Store
                Events", RFC 5423, Month 2009.

   [RFC5464]    Daboo, C., "The IMAP METADATA Extension", RFC 5464,
                February 2009.

13.  Informative References

   [RFC5228]    Guenther, P., Ed., and T. Showalter, Ed., "Sieve: An
                Email Filtering Language", RFC 5228, January 2008.



Gulbrandsen, et al.         Standards Track                    [Page 21]
^L
RFC 5465                 IMAP NOTIFY Extension             February 2009


   [EMAIL-ARCH] Crocker, D., "Internet Mail Architecture", Work in
                Progress, October 2008.

Authors' Addresses

   Arnt Gulbrandsen
   Oryx Mail Systems GmbH
   Schweppermannstr. 8
   D-81671 Muenchen
   Germany

   EMail: arnt@oryx.com


   Curtis King
   Isode Ltd
   5 Castle Business Village
   36 Station Road
   Hampton, Middlesex  TW12 2BX
   UK

   EMail: Curtis.King@isode.com


   Alexey Melnikov
   Isode Ltd
   5 Castle Business Village
   36 Station Road
   Hampton, Middlesex  TW12 2BX
   UK

   EMail: Alexey.Melnikov@isode.com



















Gulbrandsen, et al.         Standards Track                    [Page 22]
^L