RFC 6785
Support for Internet Message Access Protocol (IMAP) Events in Sieve
RFC 6785: Support for Internet Message Access Protocol (IMAP) Events in Sieve 💌
okay bestie, this is the spec that lets Sieve (the email filtering language) run when messages get created or changed on an IMAP server, not only when they get delivered 🦋
- Author: B. Leiba, Huawei Technologies
- Category: Standards Track
- Date: November 2012
- Updates: RFC 5228 (the base Sieve spec)
- Publisher: Internet Engineering Task Force (IETF)
- Request for Comments: 6785
- ISSN: 2070-1721
Abstract
Sieve is an email filtering language that could, in theory, plug into basically any point where an email message gets processed 🧚. The base spec only covers mail delivery. This doc explains how Sieve can also plug into the points in IMAP where messages get created or changed 💅. That means users or installations can add their own filtering, and with Sieve extensions you can even get things like notifications ✨. Since future Sieve extensions will need to say how they work with this one, this document updates the base Sieve spec, RFC 5228 🎀.
Status of This Memo
This is an Internet Standards Track document 🌸.
It's a product of the Internet Engineering Task Force (IETF). It reflects the consensus of the IETF community, got public review, and was approved for publication by the Internet Engineering Steering Group (IESG). More info on Internet Standards is in Section 2 of RFC 5741.
For the current status, any errata, and how to send feedback, check http://www.rfc-editor.org/info/rfc6785.
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) as they stand on the publication date. Please read these carefully, since they spell out your rights and restrictions for this document. Code Components pulled out of this document must include the Simplified BSD License text described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as the Simplified BSD License describes.
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
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 ....................................191. Introduction ✨
1.1. Overview
Some apps want to run Sieve filters [RFC5228] in places other than initial mail delivery 📬. This comes up a lot in diverse service setups, like when a client is only sometimes connected, sits on a high-latency or high-cost link, or runs on a limited-function device 📱. For those clients, it may be really important to use server capabilities for better performance and reliability, including what Sieve filtering offers (plus Sieve extensions like Notify [RFC5435]) 🫶.
This spec extends IMAP [RFC3501] so Sieve scripts can run whenever the IMAP server creates new messages or changes existing ones 🔥. It also defines how Sieve scripts handle those invocations. IMAP events in Sieve also need the following to be supported:
- IMAP Metadata [RFC5464], because Metadata is used to link scripts to IMAP mailboxes.
- Sieve Environment [RFC5183], because it gives Sieve scripts an important way to check the conditions they were invoked under.
- Sieve imap4flags [RFC5232], because it does important work on IMAP events related to flag changes.
Because future Sieve extensions have to say how they interact with this one (see Section 3.12), this document updates the base Sieve spec, RFC 5228 🌈.
1.2. Differences between IMAP Events and Mail Delivery
Running Sieve scripts somewhere besides initial mail delivery creates new situations 🙈. It changes which Sieve features apply, brings implementation challenges, and raises user interface issues. This section covers some of those differences, challenges, and issues.
At times other than message delivery, the delivery "envelope" information might not exist. With messages added through IMAP APPEND, there might be no way to even guess the intended recipient, and no concept of who "sent" the message 🤷♀️. Sieve actions that relate to contacting the sender, for example, won't apply.
IMAP events often come from user actions, and user interfaces allow bulk actions that aren't like one message arriving at a time. So a single user action, like drag-and-drop, can now start Sieve script processing on a huge number of messages at once 😭. Implementations will have to deal with situations like a "COPY" action or flag changes on dozens, or even thousands, of messages 💀.
Other issues might pop up as this extension gets deployed and people get experience with it 🎀.
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 IMAP events in Sieve support through the "imapsieve" capability 📣. A server that advertises "imapsieve" is saying it complies with this spec in every aspect 💅. The syntax of the "imapsieve" capability string is:
capability /= "IMAPSIEVE=" sieveurl-server
; <sieveurl-server> is defined in RFC 5804, Section 3Only one "imapsieve" capability string, specifying one sieveurl-server, is allowed to be present. The sieveurl-server tells clients which ManageSieve server to contact to manage the Sieve scripts linked to this IMAP server 🗂️.
The matching Sieve implementation uses the Sieve capability string "imapsieve", and Sieve scripts that depend on 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 link scripts to IMAP mailboxes and Environment gives Sieve scripts an important way to test the conditions they were invoked under 🔗. Even with that 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 dig into the IMAP commands and situations that IMAP events in Sieve affect 🔍. Not every Sieve action makes sense for messages touched by IMAP commands, so check Section 3 for the details 👑.
Here's the important bit: the base Sieve spec (see [RFC5228]) and its extensions define functions for scripts that run during initial mail delivery, so those definitions are naturally shaped by and limited to that context 🌈. This document extends those definitions for use during IMAP events. Because of that, Sieve functions may behave a bit differently in this extended context, though their extended behavior stays consistent with what the functions are for ✨.
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 📬
okay so a message can get added to a mailbox through the IMAP APPEND command 💌. If the server advertises "imapsieve", those brand new messages MUST trigger a Sieve script to run 🔥, subject to the settings you pick through Metadata (see Section 2.3.1) 🎀.
If the IMAP server also supports the IMAP MULTIAPPEND extension [RFC3502], APPEND can make more than one message at a time 🍓. Each message creation counts as its own separate event, so any applicable Sieve script gets called once for each message ✨.
2.2.2. The IMAP COPY Command 🦋
One or more messages can be added to a mailbox through IMAP COPY 🪄. In a server that advertises "imapsieve", new messages added this way MUST trigger the execution of a Sieve script, subject to the Metadata settings 💜.
2.2.3. Changes to IMAP Message Flags 🚩
Existing messages can get their flags changed in a bunch of different ways 💅, including:
- The FETCH command (may cause the
\Seenflag to be set). - The STORE command (may cause the
\Answered,\Deleted,\Draft,\Flagged, and\Seenflags to be set or reset, and may cause keywords to be set or reset). - 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 this: to avoid script loops 🔁, flag changes made as a result of a script that was itself invoked because of flag changes SHOULD NOT cause 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 applies:
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 lets clients 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] too 🫶, since Metadata is what associates scripts with IMAP mailboxes.
When an applicable event happens on an IMAP mailbox, if there is an IMAP metadata entry named "/shared/imapsieve/script" for the mailbox, that entry is used 📁. If there isn't one, but there is an IMAP metadata entry named "/shared/imapsieve/script" for the server, that entry is used instead (this gives you 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 gets invoked in response to the IMAP event 📜. If the value is empty, then no script is run 🫥. The choice of which metadata entry to use happens before anyone examines the contents of the entry 🔍. If the mailbox entry is selected and then turns out to be unusable or empty, the server entry is NOT used as a backup, so no script is run 💀.
This specifies the mechanism for "activating" a script for a given mailbox (or for all mailboxes), but it doesn't specify how to create, store, or validate 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 on the ManageSieve server, then no Sieve script will be invoked for IMAP Sieve events 🚫.
Only one Sieve script can currently be defined per mailbox 1️⃣, which gets rid of the complexity and possible ambiguity of coordinating the results of multiple scripts 🧠. Any sub-filtering is done in the Sieve script itself. For example, if you only need to deal with flag changes and not with new messages that were appended or copied, the Sieve script will still be invoked for all events, and the script is responsible for checking the event type ✅.
An extension could add support for multiple scripts, and that possibility is open 🚪. For example, you could have per-client scripts on a multi-client user's inbox, or per-user scripts on a mailbox that's shared among users 👯.
Because this metadata name is tied to the mailbox, there can be (and it's expected that there will be) different scripts for events on different mailboxes 🗂️. Honestly, most mailboxes will probably invoke no script at all 😴.
3. Applicable Sieve Actions and Interactions ✨
Some Sieve actions relate specifically to the delivery of mail, so not every action and extension makes sense when messages are created by other means or when changes are made to data associated with existing messages 📦. This section describes how the 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, the interactions noted in the individual specifications apply and must be considered 🧩.
3.1. The Implicit Keep 🛡️
For every case that falls under IMAP events in Sieve, the implicit keep means 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 every case that falls under IMAP events in Sieve. Its behavior is the same as described for the implicit keep in Section 3.1 🎀.
3.3. The "fileinto" Action 📂
If the Sieve implementation supports the "fileinto" action, that action is applicable in every case that falls 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 the base Sieve specification says ✂️.
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 every case, fileinto always creates a new message, separate from the original 🐥.
The "fileinto" action is not an IMAP APPEND or COPY, so it 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 every case that falls 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 the base Sieve specification says 🧾.
It's possible that a message processed this way doesn't have the information needed to be redirected properly 🙃. It might lack necessary header information, and there might not be appropriate information for the MAIL FROM command. In those cases, the "redirect" action uses message submission [RFC6409], and it's 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 every case that falls 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 every case that falls under IMAP events in Sieve 📣. The result is that the requested notification is sent, and the message is otherwise handled as it normally would 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 don't apply to the "keep" action (explicit or implicit). See Section 3.1 🔒.
3.8. The "setflag", "deleteflag", and "removeflag" Actions 🚩
Implementations of IMAP events in Sieve MUST also support the imap4flags extension [RFC5232], and all the actions associated with it apply to any case that falls under IMAP events in Sieve 💖.
It's also worth noting that the "hasflag" test defined in the imap4flags extension might be especially useful in scripts triggered by flag changes, since "hasflag" will see the new, changed flags 👀. The flag changes behave as though a client had made the change 🧚♀️.
As explained above, to avoid script loops 🔁, flag changes 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 🎀
okay so if the MIME Part Tests extension [RFC5703] is available, you get to use all of its functions 💅 BUT any changes you make to the message with the "replace" or "enclose" action MUST be considered transient 🫣 They only work with actions like "redirect" and "fileinto". Messages in IMAP mailboxes are immutable (they can't be edited in place), so these changes don't apply to 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 work in every case that falls under IMAP events in Sieve ✨
3.11. Inapplicable Actions 🙈
these actions and extensions don't apply to ANY case under IMAP events in Sieve, because they're built to respond to a brand new email being delivered. If they show up in the "require" control or get used in an IMAP event, that MUST result in an error condition that ends the Sieve script 💀
reject [RFC5228]
ereject [RFC5429]
vacation [RFC5230]future extensions that are built to respond to a new email being delivered won't apply here either 🦋
3.12. Future Sieve Actions 🔮
like I said above, future extensions that respond to new-message delivery won't apply to this extension, because this one doesn't act at new-message delivery time at all 🙅♀️
in general though, future extensions to Sieve that define new actions MUST specify how those actions apply to this specification 🫶
4. Interaction with Sieve Environment 🌈
4.1. Base Sieve Environment Items: location and phase 💖
the Sieve Environment extension defines a bunch of standard environment items (see [RFC5183], Section 4.1). Two of them change when the script runs through an IMAP event 👀
the value of "location" is set to "MS", which means evaluation is happening in a Message Store 🏬
the value of "phase" is set to "post", which means processing happens after final delivery (or maybe instead of it, in the case of APPEND) 🍓
4.2. New Sieve Environment Items: imap.user and imap.email 🔥
normally, when Sieve is used for final delivery, there's no identity for the "filer" (the user who's creating or changing the message). But here there IS one, and a Sieve script might want to access it 😭
implementations MUST set and make available two new environment items:
- "imap.user" is the identity (login ID) of the IMAP user who caused the action. This MUST be the empty string if it's accessed during normal (final delivery) Sieve processing.
- "imap.email" is the primary email address of the IMAP user who 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's accessed during normal (final delivery) Sieve processing.
4.3. New Sieve Environment Item: imap.cause 🎀
every mailbox uses one single script for all the change conditions in this document (append, copy, flag changes). To make that work, the implementation MUST set the Environment [RFC5183] item "imap.cause", which holds the name of the action that caused the script to run. Its value is one of these:
- APPEND (for invocations resulting from APPEND commands)
- COPY (for invocations resulting from COPY commands)
- FLAG (for invocations resulting from flag changes)
future extensions might define new events and therefore new causes ✨ Those extensions will come with their own capability strings, and their events will only show up when those capabilities are requested. Scripts that don't request those capabilities won't see those events and won't run into 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 the affected message is in (for existing messages), or the mailbox it's targeted to be stored into (for new messages). The value of this item is fixed when the script begins, and it MUST NOT change as a result of any action, like "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 changed. If the script wasn't invoked because of flag changes, the value of this item MUST be the empty string. The script won't be able to tell from this item whether the flags were set or reset, but it can use the "hasflag" test to check the current value 🧐 See example 2 in Section 5 for 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, plus any such test defined in extensions) are either inapplicable or have serious interoperability issues when they run at any time other than final delivery 😱 So envelope tests MUST NOT be permitted in the cases described here, and their use MUST generate a runtime error.
this extension doesn't change how other tests or comparisons in the Sieve base specification work 🫶
5. Examples 🍓
Example 1:
if a new message is added to the "ActionItems" mailbox, a copy gets 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 runs 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 gets sent using the Sieve notify extension [RFC5435]. No notification gets 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";
}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 checking capabilities 🔍 (The untagged CAPABILITY response is split here for readability only, but it will be one response message in real life.)
C: A01 CAPABILITY
S: * CAPABILITY IMAP4rev1 AUTH=PLAIN UIDPLUS LIST-EXTENDED
ACL IMAPSIEVE=sieve://sieve.example.com MULTISEARCH
S: A01 OK done6. Security Considerations 🚨
okay this part is SERIOUS bestie 😤
it's possible to create script processing loops by having a Sieve script that's 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: if a script is invoked by flag changes, and that script changes the flags further, those flag changes SHOULD NOT trigger a Sieve script invocation 🛑
the "fileinto" action never results in a script being invoked. 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 happen. (Mailbox A responds to all COPY events by doing "fileinto B", and mailbox B responds to all COPY events by doing "fileinto A". Chaos 🌪️) In general, actions taken as a result of the Sieve script are not IMAP events and don't trigger Sieve script invocations themselves ✨
it's also possible to create 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 doesn't change any of that advice 📚
this extension adds side effects to IMAP commands that users and script authors might not expect, and that can get triggered accidentally by something the user thinks is totally harmless 😬 In particular, certain actions, like "redirect", can cause a message (like one a user appended to a mailbox) to be sent out 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 (maybe an unencrypted draft) and then marks it for deletion, it could be really surprising to find out that the message got sent off site 😱 Script authors need to be careful not to create these kinds of surprises, especially when writing global scripts 🫣
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>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 🎀
okay bestie, this one is the registration for the imap.user Sieve environment item 💖 Here's what it says:
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 ✨
next up is imap.email 💅 This one gives you the primary email address of the IMAP user who caused the action, and it's the same user you get from imap.user. So the two items are literally a matched set 🫶
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>7.4. Registration of IMAP METADATA Mailbox Entry Name 🦋
okay so the IMAP METADATA Mailbox Entry Registry at <http://www.iana.org/assignments/imap-metadata> got a new entry too 🌈 It was added under the METADATA extension [RFC5464], and the vibe is very "per-mailbox settings" 🍓
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 🌸
and then there's the server-level version in the IMAP METADATA Server Entry Registry, <http://www.iana.org/assignments/imap-metadata> again 🧚 It's also under [RFC5464], and it's the global fallback 🌟 The server-wide script runs for any mailbox on the server that doesn't have its own mailbox-level /shared/imapsieve/script entry. So the mailbox-level one wins when it's there, and the server one catches everything else 👑
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 💜
these are the must-read ones, the ones this doc is built on 🔥
- [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.
- [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 🌷
these ones are extra reading if you want to go deeper 🫧
- [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.
Author's Address 🎀
the author who wrote all of this, Barry Leiba from Huawei Technologies 🦋
Barry Leiba
Huawei Technologies
Phone: +1 646 827 0648
EMail: barryleiba@computer.org
URI: http://internetmessagingtechnology.org/📦 where this page comes from
- ietf: rfc6785 2012-11
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms