diff options
Diffstat (limited to 'doc/rfc/rfc6785.txt')
| -rw-r--r-- | doc/rfc/rfc6785.txt | 1123 |
1 files changed, 1123 insertions, 0 deletions
diff --git a/doc/rfc/rfc6785.txt b/doc/rfc/rfc6785.txt new file mode 100644 index 0000000..b9033f1 --- /dev/null +++ b/doc/rfc/rfc6785.txt @@ -0,0 +1,1123 @@ + + + + + + +Internet Engineering Task Force (IETF) B. Leiba +Request for Comments: 6785 Huawei Technologies +Updates: 5228 November 2012 +Category: Standards Track +ISSN: 2070-1721 + + + Support for Internet Message Access Protocol (IMAP) Events in Sieve + +Abstract + + Sieve defines an email filtering language that can, in principle, + plug into any point in the processing of an email message. As + defined in the base specification, it plugs into mail delivery. This + document defines how Sieve can plug into points in IMAP where + messages are created or changed, adding the option of user-defined or + installation-defined filtering (or, with Sieve extensions, features + such as notifications). Because this requires future Sieve + extensions to specify their interactions with this one, this document + updates the base Sieve specification, RFC 5228. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc6785. + + + + + + + + + + + + + + + + + +Leiba Standards Track [Page 1] + +RFC 6785 IMAP Events in Sieve November 2012 + + +Copyright Notice + + Copyright (c) 2012 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + +Table of Contents + + 1. Introduction ....................................................3 + 1.1. Overview ...................................................3 + 1.2. Differences between IMAP Events and Mail Delivery ..........4 + 1.3. Conventions Used in This Document ..........................5 + 2. The "IMAP Events in Sieve" Extension ............................5 + 2.1. The "imapsieve" Capability Strings .........................5 + 2.2. Existing IMAP Functions Affected by IMAP Events in Sieve ...5 + 2.2.1. The IMAP APPEND Command .............................6 + 2.2.2. The IMAP COPY Command ...............................6 + 2.2.3. Changes to IMAP Message Flags .......................6 + 2.2.4. When Script Actions Set the \Deleted Flag ...........7 + 2.3. New Functions Defined by IMAP Events in Sieve ..............7 + 2.3.1. Interaction with Metadata ...........................7 + 3. Applicable Sieve Actions and Interactions .......................8 + 3.1. The Implicit Keep ..........................................9 + 3.2. The "keep" Action ..........................................9 + 3.3. The "fileinto" Action ......................................9 + 3.4. The "redirect" Action ......................................9 + 3.5. The "discard" Action ......................................10 + 3.6. The "notify" Action .......................................10 + 3.7. The "addheader" and "deleteheader" Actions ................10 + 3.8. The "setflag", "deleteflag", and "removeflag" Actions .....11 + 3.9. MIME Part Tests and Replacement ...........................11 + 3.10. spamtest and virustest ...................................11 + 3.11. Inapplicable Actions .....................................11 + 3.12. Future Sieve Actions .....................................12 + + + + + + + + +Leiba Standards Track [Page 2] + +RFC 6785 IMAP Events in Sieve November 2012 + + + 4. Interaction with Sieve Environment .............................12 + 4.1. Base Sieve Environment Items: location and phase ..........12 + 4.2. New Sieve Environment Items: imap.user and imap.email .....12 + 4.3. New Sieve Environment Item: imap.cause ....................13 + 4.4. New Sieve Environment Item: imap.mailbox ..................13 + 4.5. New Sieve Environment Item: imap.changedflags .............13 + 4.6. Interaction with Sieve Tests (Comparisons) ................13 + 5. Examples .......................................................14 + 6. Security Considerations ........................................15 + 7. IANA Considerations ............................................16 + 7.1. Registration of "imapsieve" IMAP Capability ...............16 + 7.2. Registration of "imapsieve" Sieve Extension ...............16 + 7.3. Registration of Sieve Environment Items ...................16 + 7.3.1. Registration of Sieve Environment Item: + imap.cause .........................................16 + 7.3.2. Registration of Sieve Environment Item: + imap.mailbox .......................................17 + 7.3.3. Registration of Sieve Environment Item: + imap.changedflags ..................................17 + 7.3.4. Registration of Sieve Environment Item: imap.user ..17 + 7.3.5. Registration of Sieve Environment Item: + imap.email .........................................17 + 7.4. Registration of IMAP METADATA Mailbox Entry Name ..........18 + 7.5. Registration of IMAP METADATA Server Entry Name ...........18 + 8. References .....................................................18 + 8.1. Normative References ......................................18 + 8.2. Informative References ....................................19 + +1. Introduction + +1.1. Overview + + Some applications have a need to apply Sieve filters [RFC5228] in + contexts other than initial mail delivery. This is especially true + in diverse service environments, such as when the client is + sporadically connected, is connected through a high-latency or + high-cost channel, or is on a limited-function device. For such + clients, it may be very important, for higher performance and + reliability, to take advantage of server capabilities, including + those provided by Sieve filtering (and Sieve extensions, such as + Notify [RFC5435]). + + + + + + + + + + +Leiba Standards Track [Page 3] + +RFC 6785 IMAP Events in Sieve November 2012 + + + This specification defines extensions to IMAP [RFC3501] to support + the invocation of Sieve scripts at times when the IMAP server creates + new messages or modifies existing ones. It also defines how Sieve + scripts will process these invocations. Support for IMAP events in + Sieve also requires support for the following: + + o IMAP Metadata [RFC5464], because Metadata is used to associate + scripts with IMAP mailboxes. + + o Sieve Environment [RFC5183], because it defines an important way + for Sieve scripts to test the conditions under which they have + been invoked. + + o Sieve imap4flags [RFC5232], because it provides important + functionality in handling IMAP events related to flag changes. + + Because this requires future Sieve extensions to specify their + interactions with this one (see Section 3.12), this document updates + the base Sieve specification, RFC 5228. + +1.2. Differences between IMAP Events and Mail Delivery + + Invoking Sieve scripts in a context other than initial mail delivery + introduces new situations; this changes the applicability of Sieve + features, creates implementation challenges, and creates user + interface issues. This section discusses some of those differences, + challenges, and issues. + + At times other than message delivery, delivery "envelope" information + might not be available. With messages added through IMAP APPEND, + there might be no way to even guess who the intended recipient is, + and no concept of who "sent" the message. Sieve actions that relate + to contacting the sender, for example, will not be applicable. + + Because IMAP events will often be triggered by user actions, and + because user interfaces allow bulk actions that differ from + individual message arrival, it now becomes possible for a single user + action, such as drag-and-drop, to initiate Sieve script processing on + a large number of messages at once. Implementations will have to + deal with such situations as a "COPY" action or flag changes on + dozens, or even thousands, of messages. + + Other issues might surface as this extension is deployed and + experience with it develops. + + + + + + + +Leiba Standards Track [Page 4] + +RFC 6785 IMAP Events in Sieve November 2012 + + +1.3. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + +2. The "IMAP Events in Sieve" Extension + +2.1. The "imapsieve" Capability Strings + + An IMAP server advertises support for IMAP events in Sieve through + the "imapsieve" capability. A server that advertises "imapsieve" is + claiming to be in compliance with this specification in all aspects. + The syntax of the "imapsieve" capability string is defined as + follows: + + capability /= "IMAPSIEVE=" sieveurl-server + ; <sieveurl-server> is defined in RFC 5804, Section 3 + + Only one "imapsieve" capability string, specifying one + sieveurl-server, is allowed to be present. The sieveurl-server + identifies the ManageSieve server that clients need to contact for + managing Sieve scripts associated with this IMAP server. + + The corresponding Sieve implementation uses the Sieve capability + string "imapsieve", and Sieve scripts that depend upon the IMAP + events MUST include that string in their "required" lists. + + Implementations that support IMAP events in Sieve MUST also support + IMAP Metadata [RFC5464] and Sieve Environment [RFC5183], because + Metadata is used to associate scripts with IMAP mailboxes and + Environment defines an important way for Sieve scripts to test the + conditions under which they have been invoked. Notwithstanding the + support requirement, scripts that directly use Environment MUST also + include its capability string in their "required" lists. + +2.2. Existing IMAP Functions Affected by IMAP Events in Sieve + + The subsections below describe in detail the IMAP commands and + situations on which IMAP events in Sieve have an effect. Not all + Sieve actions make sense in the case of messages affected by IMAP + commands. See Section 3 for details. + + It's important to note that since the base Sieve specification (see + [RFC5228]) and its extensions define functions for scripts that are + invoked during initial mail delivery, those function definitions are + necessarily tailored to and limited by that context. This document + extends those function definitions for use during IMAP events. By + + + +Leiba Standards Track [Page 5] + +RFC 6785 IMAP Events in Sieve November 2012 + + + nature of that, Sieve functions, in this extended context, may behave + somewhat differently, though their extended behavior will still be + consistent with the functions' goals. + + If more than one message is affected at the same time, each message + triggers the execution of a Sieve script separately. The scripts MAY + be run in parallel. + +2.2.1. The IMAP APPEND Command + + A message may be added to a mailbox through the IMAP APPEND command. + In a server that advertises "imapsieve", new messages added in this + way MUST trigger the execution of a Sieve script, subject to the + settings defined through Metadata (see Section 2.3.1). + + If the IMAP server also supports the IMAP MULTIAPPEND extension + [RFC3502], the APPEND command can create more than one message at a + time. In that case, each message creation is considered a separate + event, and any applicable Sieve script is called once for each + message. + +2.2.2. The IMAP COPY Command + + One or more messages may be added to a mailbox through the IMAP COPY + command. In a server that advertises "imapsieve", new messages added + in this way MUST trigger the execution of a Sieve script, subject to + the settings defined through Metadata. + +2.2.3. Changes to IMAP Message Flags + + One or more existing messages can have their flags changed in a + number of ways, including: + + o The FETCH command (may cause the \Seen flag to be set). + + o The STORE command (may cause the \Answered, \Deleted, \Draft, + \Flagged, and \Seen flags to be set or reset, and may cause + keywords to be set or reset). + + o The invocation of a Sieve script on an existing message, where the + script uses one of the actions defined in the imap4flags extension + [RFC5232] to change the flags. + + In a server that advertises "imapsieve", messages whose flags are + changed in any way (except as explained in the next sentence) MUST + trigger the execution of a Sieve script, subject to the settings + defined through Metadata. The exception is that in order to avoid + script loops, flag changes that are made as a result of a script that + + + +Leiba Standards Track [Page 6] + +RFC 6785 IMAP Events in Sieve November 2012 + + + was itself invoked because of flag changes SHOULD NOT result in a + further invocation of the script. In any case, implementations MUST + take steps to avoid such loops. + + For flag-change events, the Sieve script will see the message flags + as they are AFTER the changes. + +2.2.4. When Script Actions Set the \Deleted Flag + + There are times when the actions "fileinto" (see Section 3.3), + "redirect" (see Section 3.4), and "discard" (see Section 3.5) will + set the \Deleted flag on the message. In those cases, the following + apply: + + When the \Deleted flag is set by the script, a flag-change Sieve + script is not invoked. + + The implementation MAY then expunge the original message (WITHOUT + expunging other messages in the mailbox). Alternatively, it might + have expunges batched or done by a user. (It might be helpful to + allow the user to make this choice through a preference.) + + If the server does the expunge, the effect is as though a client had + flagged the message and done a UID EXPUNGE (see [RFC4315]) on the + affected message(s) only. Handling it this way allows clients to + handle messages consistently and avoids hidden changes that might + invalidate their message caches. + +2.3. New Functions Defined by IMAP Events in Sieve + +2.3.1. Interaction with Metadata + + Support for IMAP events in Sieve requires support for IMAP Metadata + [RFC5464] as well, since the latter is used to associate scripts with + IMAP mailboxes. + + When an applicable event occurs on an IMAP mailbox, if there is an + IMAP metadata entry named "/shared/imapsieve/script" for the mailbox, + that entry is used. If there is not, but there is an IMAP metadata + entry named "/shared/imapsieve/script" for the server, that entry is + used (providing a way to define a global script for all mailboxes on + a server). If neither entry exists, then no script will be invoked. + + If a "/shared/imapsieve/script" metadata entry was selected above, + its value is used as the name of the Sieve script that will be + invoked in response to the IMAP event. If the value is empty, then + no script is run. The selection of which metadata entry to use + + + + +Leiba Standards Track [Page 7] + +RFC 6785 IMAP Events in Sieve November 2012 + + + happens before any examination of the contents of the entry. If the + mailbox entry is selected and is then found to be unusable or empty, + the server entry is not used as a backup: no script is run. + + This specifies the mechanism for "activating" a script for a given + mailbox (or for all mailboxes) but does not specify a mechanism for + creating, storing, or validating the script. Implementations MUST + support ManageSieve [RFC5804] and can use the PUTSCRIPT command to + store the script without using the SETACTIVE command to activate it. + + Script names used in "/shared/imapsieve/script" metadata entries are + the script names used on the corresponding ManageSieve server. If a + "/shared/imapsieve/script" metadata entry contains a script name that + doesn't exist in the ManageSieve server, then no Sieve script will be + invoked for IMAP Sieve events. + + Only one Sieve script may currently be defined per mailbox, + eliminating the complexity and possible ambiguity involved with + coordinating the results of multiple scripts. Any sub-filtering is + done in the Sieve script. For example, if it's only necessary to + deal with flag changes, but not with new messages appended or copied, + the Sieve script will still be invoked for all events, and the script + is responsible for checking the event type. + + The possibility is open for an extension to add support for multiple + scripts -- for example, per-client scripts on a multi-client user's + inbox, or per-user scripts on a mailbox that is shared among users. + + Because this metadata name is associated with the mailbox, there can + (and it's expected that there will) be different scripts associated + with events for different mailboxes. Indeed, most mailboxes will + probably invoke no script at all. + +3. Applicable Sieve Actions and Interactions + + Since some Sieve actions relate specifically to the delivery of mail, + not all actions and extensions make sense when the messages are + created by other means or when changes are made to data associated + with existing messages. This section describes how actions in the + base Sieve specification, and those in extensions known at the time + of this writing, relate to this specification. + + In addition to what is specified here, interactions noted in the + individual specifications apply and must be considered. + + + + + + + +Leiba Standards Track [Page 8] + +RFC 6785 IMAP Events in Sieve November 2012 + + +3.1. The Implicit Keep + + For all cases that fall under IMAP events in Sieve, the implicit keep + means that the message is treated as it would have been if no Sieve + script were run. For APPEND and COPY, the message is stored into the + target mailbox normally. For flag changes, the message is left in + the mailbox. If actions have been taken that change the message, + those changes are considered transient and MUST NOT be retained for + any "keep" action (because IMAP messages are immutable). No error is + generated, but the original message, without the changes, is kept. + +3.2. The "keep" Action + + The "keep" action is applicable in all cases that fall under IMAP + events in Sieve. Its behavior is as described for implicit keep, in + Section 3.1. + +3.3. The "fileinto" Action + + If the Sieve implementation supports the "fileinto" action, that + action is applicable in all cases that fall under IMAP events in + Sieve. If the "copy" extension [RFC3894] is available and the :copy + option is specified, the implicit keep is retained; otherwise, + fileinto cancels the implicit keep, as specified in the base Sieve + specification. + + For APPEND and COPY, the message is stored into the fileinto mailbox + IN ADDITION TO the original target mailbox. For flag changes, the + message is COPIED into the fileinto mailbox, without removing the + original. In all cases, fileinto always creates a new message, + separate from the original. + + The "fileinto" action is not an IMAP APPEND or COPY and therefore + does not result in a subsequent event (see also the Security + Considerations, Section 6). + + If a "keep" action is not also in effect, the original message is + then marked with the \Deleted flag (see Section 2.2.4). + +3.4. The "redirect" Action + + The "redirect" action is applicable in all cases that fall under IMAP + events in Sieve. It causes the message to be sent, as specified in + the base Sieve specification, to the designated address. If the + "copy" extension [RFC3894] is available and the :copy option is + specified, the implicit keep is retained; otherwise, redirect cancels + the implicit keep, as specified in the base Sieve specification. + + + + +Leiba Standards Track [Page 9] + +RFC 6785 IMAP Events in Sieve November 2012 + + + It's possible that a message processed in this way does not have the + information necessary to be redirected properly. It might lack + necessary header information, and there might not be appropriate + information for the MAIL FROM command. In such cases, the "redirect" + action uses message submission [RFC6409], and it is up to the Sieve + engine to supply the missing information. The redirect address is, + of course, used for the "RCPT TO", and the "MAIL FROM" SHOULD be set + to the address of the owner of the mailbox. The message submission + server is allowed, according to the message submission protocol, to + perform necessary fix-up to the message (see Section 8 of RFC 6409). + It can also reject the submission attempt if the message is too + ill-formed for submission. + + For APPEND and COPY, the message is stored into the target mailbox in + addition to being redirected. For flag changes, the message remains + in its original mailbox. + + If a "keep" action is not also in effect, the original message is + then marked with the \Deleted flag (see Section 2.2.4). + +3.5. The "discard" Action + + The "discard" action is applicable in all cases that fall under IMAP + events in Sieve. For APPEND and COPY, the message is first stored + into the target mailbox. If an explicit "keep" action is also in + effect, the "discard" action now does nothing. Otherwise, the + original message is then marked with the \Deleted flag (see + Section 2.2.4). + +3.6. The "notify" Action + + If the Sieve notify extension [RFC5435] is available, the "notify" + action is applicable in all cases that fall under IMAP events in + Sieve. The result is that the requested notification is sent and + that the message is otherwise handled as it would normally have been. + +3.7. The "addheader" and "deleteheader" Actions + + If the editheader extension [RFC5293] is available, it can be used to + make transient changes to header fields, which aren't saved in place, + such as for "redirect" or "fileinto" actions. Because messages in + IMAP mailboxes are immutable, such changes are not applicable for the + "keep" action (explicit or implicit). See Section 3.1. + + + + + + + + +Leiba Standards Track [Page 10] + +RFC 6785 IMAP Events in Sieve November 2012 + + +3.8. The "setflag", "deleteflag", and "removeflag" Actions + + Implementations of IMAP events in Sieve MUST also support the + imap4flags extension [RFC5232], and the actions associated with it + are all applicable to any case that falls under IMAP events in Sieve. + + It is worth noting also that the "hasflag" test that is defined in + the imap4flags extension might be particularly useful in scripts + triggered by flag changes ("hasflag" will see the new, changed + flags). The flag changes behave as though a client had made the + change. + + As explained above, in order to avoid script loops, flag changes that + are made as a result of a script that was itself invoked because of + flag changes SHOULD NOT result in another script invocation. In any + case, implementations MUST take steps to avoid such loops. + +3.9. MIME Part Tests and Replacement + + If the MIME Part Tests extension [RFC5703] is available, all of its + functions can be used, but any changes made to the message, using the + "replace" or "enclose" action, MUST be considered transient and are + only applicable with actions such as "redirect" and "fileinto". + Because messages in IMAP mailboxes are immutable, such changes are + not applicable for the "keep" action (explicit or implicit). See + Section 3.1. + +3.10. spamtest and virustest + + If the spamtest and virustest extensions [RFC5235] are available, + they are applicable in all cases that fall under IMAP events in + Sieve. + +3.11. Inapplicable Actions + + The following actions and extensions are not applicable to any case + that falls under IMAP events in Sieve, because they are specifically + designed to respond to delivery of a new email message. Their + appearance in the "require" control or their use in an IMAP event + MUST result in an error condition that will terminate the Sieve + script: + + reject [RFC5228] + + ereject [RFC5429] + + vacation [RFC5230] + + + + +Leiba Standards Track [Page 11] + +RFC 6785 IMAP Events in Sieve November 2012 + + + Future extensions that are specifically designed to respond to + delivery of a new email message will likewise not be applicable to + this extension. + +3.12. Future Sieve Actions + + As noted above, future extensions that are specifically designed to + respond to delivery of a new email message will not be applicable to + this extension, because this extension does not involve acting at + new-message delivery time. + + In general, future extensions to Sieve that define new actions MUST + specify the applicability of those actions to this specification. + +4. Interaction with Sieve Environment + +4.1. Base Sieve Environment Items: location and phase + + The Sieve Environment extension defines a set of standard environment + items (see [RFC5183], Section 4.1). Two of those items are affected + when the script is invoked through an IMAP event. + + The value of "location" is set to "MS" -- evaluation is being + performed by a Message Store. + + The value of "phase" is set to "post" -- processing is taking place + after (or perhaps instead of, in the case of APPEND) final delivery. + +4.2. New Sieve Environment Items: imap.user and imap.email + + In the normal case, when Sieve is used in final delivery, there is no + identity for the "filer" -- the user who is creating or changing the + message. In this case, there is such an identity, and a Sieve script + might want to access that identity. + + Implementations MUST set and make available two new environment + items: + + "imap.user" -- the identity (login ID) of the IMAP user that caused + the action. This MUST be the empty string if it is accessed during + normal (final delivery) Sieve processing. + + "imap.email" -- the primary email address of the IMAP user that + caused the action (the user identified by "imap.user"). In some + implementations, "imap.user" and "imap.email" might have the same + value. This MUST be the empty string if it is accessed during normal + (final delivery) Sieve processing. + + + + +Leiba Standards Track [Page 12] + +RFC 6785 IMAP Events in Sieve November 2012 + + +4.3. New Sieve Environment Item: imap.cause + + Each mailbox uses a single script for all the change conditions + described in this document (append, copy, flag changes). To support + that, the implementation MUST set the Environment [RFC5183] item + "imap.cause", which contains the name of the action that caused the + script to be invoked. Its value is one of the following: + + o APPEND (for invocations resulting from APPEND commands) + + o COPY (for invocations resulting from COPY commands) + + o FLAG (for invocations resulting from flag changes) + + Future extensions might define new events and, thus, new causes. + Such extensions will come with their own capability strings, and the + events they define will only be presented when their capabilities are + requested. Scripts that do not request those capabilities will not + see those events and will not encounter the new cause strings. + +4.4. New Sieve Environment Item: imap.mailbox + + The implementation MUST set the Environment [RFC5183] item + "imap.mailbox" to the name of the mailbox that the affected message + is in, in the case of existing messages, or is targeted to be stored + into, in the case of new messages. The value of this item is fixed + when the script begins, and, in particular, MUST NOT change as a + result of any action, such as "fileinto". + +4.5. New Sieve Environment Item: imap.changedflags + + If the script was invoked because of flag changes to an existing + message, the implementation MUST set the Environment [RFC5183] item + "imap.changedflags" to the name(s) of the flag(s) that have changed. + If the script was not invoked because of flag changes, the value of + this item MUST be the empty string. The script will not know from + this item whether the flags have been set or reset, but it can use + the "hasflag" test to determine the current value. See example 2 in + Section 5 for an example of how this might be used. + +4.6. Interaction with Sieve Tests (Comparisons) + + Any tests against message envelope information, including the + "envelope" test in the Sieve base specification, as well as any such + test defined in extensions, are either inapplicable or have serious + interoperability issues when performed at other than final-delivery + time. Therefore, envelope tests MUST NOT be permitted in the cases + described here, and their use MUST generate a runtime error. + + + +Leiba Standards Track [Page 13] + +RFC 6785 IMAP Events in Sieve November 2012 + + + This extension does not affect the operation of other tests or + comparisons in the Sieve base specification. + +5. Examples + + Example 1: + If a new message is added to the "ActionItems" mailbox, a copy is + sent to the address "actionitems@example.com". + + require ["copy", "environment", "imapsieve"]; + + if anyof (environment :is "imap.cause" "APPEND", + environment :is "imap.cause" "COPY") { + if environment :is "imap.mailbox" "ActionItems" { + redirect :copy "actionitems@example.com"; + } + } + + Example 2: + If the script is called for any message with the \Flagged flag set + (tested through the imap4flags extension [RFC5232]) AND this script + invocation represents a change to that flag, then a notification is + sent using the Sieve notify extension [RFC5435]. No notification + will be sent, though, if we're called with an existing message that + already had that flag set. + + require ["enotify", "imap4flags", "variables", + "environment", "imapsieve"]; + + if environment :matches "imap.mailbox" "*" { + set "mailbox" "${1}"; + } + + if allof (hasflag "\\Flagged", + environment :contains "imap.changedflags" "\\Flagged") { + notify :message "Important message in ${mailbox}" + "xmpp:tim@example.com?message;subject=SIEVE"; + } + + + + + + + + + + + + + +Leiba Standards Track [Page 14] + +RFC 6785 IMAP Events in Sieve November 2012 + + + Example 3: + This shows an example IMAP CAPABILITY response when this extension is + supported. The client has done STARTTLS with the server and is now + inspecting capabilities. (The untagged CAPABILITY response is split + here for readability only, but it will be in one response message.) + + C: A01 CAPABILITY + S: * CAPABILITY IMAP4rev1 AUTH=PLAIN UIDPLUS LIST-EXTENDED + ACL IMAPSIEVE=sieve://sieve.example.com MULTISEARCH + S: A01 OK done + +6. Security Considerations + + It is possible to introduce script processing loops by having a Sieve + script that is triggered by flag changes use the actions defined in + the imap4flags extension [RFC5232]. Implementations MUST take steps + to prevent script loops. One way to avoid this problem is that if a + script is invoked by flag changes, and that script further changes + the flags, those flag changes SHOULD NOT trigger a Sieve script + invocation. + + The "fileinto" action never results in the invocation of a script. + If an implementation did invoke a script as the result of a fileinto, + as though an IMAP APPEND or COPY had been done, script loops could + result (mailbox A responds to all COPY events by doing "fileinto B", + and mailbox B responds to all COPY events by doing "fileinto A"). In + general, actions taken as a result of the Sieve script are not IMAP + events and do not themselves trigger Sieve script invocations. + + It is also possible to introduce loops through the "redirect" or + "notify" actions. See Sieve [RFC5228], Section 10, Sieve Notify + [RFC5435], Section 8, and the Security Considerations sections of the + applicable notification-method documents for loop-prevention + information. This extension does not change any of that advice. + + This extension introduces side effects to IMAP commands that users + and script authors might not be aware of and that can accidentally be + triggered by an operation that the user would expect to be innocuous. + In particular, certain actions, such as "redirect", can cause a + message (such as a message appended to a mailbox by a user) to be + sent to the Internet in response to something as simple as a flag + change. For example, a script might cause messages marked for + deletion to be sent to some off-site archiving service. If a user + appends a draft message to a mailbox (perhaps an unencrypted draft + message) and then marks it for deletion, it might be very surprising + to the user that the message is sent off site. Script authors need + to be careful not to create these kinds of surprises, especially when + creating global scripts. + + + +Leiba Standards Track [Page 15] + +RFC 6785 IMAP Events in Sieve November 2012 + + + Other security considerations are discussed in IMAP [RFC3501] and + Sieve [RFC5228], as well as in some of the other extension documents. + +7. IANA Considerations + +7.1. Registration of "imapsieve" IMAP Capability + + IANA has added "IMAPSIEVE=" to the IMAP 4 Capabilities registry + (<http://www.iana.org/assignments/imap4-capabilities>), according to + the IMAP 4 specification [RFC3501]. + +7.2. Registration of "imapsieve" Sieve Extension + + The following information has been added to the Sieve Extensions + registry (<http://www.iana.org/assignments/sieve-extensions>), + according to the Sieve specification [RFC5228]. + + Capability name: imapsieve + Description: Add Sieve processing for IMAP events. + RFC number: 6785 + Contact address: Sieve mailing list <sieve@ietf.org> + +7.3. Registration of Sieve Environment Items + + The following subsections register items in the Sieve Environment + Items registry + (<http://www.iana.org/assignments/sieve-environment-items>), + according to the Environment extension [RFC5183]. + +7.3.1. Registration of Sieve Environment Item: imap.cause + + Item name: imap.cause + Description: The name of the action that caused the script to be + invoked. Its value is one of the following: + + o APPEND (for invocations resulting from APPEND commands) + + o COPY (for invocations resulting from COPY commands) + + o FLAG (for invocations resulting from flag changes) + + RFC number: 6785 + Contact address: Sieve mailing list <sieve@ietf.org> + + + + + + + + +Leiba Standards Track [Page 16] + +RFC 6785 IMAP Events in Sieve November 2012 + + +7.3.2. Registration of Sieve Environment Item: imap.mailbox + + Item name: imap.mailbox + Description: The name of the mailbox that the affected message is in, + in the case of existing messages, or is targeted to be stored + into, in the case of new messages. The value of this item is + fixed when the script begins, and, in particular, MUST NOT change + as a result of any action, such as "fileinto". + RFC number: 6785 + Contact address: Sieve mailing list <sieve@ietf.org> + +7.3.3. Registration of Sieve Environment Item: imap.changedflags + + Item name: imap.changedflags + Description: If the script was invoked because of flag changes to an + existing message, this contains the name(s) of the flag(s) that + have changed. Otherwise, the value of this item MUST be the + empty string. + RFC number: 6785 + Contact address: Sieve mailing list <sieve@ietf.org> + +7.3.4. Registration of Sieve Environment Item: imap.user + + Item name: imap.user + Description: The identity (IMAP login ID) of the IMAP user that + caused the action. + RFC number: 6785 + Contact address: Sieve mailing list <sieve@ietf.org> + +7.3.5. Registration of Sieve Environment Item: imap.email + + Item name: imap.email + Description: The primary email address of the IMAP user that + caused the action (the user identified by "imap.user"). + RFC number: 6785 + Contact address: Sieve mailing list <sieve@ietf.org> + + + + + + + + + + + + + + + +Leiba Standards Track [Page 17] + +RFC 6785 IMAP Events in Sieve November 2012 + + +7.4. Registration of IMAP METADATA Mailbox Entry Name + + The following information has been added to the IMAP METADATA Mailbox + Entry Registry (<http://www.iana.org/assignments/imap-metadata>), + according to the METADATA extension [RFC5464]. + + Type: Mailbox + Name: /shared/imapsieve/script + Description: This entry name is used to define mailbox metadata + associated with IMAP events in Sieve for the associated mailbox. + Specifically, this specifies the Sieve script that will be invoked + when IMAP events occur on the specified mailbox. + Content-type: text/plain; charset=utf-8 + RFC number: 6785 + Contact address: Sieve mailing list <sieve@ietf.org> + +7.5. Registration of IMAP METADATA Server Entry Name + + The following information has been added to the IMAP METADATA Server + Entry Registry (<http://www.iana.org/assignments/imap-metadata>), + according to the METADATA extension [RFC5464]. + + Type: Server + Name: /shared/imapsieve/script + Description: This entry name is used to define metadata associated + globally with IMAP events in Sieve for the associated server. + Specifically, this specifies the Sieve script that will be invoked + when IMAP events occur on any mailbox in the server that does not + have its own mailbox-level /shared/imapsieve/script entry. + Content-type: text/plain; charset=utf-8 + RFC number: 6785 + Contact address: Sieve mailing list <sieve@ietf.org> + +8. References + +8.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - + VERSION 4rev1", RFC 3501, March 2003. + + [RFC3502] Crispin, M., "Internet Message Access Protocol (IMAP) - + MULTIAPPEND Extension", RFC 3502, March 2003. + + [RFC3894] Degener, J., "Sieve Extension: Copying Without Side + Effects", RFC 3894, October 2004. + + + +Leiba Standards Track [Page 18] + +RFC 6785 IMAP Events in Sieve November 2012 + + + [RFC5183] Freed, N., "Sieve Email Filtering: Environment Extension", + RFC 5183, May 2008. + + [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering + Language", RFC 5228, January 2008. + + [RFC5232] Melnikov, A., "Sieve Email Filtering: Imap4flags + Extension", RFC 5232, January 2008. + + [RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464, + February 2009. + + [RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely + Managing Sieve Scripts", RFC 5804, July 2010. + + [RFC6409] Gellens, R. and J. Klensin, "Message Submission for Mail", + STD 72, RFC 6409, November 2011. + +8.2. Informative References + + [RFC4315] Crispin, M., "Internet Message Access Protocol (IMAP) - + UIDPLUS extension", RFC 4315, December 2005. + + [RFC5230] Showalter, T. and N. Freed, "Sieve Email Filtering: + Vacation Extension", RFC 5230, January 2008. + + [RFC5235] Daboo, C., "Sieve Email Filtering: Spamtest and Virustest + Extensions", RFC 5235, January 2008. + + [RFC5293] Degener, J. and P. Guenther, "Sieve Email Filtering: + Editheader Extension", RFC 5293, August 2008. + + [RFC5429] Stone, A., "Sieve Email Filtering: Reject and Extended + Reject Extensions", RFC 5429, March 2009. + + [RFC5435] Melnikov, A., Leiba, B., Segmuller, W., and T. Martin, + "Sieve Email Filtering: Extension for Notifications", + RFC 5435, January 2009. + + [RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part + Tests, Iteration, Extraction, Replacement, and Enclosure", + RFC 5703, October 2009. + + + + + + + + + +Leiba Standards Track [Page 19] + +RFC 6785 IMAP Events in Sieve November 2012 + + +Author's Address + + Barry Leiba + Huawei Technologies + + Phone: +1 646 827 0648 + EMail: barryleiba@computer.org + URI: http://internetmessagingtechnology.org/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Leiba Standards Track [Page 20] + |