Support for Internet Message Access Protocol (IMAP) Events in Sieve
updates
- rfc-5228 — Sieve: An Email Filtering Language
Extracted elements (24)
Only one Sieve script is allowed per mailbox to eliminate complexity and ambiguity from coordinating multiple scripts. Any sub-filtering (e.g., acting only on flag changes and not APPEND) is handled inside the single script by checking the 'imap.cause' environment item.
This document updates the base Sieve specification (RFC 5228) by requiring future Sieve extensions that define new actions to specify their applicability to imapsieve. Extensions specifically designed for new-message delivery are not applicable to IMAP events.
When messages are processed under IMAP events, delivery envelope information may be absent. Sieve actions that rely on envelope data (such as the 'envelope' test) are prohibited. The 'redirect' action must cope with missing information by using message submission and synthesizing MAIL FROM from the mailbox owner's address.
Envelope tests MUST NOT be permitted in IMAP event contexts and their use MUST generate a runtime error, because envelope information is either unavailable or has serious interoperability issues outside of final-delivery time.
For all IMAP event cases, transient changes made to a message by Sieve actions MUST NOT be retained for any 'keep' action, because IMAP messages are immutable. The original message, without changes, is kept.
Future extensions to Sieve that define new actions MUST specify the applicability of those actions to this (imapsieve) specification.
Implementations MUST support ManageSieve (RFC 5804) for creating and storing Sieve scripts. Only one Sieve script may currently be defined per mailbox via the '/shared/imapsieve/script' metadata entry.
In a server that advertises 'imapsieve', new messages added via the IMAP COPY command MUST trigger the execution of a Sieve script, subject to Metadata settings.
Messages whose flags are changed MUST trigger the execution of a Sieve script, except that flag changes resulting from a script that was itself invoked because of flag changes SHOULD NOT result in a further invocation. Implementations MUST take steps to avoid such loops.
Sieve scripts that depend upon IMAP events MUST include the 'imapsieve' string in their 'required' lists. Implementations that support IMAP events in Sieve MUST also support IMAP Metadata (RFC 5464) and Sieve Environment (RFC 5183).
The inapplicable actions 'reject', 'ereject', and 'vacation' are not applicable to IMAP events. Their appearance in the 'require' control or their use in an IMAP event MUST result in an error condition that terminates the Sieve script.
Script association with IMAP mailboxes is done via IMAP Metadata. If the '/shared/imapsieve/script' mailbox metadata entry exists, it is used; otherwise the server-level entry of the same name is used as a global default. If neither exists, no script is invoked.
The 'fileinto' action, when triggered by an IMAP event, stores the message into the fileinto mailbox in addition to (for APPEND/COPY) or as a copy from (for flag changes) the original mailbox. The 'fileinto' action itself is not an IMAP APPEND or COPY and does not trigger a subsequent Sieve invocation.
The 'imap.cause' environment item MUST be set by the implementation to indicate which action triggered the script: APPEND, COPY, or FLAG. This allows a single mailbox script to handle all event types.
The 'imap.changedflags' environment item MUST be set to the name(s) of changed flags when the script is invoked due to flag changes; otherwise it MUST be the empty string. Scripts can use 'hasflag' to determine whether flags were set or reset.
The 'imap.mailbox' environment item MUST be set to the name of the mailbox containing or targeted for the affected message. Its value is fixed when the script begins and MUST NOT change as a result of any action such as 'fileinto'.
The 'imapsieve' IMAP capability string advertises server support for IMAP events in Sieve. Its syntax is 'IMAPSIEVE=<sieveurl-server>' where sieveurl-server identifies the ManageSieve server for managing associated Sieve scripts. Only one such capability string is allowed.
The 'redirect' action is applicable to all IMAP event cases. For messages lacking header or envelope information (e.g., APPENDed drafts), the Sieve engine must supply missing information and use message submission (RFC 6409); the MAIL FROM SHOULD be set to the mailbox owner's address.
Two new Sieve environment items are defined: 'imap.user' (the IMAP login ID of the user who caused the action) and 'imap.email' (the primary email address of that user). Both MUST be the empty string when accessed during normal final-delivery Sieve processing.
When a Sieve script is invoked through an IMAP event, the 'location' environment item is set to 'MS' (Message Store) and the 'phase' environment item is set to 'post'.
IANA registered 'IMAPSIEVE=' in the IMAP 4 Capabilities registry and 'imapsieve' in the Sieve Extensions registry. Five new Sieve Environment Items were registered: imap.cause, imap.mailbox, imap.changedflags, imap.user, and imap.email.
IANA registered '/shared/imapsieve/script' as both an IMAP METADATA Mailbox Entry Name (for per-mailbox script association) and an IMAP METADATA Server Entry Name (for a global script applying to all mailboxes lacking a mailbox-level entry).
Script processing loops can arise when a flag-change-triggered script uses imap4flags actions to further change flags. Implementations MUST prevent such loops; the recommended approach is that flag changes made by a flag-triggered script SHOULD NOT themselves trigger a new script invocation. Similarly, 'fileinto' must never trigger a subsequent script invocation to prevent cross-mailbox redirect loops.
This extension introduces side effects to IMAP commands that users may not anticipate. For example, a 'redirect' action in a global script could cause a user's appended draft message to be sent off-site when the user simply marks it for deletion. Script authors, especially those creating global scripts, must be careful about such unintended consequences.