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*

   "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.
