7Internet Engineering Task Force (IETF) B. Leiba
8Request for Comments: 6785 Huawei Technologies
9Updates: 5228 November 2012
10Category: Standards Track
14 Support for Internet Message Access Protocol (IMAP) Events in Sieve
18 Sieve defines an email filtering language that can, in principle,
19 plug into any point in the processing of an email message. As
20 defined in the base specification, it plugs into mail delivery. This
21 document defines how Sieve can plug into points in IMAP where
22 messages are created or changed, adding the option of user-defined or
23 installation-defined filtering (or, with Sieve extensions, features
24 such as notifications). Because this requires future Sieve
25 extensions to specify their interactions with this one, this document
26 updates the base Sieve specification, RFC 5228.
30 This is an Internet Standards Track document.
32 This document is a product of the Internet Engineering Task Force
33 (IETF). It represents the consensus of the IETF community. It has
34 received public review and has been approved for publication by the
35 Internet Engineering Steering Group (IESG). Further information on
36 Internet Standards is available in Section 2 of RFC 5741.
38 Information about the current status of this document, any errata,
39 and how to provide feedback on it may be obtained at
40 http://www.rfc-editor.org/info/rfc6785.
58Leiba Standards Track [Page 1]
60RFC 6785 IMAP Events in Sieve November 2012
65 Copyright (c) 2012 IETF Trust and the persons identified as the
66 document authors. All rights reserved.
68 This document is subject to BCP 78 and the IETF Trust's Legal
69 Provisions Relating to IETF Documents
70 (http://trustee.ietf.org/license-info) in effect on the date of
71 publication of this document. Please review these documents
72 carefully, as they describe your rights and restrictions with respect
73 to this document. Code Components extracted from this document must
74 include Simplified BSD License text as described in Section 4.e of
75 the Trust Legal Provisions and are provided without warranty as
76 described in the Simplified BSD License.
80 1. Introduction ....................................................3
81 1.1. Overview ...................................................3
82 1.2. Differences between IMAP Events and Mail Delivery ..........4
83 1.3. Conventions Used in This Document ..........................5
84 2. The "IMAP Events in Sieve" Extension ............................5
85 2.1. The "imapsieve" Capability Strings .........................5
86 2.2. Existing IMAP Functions Affected by IMAP Events in Sieve ...5
87 2.2.1. The IMAP APPEND Command .............................6
88 2.2.2. The IMAP COPY Command ...............................6
89 2.2.3. Changes to IMAP Message Flags .......................6
90 2.2.4. When Script Actions Set the \Deleted Flag ...........7
91 2.3. New Functions Defined by IMAP Events in Sieve ..............7
92 2.3.1. Interaction with Metadata ...........................7
93 3. Applicable Sieve Actions and Interactions .......................8
94 3.1. The Implicit Keep ..........................................9
95 3.2. The "keep" Action ..........................................9
96 3.3. The "fileinto" Action ......................................9
97 3.4. The "redirect" Action ......................................9
98 3.5. The "discard" Action ......................................10
99 3.6. The "notify" Action .......................................10
100 3.7. The "addheader" and "deleteheader" Actions ................10
101 3.8. The "setflag", "deleteflag", and "removeflag" Actions .....11
102 3.9. MIME Part Tests and Replacement ...........................11
103 3.10. spamtest and virustest ...................................11
104 3.11. Inapplicable Actions .....................................11
105 3.12. Future Sieve Actions .....................................12
114Leiba Standards Track [Page 2]
116RFC 6785 IMAP Events in Sieve November 2012
119 4. Interaction with Sieve Environment .............................12
120 4.1. Base Sieve Environment Items: location and phase ..........12
121 4.2. New Sieve Environment Items: imap.user and imap.email .....12
122 4.3. New Sieve Environment Item: imap.cause ....................13
123 4.4. New Sieve Environment Item: imap.mailbox ..................13
124 4.5. New Sieve Environment Item: imap.changedflags .............13
125 4.6. Interaction with Sieve Tests (Comparisons) ................13
126 5. Examples .......................................................14
127 6. Security Considerations ........................................15
128 7. IANA Considerations ............................................16
129 7.1. Registration of "imapsieve" IMAP Capability ...............16
130 7.2. Registration of "imapsieve" Sieve Extension ...............16
131 7.3. Registration of Sieve Environment Items ...................16
132 7.3.1. Registration of Sieve Environment Item:
133 imap.cause .........................................16
134 7.3.2. Registration of Sieve Environment Item:
135 imap.mailbox .......................................17
136 7.3.3. Registration of Sieve Environment Item:
137 imap.changedflags ..................................17
138 7.3.4. Registration of Sieve Environment Item: imap.user ..17
139 7.3.5. Registration of Sieve Environment Item:
140 imap.email .........................................17
141 7.4. Registration of IMAP METADATA Mailbox Entry Name ..........18
142 7.5. Registration of IMAP METADATA Server Entry Name ...........18
143 8. References .....................................................18
144 8.1. Normative References ......................................18
145 8.2. Informative References ....................................19
151 Some applications have a need to apply Sieve filters [RFC5228] in
152 contexts other than initial mail delivery. This is especially true
153 in diverse service environments, such as when the client is
154 sporadically connected, is connected through a high-latency or
155 high-cost channel, or is on a limited-function device. For such
156 clients, it may be very important, for higher performance and
157 reliability, to take advantage of server capabilities, including
158 those provided by Sieve filtering (and Sieve extensions, such as
170Leiba Standards Track [Page 3]
172RFC 6785 IMAP Events in Sieve November 2012
175 This specification defines extensions to IMAP [RFC3501] to support
176 the invocation of Sieve scripts at times when the IMAP server creates
177 new messages or modifies existing ones. It also defines how Sieve
178 scripts will process these invocations. Support for IMAP events in
179 Sieve also requires support for the following:
181 o IMAP Metadata [RFC5464], because Metadata is used to associate
182 scripts with IMAP mailboxes.
184 o Sieve Environment [RFC5183], because it defines an important way
185 for Sieve scripts to test the conditions under which they have
188 o Sieve imap4flags [RFC5232], because it provides important
189 functionality in handling IMAP events related to flag changes.
191 Because this requires future Sieve extensions to specify their
192 interactions with this one (see Section 3.12), this document updates
193 the base Sieve specification, RFC 5228.
1951.2. Differences between IMAP Events and Mail Delivery
197 Invoking Sieve scripts in a context other than initial mail delivery
198 introduces new situations; this changes the applicability of Sieve
199 features, creates implementation challenges, and creates user
200 interface issues. This section discusses some of those differences,
201 challenges, and issues.
203 At times other than message delivery, delivery "envelope" information
204 might not be available. With messages added through IMAP APPEND,
205 there might be no way to even guess who the intended recipient is,
206 and no concept of who "sent" the message. Sieve actions that relate
207 to contacting the sender, for example, will not be applicable.
209 Because IMAP events will often be triggered by user actions, and
210 because user interfaces allow bulk actions that differ from
211 individual message arrival, it now becomes possible for a single user
212 action, such as drag-and-drop, to initiate Sieve script processing on
213 a large number of messages at once. Implementations will have to
214 deal with such situations as a "COPY" action or flag changes on
215 dozens, or even thousands, of messages.
217 Other issues might surface as this extension is deployed and
218 experience with it develops.
226Leiba Standards Track [Page 4]
228RFC 6785 IMAP Events in Sieve November 2012
2311.3. Conventions Used in This Document
233 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
234 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
235 document are to be interpreted as described in [RFC2119].
2372. The "IMAP Events in Sieve" Extension
2392.1. The "imapsieve" Capability Strings
241 An IMAP server advertises support for IMAP events in Sieve through
242 the "imapsieve" capability. A server that advertises "imapsieve" is
243 claiming to be in compliance with this specification in all aspects.
244 The syntax of the "imapsieve" capability string is defined as
247 capability /= "IMAPSIEVE=" sieveurl-server
248 ; <sieveurl-server> is defined in RFC 5804, Section 3
250 Only one "imapsieve" capability string, specifying one
251 sieveurl-server, is allowed to be present. The sieveurl-server
252 identifies the ManageSieve server that clients need to contact for
253 managing Sieve scripts associated with this IMAP server.
255 The corresponding Sieve implementation uses the Sieve capability
256 string "imapsieve", and Sieve scripts that depend upon the IMAP
257 events MUST include that string in their "required" lists.
259 Implementations that support IMAP events in Sieve MUST also support
260 IMAP Metadata [RFC5464] and Sieve Environment [RFC5183], because
261 Metadata is used to associate scripts with IMAP mailboxes and
262 Environment defines an important way for Sieve scripts to test the
263 conditions under which they have been invoked. Notwithstanding the
264 support requirement, scripts that directly use Environment MUST also
265 include its capability string in their "required" lists.
2672.2. Existing IMAP Functions Affected by IMAP Events in Sieve
269 The subsections below describe in detail the IMAP commands and
270 situations on which IMAP events in Sieve have an effect. Not all
271 Sieve actions make sense in the case of messages affected by IMAP
272 commands. See Section 3 for details.
274 It's important to note that since the base Sieve specification (see
275 [RFC5228]) and its extensions define functions for scripts that are
276 invoked during initial mail delivery, those function definitions are
277 necessarily tailored to and limited by that context. This document
278 extends those function definitions for use during IMAP events. By
282Leiba Standards Track [Page 5]
284RFC 6785 IMAP Events in Sieve November 2012
287 nature of that, Sieve functions, in this extended context, may behave
288 somewhat differently, though their extended behavior will still be
289 consistent with the functions' goals.
291 If more than one message is affected at the same time, each message
292 triggers the execution of a Sieve script separately. The scripts MAY
2952.2.1. The IMAP APPEND Command
297 A message may be added to a mailbox through the IMAP APPEND command.
298 In a server that advertises "imapsieve", new messages added in this
299 way MUST trigger the execution of a Sieve script, subject to the
300 settings defined through Metadata (see Section 2.3.1).
302 If the IMAP server also supports the IMAP MULTIAPPEND extension
303 [RFC3502], the APPEND command can create more than one message at a
304 time. In that case, each message creation is considered a separate
305 event, and any applicable Sieve script is called once for each
3082.2.2. The IMAP COPY Command
310 One or more messages may be added to a mailbox through the IMAP COPY
311 command. In a server that advertises "imapsieve", new messages added
312 in this way MUST trigger the execution of a Sieve script, subject to
313 the settings defined through Metadata.
3152.2.3. Changes to IMAP Message Flags
317 One or more existing messages can have their flags changed in a
318 number of ways, including:
320 o The FETCH command (may cause the \Seen flag to be set).
322 o The STORE command (may cause the \Answered, \Deleted, \Draft,
323 \Flagged, and \Seen flags to be set or reset, and may cause
324 keywords to be set or reset).
326 o The invocation of a Sieve script on an existing message, where the
327 script uses one of the actions defined in the imap4flags extension
328 [RFC5232] to change the flags.
330 In a server that advertises "imapsieve", messages whose flags are
331 changed in any way (except as explained in the next sentence) MUST
332 trigger the execution of a Sieve script, subject to the settings
333 defined through Metadata. The exception is that in order to avoid
334 script loops, flag changes that are made as a result of a script that
338Leiba Standards Track [Page 6]
340RFC 6785 IMAP Events in Sieve November 2012
343 was itself invoked because of flag changes SHOULD NOT result in a
344 further invocation of the script. In any case, implementations MUST
345 take steps to avoid such loops.
347 For flag-change events, the Sieve script will see the message flags
348 as they are AFTER the changes.
3502.2.4. When Script Actions Set the \Deleted Flag
352 There are times when the actions "fileinto" (see Section 3.3),
353 "redirect" (see Section 3.4), and "discard" (see Section 3.5) will
354 set the \Deleted flag on the message. In those cases, the following
357 When the \Deleted flag is set by the script, a flag-change Sieve
358 script is not invoked.
360 The implementation MAY then expunge the original message (WITHOUT
361 expunging other messages in the mailbox). Alternatively, it might
362 have expunges batched or done by a user. (It might be helpful to
363 allow the user to make this choice through a preference.)
365 If the server does the expunge, the effect is as though a client had
366 flagged the message and done a UID EXPUNGE (see [RFC4315]) on the
367 affected message(s) only. Handling it this way allows clients to
368 handle messages consistently and avoids hidden changes that might
369 invalidate their message caches.
3712.3. New Functions Defined by IMAP Events in Sieve
3732.3.1. Interaction with Metadata
375 Support for IMAP events in Sieve requires support for IMAP Metadata
376 [RFC5464] as well, since the latter is used to associate scripts with
379 When an applicable event occurs on an IMAP mailbox, if there is an
380 IMAP metadata entry named "/shared/imapsieve/script" for the mailbox,
381 that entry is used. If there is not, but there is an IMAP metadata
382 entry named "/shared/imapsieve/script" for the server, that entry is
383 used (providing a way to define a global script for all mailboxes on
384 a server). If neither entry exists, then no script will be invoked.
386 If a "/shared/imapsieve/script" metadata entry was selected above,
387 its value is used as the name of the Sieve script that will be
388 invoked in response to the IMAP event. If the value is empty, then
389 no script is run. The selection of which metadata entry to use
394Leiba Standards Track [Page 7]
396RFC 6785 IMAP Events in Sieve November 2012
399 happens before any examination of the contents of the entry. If the
400 mailbox entry is selected and is then found to be unusable or empty,
401 the server entry is not used as a backup: no script is run.
403 This specifies the mechanism for "activating" a script for a given
404 mailbox (or for all mailboxes) but does not specify a mechanism for
405 creating, storing, or validating the script. Implementations MUST
406 support ManageSieve [RFC5804] and can use the PUTSCRIPT command to
407 store the script without using the SETACTIVE command to activate it.
409 Script names used in "/shared/imapsieve/script" metadata entries are
410 the script names used on the corresponding ManageSieve server. If a
411 "/shared/imapsieve/script" metadata entry contains a script name that
412 doesn't exist in the ManageSieve server, then no Sieve script will be
413 invoked for IMAP Sieve events.
415 Only one Sieve script may currently be defined per mailbox,
416 eliminating the complexity and possible ambiguity involved with
417 coordinating the results of multiple scripts. Any sub-filtering is
418 done in the Sieve script. For example, if it's only necessary to
419 deal with flag changes, but not with new messages appended or copied,
420 the Sieve script will still be invoked for all events, and the script
421 is responsible for checking the event type.
423 The possibility is open for an extension to add support for multiple
424 scripts -- for example, per-client scripts on a multi-client user's
425 inbox, or per-user scripts on a mailbox that is shared among users.
427 Because this metadata name is associated with the mailbox, there can
428 (and it's expected that there will) be different scripts associated
429 with events for different mailboxes. Indeed, most mailboxes will
430 probably invoke no script at all.
4323. Applicable Sieve Actions and Interactions
434 Since some Sieve actions relate specifically to the delivery of mail,
435 not all actions and extensions make sense when the messages are
436 created by other means or when changes are made to data associated
437 with existing messages. This section describes how actions in the
438 base Sieve specification, and those in extensions known at the time
439 of this writing, relate to this specification.
441 In addition to what is specified here, interactions noted in the
442 individual specifications apply and must be considered.
450Leiba Standards Track [Page 8]
452RFC 6785 IMAP Events in Sieve November 2012
4553.1. The Implicit Keep
457 For all cases that fall under IMAP events in Sieve, the implicit keep
458 means that the message is treated as it would have been if no Sieve
459 script were run. For APPEND and COPY, the message is stored into the
460 target mailbox normally. For flag changes, the message is left in
461 the mailbox. If actions have been taken that change the message,
462 those changes are considered transient and MUST NOT be retained for
463 any "keep" action (because IMAP messages are immutable). No error is
464 generated, but the original message, without the changes, is kept.
4663.2. The "keep" Action
468 The "keep" action is applicable in all cases that fall under IMAP
469 events in Sieve. Its behavior is as described for implicit keep, in
4723.3. The "fileinto" Action
474 If the Sieve implementation supports the "fileinto" action, that
475 action is applicable in all cases that fall under IMAP events in
476 Sieve. If the "copy" extension [RFC3894] is available and the :copy
477 option is specified, the implicit keep is retained; otherwise,
478 fileinto cancels the implicit keep, as specified in the base Sieve
481 For APPEND and COPY, the message is stored into the fileinto mailbox
482 IN ADDITION TO the original target mailbox. For flag changes, the
483 message is COPIED into the fileinto mailbox, without removing the
484 original. In all cases, fileinto always creates a new message,
485 separate from the original.
487 The "fileinto" action is not an IMAP APPEND or COPY and therefore
488 does not result in a subsequent event (see also the Security
489 Considerations, Section 6).
491 If a "keep" action is not also in effect, the original message is
492 then marked with the \Deleted flag (see Section 2.2.4).
4943.4. The "redirect" Action
496 The "redirect" action is applicable in all cases that fall under IMAP
497 events in Sieve. It causes the message to be sent, as specified in
498 the base Sieve specification, to the designated address. If the
499 "copy" extension [RFC3894] is available and the :copy option is
500 specified, the implicit keep is retained; otherwise, redirect cancels
501 the implicit keep, as specified in the base Sieve specification.
506Leiba Standards Track [Page 9]
508RFC 6785 IMAP Events in Sieve November 2012
511 It's possible that a message processed in this way does not have the
512 information necessary to be redirected properly. It might lack
513 necessary header information, and there might not be appropriate
514 information for the MAIL FROM command. In such cases, the "redirect"
515 action uses message submission [RFC6409], and it is up to the Sieve
516 engine to supply the missing information. The redirect address is,
517 of course, used for the "RCPT TO", and the "MAIL FROM" SHOULD be set
518 to the address of the owner of the mailbox. The message submission
519 server is allowed, according to the message submission protocol, to
520 perform necessary fix-up to the message (see Section 8 of RFC 6409).
521 It can also reject the submission attempt if the message is too
522 ill-formed for submission.
524 For APPEND and COPY, the message is stored into the target mailbox in
525 addition to being redirected. For flag changes, the message remains
526 in its original mailbox.
528 If a "keep" action is not also in effect, the original message is
529 then marked with the \Deleted flag (see Section 2.2.4).
5313.5. The "discard" Action
533 The "discard" action is applicable in all cases that fall under IMAP
534 events in Sieve. For APPEND and COPY, the message is first stored
535 into the target mailbox. If an explicit "keep" action is also in
536 effect, the "discard" action now does nothing. Otherwise, the
537 original message is then marked with the \Deleted flag (see
5403.6. The "notify" Action
542 If the Sieve notify extension [RFC5435] is available, the "notify"
543 action is applicable in all cases that fall under IMAP events in
544 Sieve. The result is that the requested notification is sent and
545 that the message is otherwise handled as it would normally have been.
5473.7. The "addheader" and "deleteheader" Actions
549 If the editheader extension [RFC5293] is available, it can be used to
550 make transient changes to header fields, which aren't saved in place,
551 such as for "redirect" or "fileinto" actions. Because messages in
552 IMAP mailboxes are immutable, such changes are not applicable for the
553 "keep" action (explicit or implicit). See Section 3.1.
562Leiba Standards Track [Page 10]
564RFC 6785 IMAP Events in Sieve November 2012
5673.8. The "setflag", "deleteflag", and "removeflag" Actions
569 Implementations of IMAP events in Sieve MUST also support the
570 imap4flags extension [RFC5232], and the actions associated with it
571 are all applicable to any case that falls under IMAP events in Sieve.
573 It is worth noting also that the "hasflag" test that is defined in
574 the imap4flags extension might be particularly useful in scripts
575 triggered by flag changes ("hasflag" will see the new, changed
576 flags). The flag changes behave as though a client had made the
579 As explained above, in order to avoid script loops, flag changes that
580 are made as a result of a script that was itself invoked because of
581 flag changes SHOULD NOT result in another script invocation. In any
582 case, implementations MUST take steps to avoid such loops.
5843.9. MIME Part Tests and Replacement
586 If the MIME Part Tests extension [RFC5703] is available, all of its
587 functions can be used, but any changes made to the message, using the
588 "replace" or "enclose" action, MUST be considered transient and are
589 only applicable with actions such as "redirect" and "fileinto".
590 Because messages in IMAP mailboxes are immutable, such changes are
591 not applicable for the "keep" action (explicit or implicit). See
5943.10. spamtest and virustest
596 If the spamtest and virustest extensions [RFC5235] are available,
597 they are applicable in all cases that fall under IMAP events in
6003.11. Inapplicable Actions
602 The following actions and extensions are not applicable to any case
603 that falls under IMAP events in Sieve, because they are specifically
604 designed to respond to delivery of a new email message. Their
605 appearance in the "require" control or their use in an IMAP event
606 MUST result in an error condition that will terminate the Sieve
618Leiba Standards Track [Page 11]
620RFC 6785 IMAP Events in Sieve November 2012
623 Future extensions that are specifically designed to respond to
624 delivery of a new email message will likewise not be applicable to
6273.12. Future Sieve Actions
629 As noted above, future extensions that are specifically designed to
630 respond to delivery of a new email message will not be applicable to
631 this extension, because this extension does not involve acting at
632 new-message delivery time.
634 In general, future extensions to Sieve that define new actions MUST
635 specify the applicability of those actions to this specification.
6374. Interaction with Sieve Environment
6394.1. Base Sieve Environment Items: location and phase
641 The Sieve Environment extension defines a set of standard environment
642 items (see [RFC5183], Section 4.1). Two of those items are affected
643 when the script is invoked through an IMAP event.
645 The value of "location" is set to "MS" -- evaluation is being
646 performed by a Message Store.
648 The value of "phase" is set to "post" -- processing is taking place
649 after (or perhaps instead of, in the case of APPEND) final delivery.
6514.2. New Sieve Environment Items: imap.user and imap.email
653 In the normal case, when Sieve is used in final delivery, there is no
654 identity for the "filer" -- the user who is creating or changing the
655 message. In this case, there is such an identity, and a Sieve script
656 might want to access that identity.
658 Implementations MUST set and make available two new environment
661 "imap.user" -- the identity (login ID) of the IMAP user that caused
662 the action. This MUST be the empty string if it is accessed during
663 normal (final delivery) Sieve processing.
665 "imap.email" -- the primary email address of the IMAP user that
666 caused the action (the user identified by "imap.user"). In some
667 implementations, "imap.user" and "imap.email" might have the same
668 value. This MUST be the empty string if it is accessed during normal
669 (final delivery) Sieve processing.
674Leiba Standards Track [Page 12]
676RFC 6785 IMAP Events in Sieve November 2012
6794.3. New Sieve Environment Item: imap.cause
681 Each mailbox uses a single script for all the change conditions
682 described in this document (append, copy, flag changes). To support
683 that, the implementation MUST set the Environment [RFC5183] item
684 "imap.cause", which contains the name of the action that caused the
685 script to be invoked. Its value is one of the following:
687 o APPEND (for invocations resulting from APPEND commands)
689 o COPY (for invocations resulting from COPY commands)
691 o FLAG (for invocations resulting from flag changes)
693 Future extensions might define new events and, thus, new causes.
694 Such extensions will come with their own capability strings, and the
695 events they define will only be presented when their capabilities are
696 requested. Scripts that do not request those capabilities will not
697 see those events and will not encounter the new cause strings.
6994.4. New Sieve Environment Item: imap.mailbox
701 The implementation MUST set the Environment [RFC5183] item
702 "imap.mailbox" to the name of the mailbox that the affected message
703 is in, in the case of existing messages, or is targeted to be stored
704 into, in the case of new messages. The value of this item is fixed
705 when the script begins, and, in particular, MUST NOT change as a
706 result of any action, such as "fileinto".
7084.5. New Sieve Environment Item: imap.changedflags
710 If the script was invoked because of flag changes to an existing
711 message, the implementation MUST set the Environment [RFC5183] item
712 "imap.changedflags" to the name(s) of the flag(s) that have changed.
713 If the script was not invoked because of flag changes, the value of
714 this item MUST be the empty string. The script will not know from
715 this item whether the flags have been set or reset, but it can use
716 the "hasflag" test to determine the current value. See example 2 in
717 Section 5 for an example of how this might be used.
7194.6. Interaction with Sieve Tests (Comparisons)
721 Any tests against message envelope information, including the
722 "envelope" test in the Sieve base specification, as well as any such
723 test defined in extensions, are either inapplicable or have serious
724 interoperability issues when performed at other than final-delivery
725 time. Therefore, envelope tests MUST NOT be permitted in the cases
726 described here, and their use MUST generate a runtime error.
730Leiba Standards Track [Page 13]
732RFC 6785 IMAP Events in Sieve November 2012
735 This extension does not affect the operation of other tests or
736 comparisons in the Sieve base specification.
741 If a new message is added to the "ActionItems" mailbox, a copy is
742 sent to the address "actionitems@example.com".
744 require ["copy", "environment", "imapsieve"];
746 if anyof (environment :is "imap.cause" "APPEND",
747 environment :is "imap.cause" "COPY") {
748 if environment :is "imap.mailbox" "ActionItems" {
749 redirect :copy "actionitems@example.com";
754 If the script is called for any message with the \Flagged flag set
755 (tested through the imap4flags extension [RFC5232]) AND this script
756 invocation represents a change to that flag, then a notification is
757 sent using the Sieve notify extension [RFC5435]. No notification
758 will be sent, though, if we're called with an existing message that
759 already had that flag set.
761 require ["enotify", "imap4flags", "variables",
762 "environment", "imapsieve"];
764 if environment :matches "imap.mailbox" "*" {
765 set "mailbox" "${1}";
768 if allof (hasflag "\\Flagged",
769 environment :contains "imap.changedflags" "\\Flagged") {
770 notify :message "Important message in ${mailbox}"
771 "xmpp:tim@example.com?message;subject=SIEVE";
786Leiba Standards Track [Page 14]
788RFC 6785 IMAP Events in Sieve November 2012
792 This shows an example IMAP CAPABILITY response when this extension is
793 supported. The client has done STARTTLS with the server and is now
794 inspecting capabilities. (The untagged CAPABILITY response is split
795 here for readability only, but it will be in one response message.)
798 S: * CAPABILITY IMAP4rev1 AUTH=PLAIN UIDPLUS LIST-EXTENDED
799 ACL IMAPSIEVE=sieve://sieve.example.com MULTISEARCH
8026. Security Considerations
804 It is possible to introduce script processing loops by having a Sieve
805 script that is triggered by flag changes use the actions defined in
806 the imap4flags extension [RFC5232]. Implementations MUST take steps
807 to prevent script loops. One way to avoid this problem is that if a
808 script is invoked by flag changes, and that script further changes
809 the flags, those flag changes SHOULD NOT trigger a Sieve script
812 The "fileinto" action never results in the invocation of a script.
813 If an implementation did invoke a script as the result of a fileinto,
814 as though an IMAP APPEND or COPY had been done, script loops could
815 result (mailbox A responds to all COPY events by doing "fileinto B",
816 and mailbox B responds to all COPY events by doing "fileinto A"). In
817 general, actions taken as a result of the Sieve script are not IMAP
818 events and do not themselves trigger Sieve script invocations.
820 It is also possible to introduce loops through the "redirect" or
821 "notify" actions. See Sieve [RFC5228], Section 10, Sieve Notify
822 [RFC5435], Section 8, and the Security Considerations sections of the
823 applicable notification-method documents for loop-prevention
824 information. This extension does not change any of that advice.
826 This extension introduces side effects to IMAP commands that users
827 and script authors might not be aware of and that can accidentally be
828 triggered by an operation that the user would expect to be innocuous.
829 In particular, certain actions, such as "redirect", can cause a
830 message (such as a message appended to a mailbox by a user) to be
831 sent to the Internet in response to something as simple as a flag
832 change. For example, a script might cause messages marked for
833 deletion to be sent to some off-site archiving service. If a user
834 appends a draft message to a mailbox (perhaps an unencrypted draft
835 message) and then marks it for deletion, it might be very surprising
836 to the user that the message is sent off site. Script authors need
837 to be careful not to create these kinds of surprises, especially when
838 creating global scripts.
842Leiba Standards Track [Page 15]
844RFC 6785 IMAP Events in Sieve November 2012
847 Other security considerations are discussed in IMAP [RFC3501] and
848 Sieve [RFC5228], as well as in some of the other extension documents.
8507. IANA Considerations
8527.1. Registration of "imapsieve" IMAP Capability
854 IANA has added "IMAPSIEVE=" to the IMAP 4 Capabilities registry
855 (<http://www.iana.org/assignments/imap4-capabilities>), according to
856 the IMAP 4 specification [RFC3501].
8587.2. Registration of "imapsieve" Sieve Extension
860 The following information has been added to the Sieve Extensions
861 registry (<http://www.iana.org/assignments/sieve-extensions>),
862 according to the Sieve specification [RFC5228].
864 Capability name: imapsieve
865 Description: Add Sieve processing for IMAP events.
867 Contact address: Sieve mailing list <sieve@ietf.org>
8697.3. Registration of Sieve Environment Items
871 The following subsections register items in the Sieve Environment
873 (<http://www.iana.org/assignments/sieve-environment-items>),
874 according to the Environment extension [RFC5183].
8767.3.1. Registration of Sieve Environment Item: imap.cause
878 Item name: imap.cause
879 Description: The name of the action that caused the script to be
880 invoked. Its value is one of the following:
882 o APPEND (for invocations resulting from APPEND commands)
884 o COPY (for invocations resulting from COPY commands)
886 o FLAG (for invocations resulting from flag changes)
889 Contact address: Sieve mailing list <sieve@ietf.org>
898Leiba Standards Track [Page 16]
900RFC 6785 IMAP Events in Sieve November 2012
9037.3.2. Registration of Sieve Environment Item: imap.mailbox
905 Item name: imap.mailbox
906 Description: The name of the mailbox that the affected message is in,
907 in the case of existing messages, or is targeted to be stored
908 into, in the case of new messages. The value of this item is
909 fixed when the script begins, and, in particular, MUST NOT change
910 as a result of any action, such as "fileinto".
912 Contact address: Sieve mailing list <sieve@ietf.org>
9147.3.3. Registration of Sieve Environment Item: imap.changedflags
916 Item name: imap.changedflags
917 Description: If the script was invoked because of flag changes to an
918 existing message, this contains the name(s) of the flag(s) that
919 have changed. Otherwise, the value of this item MUST be the
922 Contact address: Sieve mailing list <sieve@ietf.org>
9247.3.4. Registration of Sieve Environment Item: imap.user
927 Description: The identity (IMAP login ID) of the IMAP user that
930 Contact address: Sieve mailing list <sieve@ietf.org>
9327.3.5. Registration of Sieve Environment Item: imap.email
934 Item name: imap.email
935 Description: The primary email address of the IMAP user that
936 caused the action (the user identified by "imap.user").
938 Contact address: Sieve mailing list <sieve@ietf.org>
954Leiba Standards Track [Page 17]
956RFC 6785 IMAP Events in Sieve November 2012
9597.4. Registration of IMAP METADATA Mailbox Entry Name
961 The following information has been added to the IMAP METADATA Mailbox
962 Entry Registry (<http://www.iana.org/assignments/imap-metadata>),
963 according to the METADATA extension [RFC5464].
966 Name: /shared/imapsieve/script
967 Description: This entry name is used to define mailbox metadata
968 associated with IMAP events in Sieve for the associated mailbox.
969 Specifically, this specifies the Sieve script that will be invoked
970 when IMAP events occur on the specified mailbox.
971 Content-type: text/plain; charset=utf-8
973 Contact address: Sieve mailing list <sieve@ietf.org>
9757.5. Registration of IMAP METADATA Server Entry Name
977 The following information has been added to the IMAP METADATA Server
978 Entry Registry (<http://www.iana.org/assignments/imap-metadata>),
979 according to the METADATA extension [RFC5464].
982 Name: /shared/imapsieve/script
983 Description: This entry name is used to define metadata associated
984 globally with IMAP events in Sieve for the associated server.
985 Specifically, this specifies the Sieve script that will be invoked
986 when IMAP events occur on any mailbox in the server that does not
987 have its own mailbox-level /shared/imapsieve/script entry.
988 Content-type: text/plain; charset=utf-8
990 Contact address: Sieve mailing list <sieve@ietf.org>
9948.1. Normative References
996 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
997 Requirement Levels", BCP 14, RFC 2119, March 1997.
999 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL -
1000 VERSION 4rev1", RFC 3501, March 2003.
1002 [RFC3502] Crispin, M., "Internet Message Access Protocol (IMAP) -
1003 MULTIAPPEND Extension", RFC 3502, March 2003.
1005 [RFC3894] Degener, J., "Sieve Extension: Copying Without Side
1006 Effects", RFC 3894, October 2004.
1010Leiba Standards Track [Page 18]
1012RFC 6785 IMAP Events in Sieve November 2012
1015 [RFC5183] Freed, N., "Sieve Email Filtering: Environment Extension",
1018 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering
1019 Language", RFC 5228, January 2008.
1021 [RFC5232] Melnikov, A., "Sieve Email Filtering: Imap4flags
1022 Extension", RFC 5232, January 2008.
1024 [RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464,
1027 [RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely
1028 Managing Sieve Scripts", RFC 5804, July 2010.
1030 [RFC6409] Gellens, R. and J. Klensin, "Message Submission for Mail",
1031 STD 72, RFC 6409, November 2011.
10338.2. Informative References
1035 [RFC4315] Crispin, M., "Internet Message Access Protocol (IMAP) -
1036 UIDPLUS extension", RFC 4315, December 2005.
1038 [RFC5230] Showalter, T. and N. Freed, "Sieve Email Filtering:
1039 Vacation Extension", RFC 5230, January 2008.
1041 [RFC5235] Daboo, C., "Sieve Email Filtering: Spamtest and Virustest
1042 Extensions", RFC 5235, January 2008.
1044 [RFC5293] Degener, J. and P. Guenther, "Sieve Email Filtering:
1045 Editheader Extension", RFC 5293, August 2008.
1047 [RFC5429] Stone, A., "Sieve Email Filtering: Reject and Extended
1048 Reject Extensions", RFC 5429, March 2009.
1050 [RFC5435] Melnikov, A., Leiba, B., Segmuller, W., and T. Martin,
1051 "Sieve Email Filtering: Extension for Notifications",
1052 RFC 5435, January 2009.
1054 [RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part
1055 Tests, Iteration, Extraction, Replacement, and Enclosure",
1056 RFC 5703, October 2009.
1066Leiba Standards Track [Page 19]
1068RFC 6785 IMAP Events in Sieve November 2012
1076 Phone: +1 646 827 0648
1077 EMail: barryleiba@computer.org
1078 URI: http://internetmessagingtechnology.org/
1122Leiba Standards Track [Page 20]