Cyrus Event Source

Overview

Cyrus can be configured to send events to another program any time something changes in a mailbox. The event contains details about the type of action that occurred, identifying information about the message and other useful information. Cyrus generates events for pretty much everything – every user action, data change, and other interesting things like calendar alarms.

The notifications are compliant with RFC 5423, though Cyrus includes some additional events outside of the RFC.

By default, Cyrus ships with notifyd(8) which listens for events from Cyrus. Mostly it is used for sending email notifications triggered by Sieve scripts, or by calendar alarms triggered by calalarmd.

Compile options

You can control what kind of events Cyrus generates during the configure step of compilation.

--enable_event_notification: Set this to "yes" to have Cyrus generate mailbox related events. This is enabled by default.

--enable-apple-push-service: Set this to "yes" to enable support for the Apple Push service. This is disabled by default as Apple does not provide licenses for Push support to developers at this stage.

Configuration options

These need to be set in imapd.conf(5).

event_content_inclusion_mode: standard

The mode in which message content may be included with MessageAppend and MessageNew. "standard" mode is the default behavior in which message is included up to a size with the notification. In "message" mode, the message is included and may be truncated to a size. In "header" mode, it includes headers truncated to a size. In "body" mode, it includes body truncated to a size. In "headerbody" mode, it includes full headers and body truncated to a size. Allowed values: standard, message, header, body, headerbody

event_content_size: 0

Truncate the message content that may be included with MessageAppend and MessageNew. Set 0 to include the entire message itself.

If no unit is specified, bytes is assumed.

event_exclude_flags: <none>

Don't send event notification for given IMAP flag(s).

event_exclude_specialuse: \Junk

Don't send event notification for folder with given special-use attributes. Set ALL for any folder.

event_extra_params: timestamp

Space-separated list of extra parameters to add to any appropriated event.

Allowed values: bodyStructure, clientAddress, diskUsed, flagNames, messageContent, messageSize, messages, modseq, service, timestamp, uidnext, vnd.cmu.midset, vnd.cmu.unseenMessages, vnd.cmu.envelope, vnd.cmu.sessionId, vnd.cmu.mailboxACL, vnd.cmu.mbtype, vnd.cmu.davFilename, vnd.cmu.davUid, vnd.fastmail.clientId, vnd.fastmail.sessionId, vnd.fastmail.convExists, vnd.fastmail.convUnseen, vnd.fastmail.cid, vnd.fastmail.counters, vnd.fastmail.jmapEmail, vnd.fastmail.jmapStates, vnd.cmu.emailid, vnd.cmu.threadid, vnd.cmu.visibleUsers

event_groups: message mailbox

Space-separated list of groups of related events to turn on notification.

Allowed values: message, quota, flags, access, mailbox, subscription, calendar, applepushservice, jmap

event_notifier: <none>

Notifyd(8) method to use for "EVENT" notifications which are based on the RFC 5423. If not set, "EVENT" notifications are disabled.

Event Types

These are detailed in Event Notifications.

Accessing events

While Cyrus only communicates with a single notification process, it doesn't have to be its standard notifyd(8). It's possible to write your own, providing it conforms with RFC 5465.

Apple Push Service

While Cyrus supports the Apple Push Service, Apple has only licensed Apple Push for mail to a couple of large mail providers: Fastmail and Yahoo. If you own an OS X Server license, you also get a key for personal use. But it's not generally a supported option for third party developers that we're aware of, unfortunately.

We have discussed pulling the XAPPLEPUSH code out from upstream Cyrus, but right now it remains against the day that Apple do decide to open up access.