Debian Codegraph @

doc/html/_sources/imap/concepts/features/event-notifications.rst.txt

raw
1 .. _imap-features-event-notifications:
2
3 ===================
4 Event Notifications
5 ===================
6
7 :rfc:`5423` standardizes the emission of message store event
8 notifications, and :rfc:`5465` outlines the IMAP NOTIFY extensions.
9
10 .. versionadded:: 2.5.0
11
12 Available Event Notifications
13 =============================
14
15 * Message Events
16 * :ref:`imap-features-event-notifications-messageappend`
17 * :ref:`imap-features-event-notifications-messagecopy`
18 * :ref:`imap-features-event-notifications-messageexpire`
19 * :ref:`imap-features-event-notifications-messageexpunge`
20 * :ref:`imap-features-event-notifications-messagemove`
21 * :ref:`imap-features-event-notifications-messagenew`
22 * Flag Events
23 * :ref:`imap-features-event-notifications-flagsclear`
24 * :ref:`imap-features-event-notifications-flagsset`
25 * :ref:`imap-features-event-notifications-messageread`
26 * :ref:`imap-features-event-notifications-messagetrash`
27 * Mailbox Events
28 * :ref:`imap-features-event-notifications-aclchange`
29 * :ref:`imap-features-event-notifications-mailboxcreate`
30 * :ref:`imap-features-event-notifications-mailboxdelete`
31 * :ref:`imap-features-event-notifications-mailboxrename`
32 * Subscription Events
33 * :ref:`imap-features-event-notifications-mailboxsubscribe`
34 * :ref:`imap-features-event-notifications-mailboxunsubscribe`
35 * Quota Events
36 * :ref:`imap-features-event-notifications-quotaexceed`
37 * :ref:`imap-features-event-notifications-quotawithin`
38 * :ref:`imap-features-event-notifications-quotachange`
39 * Calendar Events
40 * :ref:`imap-features-event-notifications-calendaralarm`
41 * Access Accounting
42 * :ref:`imap-features-event-notifications-login`
43 * :ref:`imap-features-event-notifications-logout`
44 * Apple Push
45 * :ref:`imap-features-event-notifications-applepushservice`
46
47
48 Example Event Notifications
49 ===========================
50
51 .. _imap-features-event-notifications-aclchange:
52
53 AclChange
54 ---------
55
56 The ACL Change notification is emitted when a command ``SETACL`` is
57 issued.
58
59 .. NOTE::
60
61 This event notification is added to Cyrus IMAP outside of any RFC.
62
63 .. literalinclude:: ../../../_static/event_notifications/AclChange.json
64 :language: json
65 :linenos:
66
67 .. _imap-features-event-notifications-flagsclear:
68
69 FlagsClear
70 ----------
71
72 The FlagsClear notification is emitted when all flags are removed from a
73 message.
74
75 This includes ``\Deleted``, ``\Seen`` and ``\Flagged``, and as such are,
76 in part, the counter-parts to
77 :ref:`imap-features-event-notifications-messagetrash`,
78 :ref:`imap-features-event-notifications-messageread`, and
79 :ref:`imap-features-event-notifications-flagsset`.
80
81 .. TODO::
82
83 * Include an example event notification emitted for multiple
84 messages being cleared the flags of.
85
86 * Include an example event notification emitted for multiple flags
87 being cleared.
88
89 .. literalinclude:: ../../../_static/event_notifications/FlagsClear.json
90 :language: json
91 :linenos:
92
93 .. _imap-features-event-notifications-flagsset:
94
95 FlagsSet
96 --------
97
98 The FlagsSet notification is emitted when flags are set on a message,
99 but not including the ``\Deleted`` and ``\Seen`` flags, which emit
100 :ref:`imap-features-event-notifications-messagetrash` and
101 :ref:`imap-features-event-notifications-messageread` event notifications
102 respectively.
103
104 .. TODO::
105
106 * Include an example event notification emitted for multiple
107 messages being set flags on.
108
109 * Include an example event notification emitted for multiple flags
110 being set.
111
112 .. literalinclude:: ../../../_static/event_notifications/FlagsSet.json
113 :language: json
114 :linenos:
115
116 .. _imap-features-event-notifications-login:
117
118 Login
119 -----
120
121 .. literalinclude:: ../../../_static/event_notifications/Login.json
122 :language: json
123 :linenos:
124
125 .. _imap-features-event-notifications-logout:
126
127 Logout
128 ------
129
130 .. literalinclude:: ../../../_static/event_notifications/Logout.json
131 :language: json
132 :linenos:
133
134 .. _imap-features-event-notifications-mailboxcreate:
135
136 MailboxCreate
137 -------------
138
139 .. literalinclude:: ../../../_static/event_notifications/MailboxCreate.json
140 :language: json
141 :linenos:
142
143 .. _imap-features-event-notifications-mailboxdelete:
144
145 MailboxDelete
146 -------------
147
148 .. NOTE::
149
150 A mailbox deletion event notification is issued once for each top-
151 level mailbox in a hierarchy being deleted.
152
153 ..
154 Mar 10 13:59:36 kolab notifyd[18204]: EVENT, , , , "{"event":"MailboxDelete","timestamp":"2015-03-10T13:59:36.279+01:00","service":"imaps","mailboxID":"imap://[email protected]@kolab.example.org/INBOX;UIDVALIDITY=1425991710","uri":"imap://[email protected]@kolab.example.org/INBOX;UIDVALIDITY=1425991710","pid":18210,"user":"cyrus-admin","vnd.cmu.sessionId":"kolab.example.org-18210-1425992375-1-10616182148387168471"}"
155
156 .. literalinclude:: ../../../_static/event_notifications/MailboxDelete.json
157 :language: json
158 :linenos:
159
160 .. _imap-features-event-notifications-mailboxrename:
161
162 MailboxRename
163 -------------
164
165 .. literalinclude:: ../../../_static/event_notifications/MailboxRename.json
166 :language: json
167 :linenos:
168
169 .. _imap-features-event-notifications-mailboxsubscribe:
170
171 MailboxSubscribe
172 ----------------
173
174 .. literalinclude:: ../../../_static/event_notifications/MailboxSubscribe.json
175 :language: json
176 :linenos:
177
178 .. _imap-features-event-notifications-mailboxunsubscribe:
179
180 MailboxUnSubscribe
181 ------------------
182
183 .. literalinclude:: ../../../_static/event_notifications/MailboxUnSubscribe.json
184 :language: json
185 :linenos:
186
187 .. _imap-features-event-notifications-messageappend:
188
189 MessageAppend
190 -------------
191
192 .. literalinclude:: ../../../_static/event_notifications/MessageAppend.json
193 :language: json
194 :linenos:
195
196 .. _imap-features-event-notifications-messagecopy:
197
198 MessageCopy
199 -----------
200
201 .. literalinclude:: ../../../_static/event_notifications/MessageCopy.json
202 :language: json
203 :linenos:
204
205 .. _imap-features-event-notifications-messageexpire:
206
207 MessageExpire
208 -------------
209
210 .. _imap-features-event-notifications-messageexpunge:
211
212 MessageExpunge
213 --------------
214
215 .. literalinclude:: ../../../_static/event_notifications/MessageExpunge.json
216 :language: json
217 :linenos:
218
219 .. _imap-features-event-notifications-messagemove:
220
221 MessageMove
222 -----------
223
224 .. IMPORTANT::
225
226 The ``MessageMove`` event is an event type not documented in an RFC.
227
228 .. literalinclude:: ../../../_static/event_notifications/MessageMove.json
229 :language: json
230 :linenos:
231
232 .. _imap-features-event-notifications-messagenew:
233
234 MessageNew
235 ----------
236
237 .. literalinclude:: ../../../_static/event_notifications/MessageNew.json
238 :language: json
239 :linenos:
240
241 .. _imap-features-event-notifications-messageread:
242
243 MessageRead
244 -----------
245
246 .. literalinclude:: ../../../_static/event_notifications/MessageRead.json
247 :language: json
248 :linenos:
249
250 .. _imap-features-event-notifications-messagetrash:
251
252 MessageTrash
253 ------------
254
255 .. literalinclude:: ../../../_static/event_notifications/MessageTrash.json
256 :language: json
257 :linenos:
258
259 .. _imap-features-event-notifications-quotachange:
260
261 QuotaChange
262 -----------
263
264 .. NOTE::
265
266 This event may be followed by a
267 :ref:`imap-features-event-notifications-quotawithin` event
268 notification, if the quota change leads the quota root to allow more
269 resources than currently in use.
270
271 .. literalinclude:: ../../../_static/event_notifications/QuotaChange.json
272 :language: json
273 :linenos:
274
275 .. _imap-features-event-notifications-quotaexceed:
276
277 QuotaExceed
278 -----------
279
280 The ``user`` parameter in the event notification is the user to whom the
281 quota applies, that is being exceeded, otherwise known as the owner of
282 the :ref:`imap-features-namespaces-personal`.
283
284 .. NOTE::
285
286 Quota being exceeded on shared folders cannot include an "owner" for
287 the quota root.
288
289 .. literalinclude:: ../../../_static/event_notifications/QuotaExceed.json
290 :language: json
291 :linenos:
292
293 .. _imap-features-event-notifications-quotawithin:
294
295 QuotaWithin
296 -----------
297
298 The ``QuotaWithin`` event typically follows a
299 :ref:`imap-features-event-notifications-mailboxdelete` [#]_,
300 :ref:`imap-features-event-notifications-messageexpunge` [#]_,
301 :ref:`imap-features-event-notifications-messagemove` [#]_, or
302 :ref:`imap-features-event-notifications-quotachange` [#]_.
303
304 .. literalinclude:: ../../../_static/event_notifications/QuotaWithin.json
305 :language: json
306 :linenos:
307
308 .. rubric:: Footnotes for QuotaWithin
309
310 .. [#]
311
312 A ``QuotaWithin`` event follows a ``MailboxDelete`` event if the
313 mailbox deleted resides inside a quota root, and lowers the
314 resources used to below the existing quota thresholds.
315
316 .. [#]
317
318 A ``QuotaWithin`` event follows a ``MessageExpunge`` event if the
319 messages purged reside inside a quota root, and amount to a number
320 or size that lowers the amount of resources used to below the
321 existing quota thresholds.
322
323 .. [#]
324
325 A ``QuotaWithin`` event follows a ``MessageMove`` event if the
326 source folder of the messages moved resides inside a quota root, and
327 the target folder to which the messages have been moved does not
328 reside within the same quota root, and the number or size of the
329 messages moves lowers the amount of resources used in the quota root
330 for the source folder of the messages to below the existing
331 quota thresholds.
332
333 .. [#]
334
335 A ``QuotaWithin`` event follows a ``QuotaChange`` event if the quota
336 change raised the threshold on the amount of resources used within
337 the quota root to a level higher than the existing amount of
338 resources used.
339
340 .. _imap-features-event-notifications-calendaralarm:
341
342 CalendarAlarm
343 -------------
344
345 The ``CalendarAlarm`` event occurs when a calendar event triggers an
346 alarm.
347
348 .. literalinclude:: ../../../_static/event_notifications/CalendarAlarm.json
349 :language: json
350 :linenos:
351
352 .. _imap-features-event-notifications-applepushservice:
353
354 ApplePushService
355 ----------------
356
357 While Cyrus supports the Apple Push Service, Apple has only licensed Apple Push
358 for mail to a couple of large mail providers: Fastmail and Yahoo. If you own an
359 OS X Server license, you also get a key for personal use. But it's not
360 a supported option for third party developers at this time.
361
362 The ``ApplePushService`` event occurs when
363
364 .. literalinclude:: ../../../_static/event_notifications/ApplePushService.json
365 :language: json
366 :linenos:
367
368 apsVersion
369 Version of the Apple Push Service this message is compliant with.
370
371 apsAccountId
372 Service Provider's accountID with the Apple Push Service.
373
374 apsDeviceToken
375 Unique identifier for the user's device registered with Apple.
376
377 apsSubtopic
378 TODO: describe this
379
380 Back to :ref:`imap-features`