Event Notifications

Note

Cyrus IMAP documentation is a work in progress. The completion of this particular part of the documentation is pending the resolution of :task:`43`.

RFC 5423 standardizes the emission of message store event notifications, and RFC 5465 outlines the IMAP NOTIFY extensions.

New in version 2.5.0.

Example Event Notifications

AclChange

The ACL Change notification is emitted when a command SETACL is issued.

Note

This event notification is added to Cyrus IMAP outside of any RFC.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "aclRights": "lrs",
    "aclSubject": "jane@example.org",
    "event": "AclChange",
    "mailboxID": "imap://john@example.org@imap.example.org/Testfolder_renamed;UIDVALIDITY=1424699807",
    "pid": 8048,
    "service": "imap",
    "timestamp": "2015-02-23T14:57:59.736+01:00",
    "uri": "imap://john@example.org@imap.example.org/Testfolder_renamed;UIDVALIDITY=1424699807",
    "user": "john@example.org",
    "vnd.cmu.sessionId": "imap.example.org-8048-1424699879-1-8051832424702584527"
}

FlagsClear

The FlagsClear notification is emitted when all flags are removed from a message.

This includes \Deleted, \Seen and \Flagged, and as such are, in part, the counter-parts to MessageTrash, MessageRead, and FlagsSet.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
    "event": "FlagsClear",
    "flagNames": "\\Flagged",
    "messages": 1,
    "modseq": 43,
    "pid": 7721,
    "service": "imap",
    "timestamp": "2015-02-23T14:50:43.640+01:00",
    "uidnext": 4,
    "uidset": "3",
    "uri": "imap://john@example.org@imap.example.org/INBOX;UIDVALIDITY=1424683682",
    "user": "john@example.org",
    "vnd.cmu.midset": [
        "<4d9618acd0aea6b33683766358351459@example.org>"
    ],
    "vnd.cmu.sessionId": "imap.example.org-7721-1424699443-1-8479002111695998134",
    "vnd.cmu.unseenMessages": 0
}

FlagsSet

The FlagsSet notification is emitted when flags are set on a message, but not including the \Deleted and \Seen flags, which emit MessageTrash and MessageRead event notifications respectively.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
    "event": "FlagsSet",
    "flagNames": "\\Flagged",
    "messages": 1,
    "modseq": 42,
    "pid": 7649,
    "service": "imap",
    "timestamp": "2015-02-23T14:50:21.858+01:00",
    "uidnext": 4,
    "uidset": "3",
    "uri": "imap://john@example.org@imap.example.org/INBOX;UIDVALIDITY=1424683682",
    "user": "john@example.org",
    "vnd.cmu.midset": [
        "<4d9618acd0aea6b33683766358351459@example.org>"
    ],
    "vnd.cmu.sessionId": "imap.example.org-7649-1424699421-1-11813528620713894618",
    "vnd.cmu.unseenMessages": 0
}

Login

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "clientIP": "::1",
    "clientPort": 46461,
    "event": "Login",
    "pid": 7629,
    "serverDomain": "::1",
    "serverPort": 143,
    "service": "imap",
    "timestamp": "2015-02-23T14:47:36.097+01:00",
    "uri": "imap://imap.example.org",
    "user": "john@example.org",
    "vnd.cmu.sessionId": "imap.example.org-7629-1424699256-1-3981462903180119079"
}

Logout

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "clientIP": "::1",
    "clientPort": 46461,
    "event": "Logout",
    "pid": 7629,
    "serverDomain": "::1",
    "serverPort": 143,
    "service": "imap",
    "timestamp": "2015-02-23T14:47:36.183+01:00",
    "uri": "imap://imap.example.org",
    "user": "john@example.org",
    "vnd.cmu.sessionId": "imap.example.org-7629-1424699256-1-3981462903180119079"
}

MailboxCreate

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "event": "MailboxCreate",
    "mailboxID": "imap://john@example.org@imap.example.org/Testfolder;UIDVALIDITY=1424690388",
    "pid": 7721,
    "service": "imap",
    "timestamp": "2015-02-23T14:55:57.621+01:00",
    "uri": "imap://john@example.org@imap.example.org/Testfolder;UIDVALIDITY=1424690388",
    "user": "john@example.org",
    "vnd.cmu.sessionId": "imap.example.org-7721-1424699757-1-18345110432907898457"
}

MailboxDelete

Note

A mailbox deletion event notification is issued once for each top- level mailbox in a hierarchy being deleted.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "event": "MailboxDelete",
    "mailboxID": "imap://john@example.org@imap.example.org/Testfolder_renamed;UIDVALIDITY=1424699807",
    "pid": 8070,
    "service": "imap",
    "timestamp": "2015-02-23T14:58:37.145+01:00",
    "uri": "imap://john@example.org@imap.example.org/Testfolder_renamed;UIDVALIDITY=1424699807",
    "user": "john@example.org",
    "vnd.cmu.sessionId": "imap.example.org-8070-1424699917-1-11277155374959916506"
}

MailboxRename

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "event": "MailboxRename",
    "mailboxID": "imap://john@example.org@imap.example.org/Testfolder_renamed;UIDVALIDITY=1424699807",
    "oldMailboxID": "imap://john@example.org@imap.example.org/Testfolder;UIDVALIDITY=1424690388",
    "pid": 8026,
    "service": "imap",
    "timestamp": "2015-02-23T14:56:47.466+01:00",
    "uri": "imap://john@example.org@imap.example.org/Testfolder_renamed;UIDVALIDITY=1424699807",
    "user": "john@example.org",
    "vnd.cmu.sessionId": "imap.example.org-8026-1424699807-1-3097981731339369225"
}

MailboxSubscribe

1
2
3
4
5
6
7
8
9
{
    "event": "MailboxSubscribe",
    "pid": 3004,
    "service": "imap",
    "timestamp": "2015-02-23T18:37:02.344+01:00",
    "uri": "imap://john@example.org@imap.example.org/Archive",
    "user": "john@example.org",
    "vnd.cmu.sessionId": "imap.example.org-3004-1424713022-1-7149274646509524617"
}

MailboxUnSubscribe

1
2
3
4
5
6
7
8
9
{
    "event": "MailboxUnSubscribe",
    "pid": 3003,
    "service": "imap",
    "timestamp": "2015-02-23T18:37:19.482+01:00",
    "uri": "imap://john@example.org@imap.example.org/Testfolder_renamed",
    "user": "john@example.org",
    "vnd.cmu.sessionId": "imap.example.org-3003-1424713039-1-2806700531460584176"
}

MessageAppend

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    "bodyStructure": "((\"TEXT\" \"PLAIN\" (\"CHARSET\" \"ISO-8859-1\") NIL NIL \"QUOTED-PRINTABLE\" 206 4 NIL NIL NIL NIL)(\"APPLICATION\" \"CALENDAR+XML\" (\"CHARSET\" \"UTF-8\" \"NAME\" \"kolab.xml\") NIL NIL \"8BIT\" 2030 NIL (\"ATTACHMENT\" (\"FILENAME\" \"kolab.xml\" \"SIZE\" \"2030\")) NIL NIL) \"MIXED\" (\"BOUNDARY\" \"=_d9aa3c2dd73a9166113254d4ebe07bc8\") NIL NIL NIL)",
    "event": "MessageAppend",
    "messageSize": 2992,
    "messages": 3,
    "modseq": 12,
    "pid": 7721,
    "service": "imap",
    "timestamp": "2015-02-23T14:51:29.008+01:00",
    "uidnext": 6,
    "uri": "imap://john@example.org@imap.example.org/Calendar;UIDVALIDITY=1424683684/;UID=5",
    "user": "john@example.org",
    "vnd.cmu.envelope": "(\"Mon, 23 Feb 2015 13:51:28 +0000\" \"BBA47B13E4839F49AB1C8047EE7B4FDB-A4BF5BBB9FEAA271\" ((NIL NIL \"john\" \"example.org\")) ((NIL NIL \"john\" \"example.org\")) ((NIL NIL \"john\" \"example.org\")) ((NIL NIL \"john\" \"example.org\")) NIL NIL NIL NIL)",
    "vnd.cmu.midset": [
        "NIL"
    ],
    "vnd.cmu.sessionId": "imap.example.org-7721-1424699488-1-10167054345787041319",
    "vnd.cmu.unseenMessages": 3
}

MessageCopy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    "event": "vnd.cmu.MessageCopy",
    "messages": 1,
    "modseq": 9,
    "oldMailboxID": "imap://john@example.org@imap.example.org/Sent;UIDVALIDITY=1424683683",
    "pid": 8107,
    "service": "imap",
    "timestamp": "2015-02-23T14:59:49.717+01:00",
    "uidnext": 5,
    "uidset": "4",
    "uri": "imap://john@example.org@imap.example.org/Archive;UIDVALIDITY=1424683684",
    "user": "john@example.org",
    "vnd.cmu.midset": [
        "<4d9618acd0aea6b33683766358351459@example.org>"
    ],
    "vnd.cmu.oldUidset": "2",
    "vnd.cmu.sessionId": "imap.example.org-8107-1424699989-1-8439907626481649843",
    "vnd.cmu.unseenMessages": 0
}

MessageExpire

MessageExpunge

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
    "event": "MessageExpunge",
    "messages": 0,
    "modseq": 53,
    "pid": 7813,
    "service": "imap",
    "timestamp": "2015-02-23T14:55:20.562+01:00",
    "uidnext": 5,
    "uidset": "4",
    "uri": "imap://john@example.org@imap.example.org/INBOX;UIDVALIDITY=1424683682",
    "user": "john@example.org",
    "vnd.cmu.midset": [
        "<4d9618acd0aea6b33683766358351459@example.org>"
    ],
    "vnd.cmu.sessionId": "imap.example.org-7813-1424699720-1-13590468293654033744",
    "vnd.cmu.unseenMessages": 0
}

MessageMove

Important

The MessageMove event is an event type not documented in an RFC.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    "event": "vnd.cmu.MessageMove",
    "messages": 2,
    "modseq": 5,
    "oldMailboxID": "imap://john@example.org@imap.example.org/INBOX;UIDVALIDITY=1424683682",
    "pid": 7685,
    "service": "imap",
    "timestamp": "2015-02-23T14:52:41.676+01:00",
    "uidnext": 4,
    "uidset": "3",
    "uri": "imap://john@example.org@imap.example.org/Archive;UIDVALIDITY=1424683684",
    "user": "john@example.org",
    "vnd.cmu.midset": [
        "<4d9618acd0aea6b33683766358351459@example.org>"
    ],
    "vnd.cmu.oldUidset": "3",
    "vnd.cmu.sessionId": "imap.example.org-7685-1424699561-1-7444588115769591371",
    "vnd.cmu.unseenMessages": 0
}

MessageNew

 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
{
    "event": "MessageNew",
    "messageContent": {
        "6": "Return-Path: <john@example.org>\r\nReceived: from imap.example.org ([unix socket])\r\n\t by imap.example.org (Cyrus git2.5+0-Kolab-2.5-67.el6.kolab_3.4) with LMTPA;\r\n\t Mon, 20 Oct 2014 13:34:14 +0200\r\nX-Sieve: CMU Sieve 2.4\r\nX-Virus-Scanned: amavisd-new at example.org\r\nX-Spam-Flag: NO\r\nX-Spam-Score: -0.002\r\nX-Spam-Level: \r\nX-Spam-Status: No, score=-0.002 tagged_above=-10 required=6.2\r\n\ttests=[NO_RECEIVED=-0.001, NO_RELAYS=-0.001] autolearn=ham\r\nMIME-Version: 1.0\r\nContent-Type: text/plain; charset=US-ASCII;\r\n format=flowed\r\nContent-Transfer-Encoding: 7bit\r\nDate: Mon, 20 Oct 2014 13:32:41 +0200\r\nFrom: =?UTF-8?Q?Br=C3=BCederli=2C_Thomas?= <john@example.org>\r\nTo: \"Doe, John\" <john@example.org>\r\nSubject: MessageNew event test\r\nMessage-ID: <a8486f5db6ec207de9b9f069850546ee@example.org>\r\nX-Sender: john@example.org\r\n\r\nThis message should trigger the MessageNew event for john...\r\n...and MessageAppend to /Sent for the sender.\r\n"
    },
    "messageHeaders": {
        "6": {
            "Content-Transfer-Encoding": "7bit",
            "Content-Type": "text/plain",
            "Date": "2014-10-20T11:32:41Z",
            "From": [
                "Br\u00fcederli, Thomas <john@example.org>"
            ],
            "MIME-Version": "1.0",
            "Message-ID": "<a8486f5db6ec207de9b9f069850546ee@example.org>",
            "Received": "from imap.example.org ([unix socket])\r\n\t by imap.example.org (Cyrus git2.5+0-Kolab-2.5-67.el6.kolab_3.4) with LMTPA;\r\n\t Mon, 20 Oct 2014 13:34:14 +0200",
            "Return-Path": "<john@example.org>",
            "Subject": "MessageNew event test",
            "To": [
                "Doe, John <john@example.org>"
            ],
            "X-Sender": "john@example.org",
            "X-Sieve": "CMU Sieve 2.4",
            "X-Spam-Flag": "NO",
            "X-Spam-Level": "",
            "X-Spam-Score": "-0.002",
            "X-Spam-Status": "No, score=-0.002 tagged_above=-10 required=6.2\r\n\ttests=[NO_RECEIVED=-0.001, NO_RELAYS=-0.001] autolearn=ham",
            "X-Virus-Scanned": "amavisd-new at example.org"
        }
    },
    "messageSize": 976,
    "messages": 6,
    "modseq": 20,
    "pid": 2340,
    "service": "lmtpunix",
    "timestamp": "2014-10-20T13:34:14.966+02:00",
    "uidnext": 7,
    "uidset": "6",
    "uri": "imap://john@example.org@imap.example.org/INBOX;UIDVALIDITY=1411487714/;UID=6",
    "user": "john@example.org",
    "vnd.cmu.midset": [
        "<a8486f5db6ec207de9b9f069850546ee@example.org>"
    ],
    "vnd.cmu.sessionId": "imap.example.org-2340-1413804854-1",
    "vnd.cmu.unseenMessages": 3
}

MessageRead

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
    "event": "MessageRead",
    "messages": 1,
    "modseq": 47,
    "pid": 7685,
    "service": "imap",
    "timestamp": "2015-02-23T14:53:44.476+01:00",
    "uidnext": 5,
    "uidset": "4",
    "uri": "imap://john@example.org@imap.example.org/INBOX;UIDVALIDITY=1424683682",
    "user": "john@example.org",
    "vnd.cmu.midset": [
        "<4d9618acd0aea6b33683766358351459@example.org>"
    ],
    "vnd.cmu.sessionId": "imap.example.org-7685-1424699624-1-9701853636551497828",
    "vnd.cmu.unseenMessages": 0
}

MessageTrash

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
    "event": "MessageTrash",
    "messages": 1,
    "modseq": 48,
    "pid": 7809,
    "service": "imap",
    "timestamp": "2015-02-23T14:54:02.616+01:00",
    "uidnext": 5,
    "uidset": "4",
    "uri": "imap://john@example.org@imap.example.org/INBOX;UIDVALIDITY=1424683682",
    "user": "john@example.org",
    "vnd.cmu.midset": [
        "<4d9618acd0aea6b33683766358351459@example.org>"
    ],
    "vnd.cmu.sessionId": "imap.example.org-7809-1424699642-1-2896189896878960640",
    "vnd.cmu.unseenMessages": 0
}

QuotaChange

Note

This event may be followed by a QuotaWithin event notification, if the quota change leads the quota root to allow more resources than currently in use.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "diskQuota": 123456789,
    "diskUsed": 2,
    "event": "QuotaChange",
    "maxMessages": -1,
    "messages": 3,
    "pid": 8140,
    "service": "imaps",
    "timestamp": "2015-03-10T16:16:19.255+01:00",
    "uri": "imap://john.doe@example.org@kolab.example.org/INBOX",
    "user": "john.doe@example.org",
    "vnd.cmu.sessionId": "kolab.example.org-8140-1426000578-1-14068443041501787710"
}

QuotaExceed

The user parameter in the event notification is the user to whom the quota applies, that is being exceeded, otherwise known as the owner of the Personal Namespace.

Note

Quota being exceeded on shared folders cannot include an “owner” for the quota root.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "diskQuota": 2,
    "diskUsed": 2,
    "event": "QuotaExceed",
    "maxMessages": -1,
    "messages": 3,
    "pid": 8210,
    "service": "lmtpunix",
    "timestamp": "2015-03-10T16:13:40.218+01:00",
    "uri": "imap://john.doe@example.org@kolab.example.org/INBOX",
    "user": "john.doe@example.org",
    "vnd.cmu.sessionId": "kolab.example.org-8210-1426000420-4-9494635035963533515"
}

QuotaWithin

The QuotaWithin event typically follows a MailboxDelete 1, MessageExpunge 2, MessageMove 3, or QuotaChange 4.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "diskQuota": 123456789,
    "diskUsed": 2,
    "event": "QuotaWithin",
    "maxMessages": -1,
    "messages": 3,
    "pid": 8140,
    "service": "imaps",
    "timestamp": "2015-03-10T16:16:19.255+01:00",
    "uri": "imap://john.doe@example.org@kolab.example.org/INBOX",
    "user": "john.doe@example.org",
    "vnd.cmu.sessionId": "kolab.example.org-8140-1426000578-1-14068443041501787710"
}

Footnotes for QuotaWithin

1

A QuotaWithin event follows a MailboxDelete event if the mailbox deleted resides inside a quota root, and lowers the resources used to below the existing quota thresholds.

2

A QuotaWithin event follows a MessageExpunge event if the messages purged reside inside a quota root, and amount to a number or size that lowers the amount of resources used to below the existing quota thresholds.

3

A QuotaWithin event follows a MessageMove event if the source folder of the messages moved resides inside a quota root, and the target folder to which the messages have been moved does not reside within the same quota root, and the number or size of the messages moves lowers the amount of resources used in the quota root for the source folder of the messages to below the existing quota thresholds.

4

A QuotaWithin event follows a QuotaChange event if the quota change raised the threshold on the amount of resources used within the quota root to a level higher than the existing amount of resources used.

CalendarAlarm

The CalendarAlarm event occurs when a calendar event triggers an alarm.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "event":"CalendarAlarm",
    "pid":3164225,
    "serverFQDN":"sloti30t15",
    "alarmTime":"20151119T063000Z",
    "alarmRecipients":["mailto:mary@example.org"],
    "userId":"mary@example.org",
    "calendarName":"Calendar",
    "uid":"49ba20f5-cb44-4863-aea7-255f37ffc2e7",
    "action":"email",
    "summary":"Here's a lovely event.  Remind me",
    "description":"",
    "location":"",
    "timezone":"Australia/Melbourne",
    "start":"20151119T073000Z",
    "end":"20151119T083000Z",
    "allDay":0,
    "attendeeNames":[],
    "attendeeEmails":[],
    "attendeeStatus":[],
    "organizer":""
}

ApplePushService

The ApplePushService event occurs when

1
2
3
4
5
6
7
8
9
{
    "event":"ApplePushService",
    "user": "john@example.org",
    "apsVersion": "",     # Version of the Apple Push Service this message is compliant with.
    "apsAccountId": "",   # Service Provider's accountID with the Apple Push Service.
    "apsDeviceToken": "", # Unique identifier for the user's device registered with Apple
    "apsSubtopic": "",    # 
    "mailboxes": "[array of mailboxIDs]"
}

Back to IMAP Features