idnits 2.17.1 draft-ietf-sieve-imap-sieve-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. -- The draft header indicates that this document updates RFC5228, but the abstract doesn't seem to directly say this. It does mention RFC5228 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC5228, updated by this document, for RFC5378 checks: 2005-05-09) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 14, 2012) is 4240 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 3501 (Obsoleted by RFC 9051) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Sieve Working Group B. Leiba 3 Internet-Draft Huawei Technologies 4 Updates: 5228 (if approved) September 14, 2012 5 Intended status: Standards Track 6 Expires: March 18, 2013 8 Support for Internet Message Access Protocol (IMAP) Events in Sieve 9 draft-ietf-sieve-imap-sieve-09 11 Abstract 13 Sieve defines an email filtering language that can, in principle, 14 plug into any point in the processing of an email message. As 15 defined in the base specification, it plugs into mail delivery. This 16 document defines how Sieve can plug into points in the IMAP protocol 17 where messages are created or changed, adding the option of user- 18 defined or installation-defined filtering (or, with Sieve extensions, 19 features such as notifications). Because this requires future Sieve 20 extensions to specify their interactions with this one, this document 21 updates the base Sieve specification, RFC 5228. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on March 18, 2013. 40 Copyright Notice 42 Copyright (c) 2012 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 1.2. Differences Between IMAP Events and Mail Delivery . . . . 4 60 1.3. Conventions used in this document . . . . . . . . . . . . 5 62 2. The IMAP Events in Sieve Extension . . . . . . . . . . . . 6 63 2.1. The "imapsieve" Capability Strings . . . . . . . . . . . . 6 64 2.2. Existing IMAP Functions Affected by IMAP events in 65 Sieve . . . . . . . . . . . . . . . . . . . . . . . . . . 6 66 2.2.1. The IMAP APPEND Command . . . . . . . . . . . . . . . . . 7 67 2.2.2. The IMAP COPY Command . . . . . . . . . . . . . . . . . . 7 68 2.2.3. Changes to IMAP Message Flags . . . . . . . . . . . . . . 7 69 2.2.4. When Script Actions Set the \Deleted Flag . . . . . . . . 8 70 2.3. New Functions Defined by IMAP events in Sieve . . . . . . 8 71 2.3.1. Interaction with Metadata . . . . . . . . . . . . . . . . 8 73 3. Applicable Sieve Actions and Interactions . . . . . . . . 10 74 3.1. The Implicit Keep . . . . . . . . . . . . . . . . . . . . 10 75 3.2. The Keep Action . . . . . . . . . . . . . . . . . . . . . 10 76 3.3. The Fileinto Action . . . . . . . . . . . . . . . . . . . 10 77 3.4. The Redirect Action . . . . . . . . . . . . . . . . . . . 11 78 3.5. The Discard Action . . . . . . . . . . . . . . . . . . . . 11 79 3.6. The Notify Action . . . . . . . . . . . . . . . . . . . . 11 80 3.7. The Addheader and Deleteheader Actions . . . . . . . . . . 12 81 3.8. The Setflag, Deleteflag, and Removeflag Actions . . . . . 12 82 3.9. MIME Part Tests and Replacement . . . . . . . . . . . . . 12 83 3.10. Spamtest and Virustest . . . . . . . . . . . . . . . . . . 12 84 3.11. Inapplicable Actions . . . . . . . . . . . . . . . . . . . 12 85 3.12. Future Sieve Actions . . . . . . . . . . . . . . . . . . . 13 87 4. Interaction With Sieve Environment . . . . . . . . . . . . 14 88 4.1. Base Sieve Environment Items: location and phase . . . . . 14 89 4.2. New Sieve Environment Items: imap.user and imap.email . . 14 90 4.3. New Sieve Environment Item: imap.cause . . . . . . . . . . 14 91 4.4. New Sieve Environment Item: imap.mailbox . . . . . . . . . 15 92 4.5. New Sieve Environment Item: imap.changedflags . . . . . . 15 93 4.6. Interaction With Sieve Tests (Comparisons) . . . . . . . . 15 95 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 16 96 6. Security Considerations . . . . . . . . . . . . . . . . . 17 98 7. IANA Considerations . . . . . . . . . . . . . . . . . . . 18 99 7.1. Registration of "imapsieve" IMAP capability . . . . . . . 18 100 7.2. Registration of "imapsieve" Sieve extension . . . . . . . 18 101 7.3. Registration of Sieve Environment Items . . . . . . . . . 18 102 7.3.1. Registration of Sieve Environment Item: imap.cause . . . . 18 103 7.3.2. Registration of Sieve Environment Item: imap.mailbox . . . 19 104 7.3.3. Registration of Sieve Environment Item: 105 imap.changedflags . . . . . . . . . . . . . . . . . . . . 19 106 7.3.4. Registration of Sieve Environment Item: imap.user . . . . 19 107 7.3.5. Registration of Sieve Environment Item: imap.email . . . . 19 108 7.4. Registration of IMAP METADATA Mailbox Entry Name . . . . . 19 109 7.5. Registration of IMAP METADATA Server Entry Name . . . . . 20 111 8. References . . . . . . . . . . . . . . . . . . . . . . . . 21 112 8.1. Normative References . . . . . . . . . . . . . . . . . . . 21 113 8.2. Informative References . . . . . . . . . . . . . . . . . . 21 115 Author's Address . . . . . . . . . . . . . . . . . . . . . 23 117 1. Introduction 119 1.1. Overview 121 Some applications have a need to apply Sieve filters [RFC5228] in 122 contexts other than initial mail delivery. This is especially true 123 in diverse service environments, such as when the client is 124 sporadically connected, is connected through a high-latency or high- 125 cost channel, or is on a limited-function device. For such clients, 126 it may be very important, for higher performance and reliability, to 127 take advantage of server capabilities, including those provided by 128 Sieve filtering (and Sieve extensions, such as Notify [RFC5435]). 130 This specification defines extensions to IMAP [RFC3501] to support 131 the invocation of Sieve scripts at times when the IMAP server creates 132 new messages or modifies existing ones. It also defines how Sieve 133 scripts will process these invocations. Support for IMAP events in 134 Sieve also requires support for the following: 136 o IMAP Metadata [RFC5464], because Metadata is used to associate 137 scripts with IMAP mailboxes. 139 o Sieve Environment [RFC5183], because it defines an important way 140 for Sieve scripts to test the conditions under which they have 141 been invoked. 143 o Sieve IMAP4Flags [RFC5232], because it provides important 144 functionality in handling IMAP events related to flag changes. 146 Because this requires future Sieve extensions to specify their 147 interactions with this one (see Section 3.12), this document updates 148 the base Sieve specification, RFC 5228. 150 1.2. Differences Between IMAP Events and Mail Delivery 152 Invoking Sieve scripts in a context other than initial mail delivery 153 introduces new situations, which changes the applicability of Sieve 154 features and creates implementation challenges and user interface 155 issues. This section discusses some of those differences, 156 challenges, and issues. 158 At times other than message delivery, delivery "envelope" information 159 might not be available. With messages added through IMAP APPEND, 160 there might be no way to even guess who the intended recipient is, 161 and no concept of who "sent" the message. Sieve actions that relate 162 to contacting the sender, for example, will not be applicable. 164 Because IMAP events will often be triggered by user actions, and 165 because user interfaces allow bulk actions that differ from 166 individual message arrival, it now becomes possible for a single user 167 action, such as drag-and-drop, to initiate Sieve script processing on 168 a large number of messages at once. Implementations will have to 169 deal with such situations as a "COPY" action or flag changes on 170 dozens, or even thousands of messages. 172 Other issues might surface as this extension is deployed and 173 experience with it develops. 175 1.3. Conventions used in this document 177 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 178 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 179 document are to be interpreted as described in [RFC2119]. 181 2. The IMAP Events in Sieve Extension 183 2.1. The "imapsieve" Capability Strings 185 An IMAP server advertises support for IMAP events in Sieve through 186 the "imapsieve" capability. A server that advertises "imapsieve" is 187 claiming to be in compliance with this specification in all aspects. 188 The syntax of the "imapsieve" capability string is defined as 189 follows: 191 capability /= "IMAPSIEVE=" sieveurl-server 192 ; is defined in RFC 5804, Section 3 194 Only one "imapsieve" capability string, specifying one sieveurl- 195 server, is allowed to be present. The sieveurl-server identifies the 196 ManageSieve server that clients need to contact for managing Sieve 197 scripts associated with this IMAP server. 199 The corresponding Sieve implementation uses the Sieve capability 200 string "imapsieve", and Sieve scripts that depend upon the IMAP 201 events MUST include that string in their "required" lists. 203 Implementations that support IMAP events in Sieve MUST also support 204 IMAP Metadata [RFC5464] and Sieve Environment [RFC5183], because 205 Metadata is used to associate scripts with IMAP mailboxes and 206 Environment defines an important way for Sieve scripts to test the 207 conditions under which they have been invoked. Notwithstanding the 208 support requirement, scripts that directly use Environment MUST also 209 include its capability string in their "required" lists. 211 2.2. Existing IMAP Functions Affected by IMAP events in Sieve 213 The subsections below describe in detail the IMAP commands and 214 situations on which IMAP events in Sieve have an effect. Not all 215 Sieve actions make sense in the case of messages affected by IMAP 216 commands. See Section 3 for details. 218 It's important to note that since the base Sieve specification (see 219 [RFC5228]) and its extensions define functions for scripts that are 220 invoked during initial mail delivery, those function definitions are 221 necessarily tailored to and limited by that context. This document 222 extends those function definitions for use during IMAP events. By 223 nature of that, Sieve functions, in this extended context, may behave 224 somewhat differently, though their extended behaviour will still be 225 consistent with the functions' goals. 227 If more than one message is affected at the same time, each message 228 triggers the execution of a Sieve script separately. The scripts MAY 229 be run in parallel. 231 2.2.1. The IMAP APPEND Command 233 A message may be added to a mailbox through the IMAP APPEND command. 234 In a server that advertises "imapsieve", new messages added in this 235 way MUST trigger the execution of a Sieve script, subject to the 236 settings defined through Metadata (see Section 2.3.1). 238 If the IMAP server also supports the IMAP MultiAppend extension 239 [RFC3502], the APPEND command can create more than one message at a 240 time. In that case, each message creation is considered a separate 241 event, and any applicable Sieve script is called once for each 242 message. 244 2.2.2. The IMAP COPY Command 246 One or more messages may be added to a mailbox through the IMAP COPY 247 command. In a server that advertises "imapsieve", new messages added 248 in this way MUST trigger the execution of a Sieve script, subject to 249 the settings defined through Metadata. 251 2.2.3. Changes to IMAP Message Flags 253 One or more existing messages can have their flags changed in a 254 number of ways, including: 256 o The FETCH command (may cause the \Seen flag to be set). 258 o The STORE command (may cause the \Answered, \Deleted, \Draft, 259 \Flagged, and \Seen flags to be set or reset, and may cause 260 keywords to be set or reset). 262 o The invocation of a Sieve script on an existing message, where the 263 script uses one of the actions defined in the IMAP4Flags extension 264 [RFC5232] to change the flags. 266 In a server that advertises "imapsieve", messages whose flags are 267 changed in any way (except as explained in the next sentence) MUST 268 trigger the execution of a Sieve script, subject to the settings 269 defined through Metadata. The exception is that in order to avoid 270 script loops, flag changes that are made as a result of a script that 271 was itself invoked because of flag changes SHOULD NOT result in a 272 further invocation of the script. In any case, implementations MUST 273 take steps to avoid such loops. 275 For flag-change events, the Sieve script will see the message flags 276 as they are AFTER the changes. 278 2.2.4. When Script Actions Set the \Deleted Flag 280 There are times when the actions "fileinto" (see Section 3.3), 281 "redirect" (see Section 3.4), and "discard" (see Section 3.5) will 282 set the \Deleted flag on the message. In those cases, the following 283 apply: 285 When the \Deleted flag is set by the script, a flag-change Sieve 286 script is not invoked. 288 The implementation MAY then expunge the original message (WITHOUT 289 expunging other messages in the mailbox). Alternatively, it might 290 have expunges batched or done by a user. (It might be helpful to 291 allow the user to make this choice through a preference.) 293 If the server does the expunge, the effect is as though a client had 294 flagged the message and done a UID EXPUNGE (see [RFC4315]) on the 295 affected message(s) only. Handling it this way allows clients to 296 handle messages consistently, and avoids hidden changes that might 297 invalidate their message caches. 299 2.3. New Functions Defined by IMAP events in Sieve 301 2.3.1. Interaction with Metadata 303 Support for IMAP events in Sieve requires support for IMAP Metadata 304 [RFC5464] as well, since the latter is used to associate scripts with 305 IMAP mailboxes. 307 When an applicable event occurs on an IMAP mailbox, if there is an 308 IMAP metadata entry named "/shared/imapsieve/script" for the mailbox, 309 that entry is used. If there is not, but there is an IMAP metadata 310 entry named "/shared/imapsieve/script" for the server, that entry is 311 used (providing a way to define a global script for all mailboxes on 312 a server). If neither entry exists, then no script will be invoked. 314 If a "/shared/imapsieve/script" metadata entry was selected above, 315 its value is used as the name of the Sieve script that will be 316 invoked in response to the IMAP event. If the value is empty, then 317 no script is run. The selection of which metadata entry to use 318 happens before any examination of the contents of the entry. If the 319 mailbox entry is selected and is then found to be unusable or empty, 320 the server entry is not used as a backup: no script is run. 322 This specifies the mechanism for "activating" a script for a given 323 mailbox (or for all mailboxes), but does not specify a mechanism for 324 creating, storing, or validating the script. Implementations MUST 325 support ManageSieve [RFC5804], and can use the PUTSCRIPT command to 326 store the script without using the SETACTIVE command to activate it. 328 Script names used in "/shared/imapsieve/script" metadata entries are 329 the script names used on the corresponding ManageSieve server. If a 330 "/shared/imapsieve/script" metadata entry contains a script name that 331 doesn't exist in the ManageSieve server, then no Sieve script will be 332 invoked for IMAP Sieve events. 334 Only one Sieve script may currently be defined per mailbox, 335 eliminating the complexity and possible ambiguity involved with 336 coordinating the results of multiple scripts. Any sub-filtering is 337 done in the Sieve script. For example, if it's only necessary to 338 deal with flag changes, but not with new messages appended or copied, 339 the Sieve script will still be invoked for all events, and the script 340 is responsible for checking the event type. 342 The possibility is open for an extension to add support for multiple 343 scripts -- for example, per-client scripts on a multi-client user's 344 inbox, or per-user scripts on a mailbox that is shared among users. 346 Because this metadata name is associated with the mailbox, there can 347 (and it's expected that there will) be different scripts associated 348 with events for different mailboxes. Indeed, most mailboxes will 349 probably invoke no script at all. 351 3. Applicable Sieve Actions and Interactions 353 Since some Sieve actions relate specifically to the delivery of mail, 354 not all actions and extensions make sense when the messages are 355 created by other means or when changes are made to data associated 356 with existing messages. This section describes how actions in the 357 base Sieve specification, and those in extensions known at this 358 writing, relate to this specification. 360 In addition to what is specified here, interactions noted in the 361 individual specifications apply, and must be considered. 363 3.1. The Implicit Keep 365 For all cases that fall under IMAP events in Sieve, the implicit keep 366 means that the message is treated as it would have been if no Sieve 367 script were run. For APPEND and COPY, the message is stored into the 368 target mailbox normally. For flag changes, the message is left in 369 the mailbox. If actions have been taken that change the message, 370 those changes are considered transient and MUST NOT be retained for 371 any keep action (because IMAP messages are immutable). No error is 372 generated, but the original message, without the changes, is kept. 374 3.2. The Keep Action 376 The keep action is applicable in all cases that fall under IMAP 377 events in Sieve. Its behaviour is as described for implicit keep, in 378 Section 3.1. 380 3.3. The Fileinto Action 382 If the Sieve implementation supports the fileinto action, that action 383 is applicable in all cases that fall under IMAP events in Sieve. If 384 the Copy extension [RFC3894] is available and the :copy option is 385 specified, the implicit keep is retained; otherwise, fileinto cancels 386 the implicit keep, as specified in the base Sieve specification. 388 For APPEND and COPY, the message is stored into the fileinto mailbox 389 IN ADDITION TO the original target mailbox. For flag changes, the 390 message is COPIED into the fileinto mailbox, without removing the 391 original. In all cases, fileinto always creates a new message, 392 separate from the original. 394 The fileinto action is not an IMAP APPEND or COPY, and therefore does 395 not result in a subsequent event (see also the Security 396 Considerations, Section 6). 398 If a keep action is not also in effect, the original message is then 399 marked with the \Deleted flag (see Section 2.2.4). 401 3.4. The Redirect Action 403 The redirect action is applicable in all cases that fall under IMAP 404 events in Sieve. It causes the message to be sent, as specified in 405 the base Sieve specification, to the designated address. If the Copy 406 extension [RFC3894] is available and the :copy option is specified, 407 the implicit keep is retained; otherwise, redirect cancels the 408 implicit keep, as specified in the base Sieve specification. 410 It's possible that a message processed in this way does not have the 411 information necessary to be redirected properly. It might lack 412 necessary header information, and there might not be appropriate 413 information for the MAIL FROM command. In such cases, the "redirect" 414 action uses Message Submission [RFC6409], and it is up to the Sieve 415 engine to supply the missing information. The redirect address is, 416 of course, used for the "RCPT TO", and the "MAIL FROM" SHOULD be set 417 to the address of the owner of the mailbox. The message submission 418 server is allowed, according to the Message Submission protocol, to 419 perform necessary fix-up to the message (see Section 8 of RFC 6409). 420 It can also reject the submission attempt, if the message is too ill- 421 formed for submission. 423 For APPEND and COPY, the message is stored into the target mailbox in 424 addition to being redirected. For flag changes, the message remains 425 in its original mailbox. 427 If a keep action is not also in effect, the original message is then 428 marked with the \Deleted flag (see Section 2.2.4). 430 3.5. The Discard Action 432 The discard action is applicable in all cases that fall under IMAP 433 events in Sieve. For APPEND and COPY, the message is first stored 434 into the target mailbox. If an explicit keep action is also in 435 effect, the discard action now does nothing. Otherwise, the original 436 message is then marked with the \Deleted flag (see Section 2.2.4). 438 3.6. The Notify Action 440 If the Nofity extension [RFC5435] is available, the notify action is 441 applicable in all cases that fall under IMAP events in Sieve. The 442 result is that the requested notification is sent, and that the 443 message is otherwise handled as it would normally have been. 445 3.7. The Addheader and Deleteheader Actions 447 If the EditHeader extension [RFC5293] is available, it can be used to 448 make transient changes to header fields, which aren't saved in place, 449 such as for "redirect" or "fileinto" actions. Because messages in 450 IMAP mailboxes are immutable, such changes are not applicable for the 451 "keep" action (explicit or implicit). See Section 3.1. 453 3.8. The Setflag, Deleteflag, and Removeflag Actions 455 Implementations of IMAP events in Sieve MUST also support the 456 IMAP4Flags extension [RFC5232], and the actions associated with it 457 are all applicable to any case that falls under IMAP events in Sieve. 459 It is worth noting also that the "hasflag" test that is defined in 460 the IMAP4Flags extension might be particularly useful in scripts 461 triggered by flag changes ("hasflag" will see the new, changed 462 flags). The flag changes behave as though a client had made the 463 change. 465 As explained above, in order to avoid script loops flag changes that 466 are made as a result of a script that was itself invoked because of 467 flag changes SHOULD NOT result in another script invocation. In any 468 case, implementations MUST take steps to avoid such loops. 470 3.9. MIME Part Tests and Replacement 472 If the MIME Part Tests extension [RFC5703] is available, all of its 473 functions can be used, but any changes made to the message, using the 474 "replace" or "enclose" action, MUST be considered transient, and are 475 only applicable with actions such as "redirect" and "fileinto". 476 Because messages in IMAP mailboxes are immutable, such changes are 477 not applicable for the "keep" action (explicit or implicit). See 478 Section 3.1. 480 3.10. Spamtest and Virustest 482 If the Spamtest and Virustest extensions [RFC5235] are available, 483 they are applicable in all cases that fall under IMAP events in 484 Sieve. 486 3.11. Inapplicable Actions 488 The following actions and extensions are not applicable to any case 489 that falls under IMAP events in Sieve, because they are specifically 490 designed to respond to delivery of a new email message. Their 491 appearance in the "require" control or their use in an IMAP event 492 MUST result in an error condition that will terminate the Sieve 493 script: 495 reject [RFC5228] 497 ereject [RFC5429] 499 vacation [RFC5230] 501 Future extensions that are specifically designed to respond to 502 delivery of a new email message will likewise not be applicable to 503 this extension. 505 3.12. Future Sieve Actions 507 As noted above, future extensions that are specifically designed to 508 respond to delivery of a new email message will not be applicable to 509 this extension, because this extension does not involve acting at 510 new-message delivery time. 512 In general, future extensions to Sieve that define new actions MUST 513 specify the applicability of those actions to this specification. 515 4. Interaction With Sieve Environment 517 4.1. Base Sieve Environment Items: location and phase 519 The Sieve Environment extension defines a set of standard environment 520 items (see [RFC5183], Section 4.1). Two of those items are affected 521 when the script is invoked through an IMAP event. 523 The value of "location" is set to "MS" -- evaluation is being 524 performed by a Message Store. 526 The value of "phase" is set to "post" -- processing is taking place 527 after (or perhaps instead of, in the case of APPEND) final delivery. 529 4.2. New Sieve Environment Items: imap.user and imap.email 531 In the normal case, when Sieve is used in final delivery, there is no 532 identity for the "filer" -- the user who is creating or changing the 533 message. In this case, there is such an identity, and a Sieve script 534 might want to access that identity. 536 Implementations MUST set and make available two new environment 537 items: 539 "imap.user" -- the identity (login ID) of the IMAP user that caused 540 the action. This MUST be the empty string if it is accessed during 541 normal (final delivery) Sieve processing. 543 "imap.email" -- the primary email address of the IMAP user that 544 caused the action (the user identified by "imap.user"). In some 545 implementations, "imap.user" and "imap.email" might have the same 546 value. This MUST be the empty string if it is accessed during normal 547 (final delivery) Sieve processing. 549 4.3. New Sieve Environment Item: imap.cause 551 Each mailbox uses a single script for all the change conditions 552 described in this document (append, copy, flag changes). To support 553 that, the implementation MUST set the Environment [RFC5183] item 554 "imap.cause", which contains the name of the action that caused the 555 script to be invoked. Its value is one of the following: 557 o APPEND (for invocations resulting from APPEND commands) 559 o COPY (for invocations resulting from COPY commands) 561 o FLAG (for invocations resulting from flag changes) 562 Future extensions might define new events and, thus, new causes. 563 Such extensions will come with their own capability strings, and the 564 events they define will only be presented when their capabilities are 565 requested. Scripts that do not request those capabilities will not 566 see those events, and will not encounter the new cause strings. 568 4.4. New Sieve Environment Item: imap.mailbox 570 The implementation MUST set the Environment [RFC5183] item 571 "imap.mailbox" to the name of the mailbox that the affected message 572 is in, in the case of existing messages, or is targeted to be stored 573 into, in the case of new messages. The value of this item is fixed 574 when the script begins, and, in particular, MUST NOT change as a 575 result of any action, such as "fileinto". 577 4.5. New Sieve Environment Item: imap.changedflags 579 If the script was invoked because of flag changes to an existing 580 message, the implementation MUST set the Environment [RFC5183] item 581 "imap.changedflags" to the name(s) of the flag(s) that have changed. 582 If the script was not invoked because of flag changes, the value of 583 this item MUST be the empty string. The script will not know from 584 this item whether the flags have been set or reset, but it can use 585 the "hasflag" test to determine the current value. See example 2 in 586 Section 5 for an example of how this might be used. 588 4.6. Interaction With Sieve Tests (Comparisons) 590 Any tests against message envelope information, including the 591 "envelope" test in the Sieve base specification, as well as any such 592 test defined in extensions, are either inapplicable or have serious 593 interoperability issues when performed at other than final-delivery 594 time. Therefore, envelope tests MUST NOT be permitted in the cases 595 described here, and their use MUST generate a runtime error. 597 This extension does not affect the operation of other tests or 598 comparisons in the Sieve base specification. 600 5. Examples 602 Example 1: 603 If a new message is added to the "ActionItems" mailbox, a copy is 604 sent to the address "actionitems@example.com". 606 require ["copy", "environment", "imapsieve"]; 608 if anyof (environment :is "imap.cause" "APPEND", 609 environment :is "imap.cause" "COPY") { 610 if environment :is "imap.mailbox" "ActionItems" { 611 redirect :copy "actionitems@example.com"; 612 } 613 } 615 Example 2: 616 If the script is called for any message with the \Flagged flag set 617 (tested through the IMAP4Flags extension [RFC5232]) AND this script 618 invocation represents a change to that flag, then a notification is 619 sent using the Notify extension [RFC5435]. No notification will be 620 sent, though, if we're called with an existing message that already 621 had that flag set. 623 require ["enotify", "imap4flags", "variables", 624 "environment", "imapsieve"]; 626 if environment :matches "imap.mailbox" "*" { 627 set "mailbox" "${1}"; 628 } 630 if allof (hasflag "\\Flagged", 631 environment :contains "imap.changedflags" "\\Flagged") { 632 notify :message "Important message in ${mailbox}" 633 "xmpp:tim@example.com?message;subject=SIEVE"; 634 } 636 Example 3: 637 This shows an example IMAP CAPABILITY response when this extension is 638 supported. The client has done STARTTLS with the server, and is now 639 inspecting capabilities. (The untagged CAPABILITY response is split 640 here for readability only, but will be in one response message.) 642 C: A01 CAPABILITY 643 S: * CAPABILITY IMAP4rev1 AUTH=PLAIN UIDPLUS LIST-EXTENDED 644 ACL IMAPSIEVE=sieve://sieve.example.com MULTISEARCH 645 S: A01 OK done 647 6. Security Considerations 649 It is possible to introduce script processing loops by having a Sieve 650 script that is triggered by flag changes use the actions defined in 651 the IMAP4Flags extension [RFC5232]. Implementations MUST take steps 652 to prevent script loops. One way to avoid this problem is that if a 653 script is invoked by flag changes, and that script further changes 654 the flags, those flag changes SHOULD NOT trigger a Sieve script 655 invocation. 657 The fileinto action never results in the invocation of a script. If 658 an implementation did invoke a script as the result of a fileinto, as 659 though an IMAP APPEND or COPY had been done, script loops could 660 result (mailbox A responds to all COPY events by doing "fileinto B", 661 and mailbox B responds to all COPY events by doing "fileinto A"). In 662 general, actions taken as a result of the Sieve script are not IMAP 663 events, and do not themselves trigger Sieve script invocations. 665 It is also possible to introduce loops through the "redirect" or 666 "notify" actions. See Section 10 of Sieve [RFC5228], Section 8 of 667 Sieve Notify [RFC5435], and the Security Considerations sections of 668 the applicable notification-method documents for loop-prevention 669 information. This extension does not change any of that advice. 671 This extension introduces side-effects to IMAP commands that users 672 and script authors might not be aware of and that can accidentally be 673 triggered by an operation that the user would expect to be innocuous. 674 In particular, certain actions, such as redirect, can cause a message 675 (such as a message appended to a mailbox by a user) to be sent to the 676 Internet in response to something as simple as a flag change. For 677 example, a script might cause messages marked for deletion to be sent 678 to some off-site archiving service. If a user appends a draft 679 message to a mailbox (perhaps an unencrypted draft message) and then 680 marks it for deletion, it might be very surprising to the user that 681 the message is sent off site. Script authors need to be careful not 682 to create these kinds of surprises, especially when creating global 683 scripts. 685 Other security considerations are discussed in IMAP [RFC3501], and 686 Sieve [RFC5228], as well as in some of the other extension documents. 688 7. IANA Considerations 690 7.1. Registration of "imapsieve" IMAP capability 692 IANA is asked to add "IMAPSIEVE=" to the IMAP 4 Capabilities 693 registry, according to the IMAP 4 specification [RFC3501]. 694 (http://www.iana.org/assignments/imap4-capabilities) 696 7.2. Registration of "imapsieve" Sieve extension 698 The following information should be added to the Sieve Extensions 699 registry, according to the Sieve specification [RFC5228]. (http:// 700 www.iana.org/assignments/sieve-extensions/sieve-extensions.xml) 702 To: iana@iana.org 703 Subject: Registration of new Sieve extension 704 Capability name: imapsieve 705 Description: Add Sieve processing for IMAP events. 706 RFC number: [[this RFC]] 707 Contact address: Sieve mailing list 709 7.3. Registration of Sieve Environment Items 711 The following subsections register items in the Sieve Environment 712 Items registry, according to the Environment extension [RFC5183]. 713 (http://www.iana.org/assignments/sieve-environment-items/ sieve- 714 environment-items.xml) 716 7.3.1. Registration of Sieve Environment Item: imap.cause 718 To: iana@iana.org 719 Subject: Registration of new Sieve environment item 720 Item name: imap.cause 721 Description: The name of the action that caused the script to be 722 invoked. Its value is one of the following: 724 o APPEND (for invocations resulting from APPEND commands) 726 o COPY (for invocations resulting from COPY commands) 728 o FLAG (for invocations resulting from flag changes) 730 RFC number: [[this RFC]] 731 Contact address: Sieve mailing list 733 7.3.2. Registration of Sieve Environment Item: imap.mailbox 735 To: iana@iana.org 736 Subject: Registration of new Sieve environment item 737 Item name: imap.mailbox 738 Description: The name of the mailbox that the affected message is in, 739 in the case of existing messages, or is targeted to be stored into, 740 in the case of new messages. The value of this item is fixed when 741 the script begins, and, in particular, MUST NOT change as a result of 742 any action, such as "fileinto". 743 RFC number: [[this RFC]] 744 Contact address: Sieve mailing list 746 7.3.3. Registration of Sieve Environment Item: imap.changedflags 748 To: iana@iana.org 749 Subject: Registration of new Sieve environment item 750 Item name: imap.changedflags 751 Description: If the script was invoked because of flag changes to an 752 existing message, this contains the name(s) of the flag(s) that have 753 changed. Otherwise, the value of this item MUST be the empty string. 754 RFC number: [[this RFC]] 755 Contact address: Sieve mailing list 757 7.3.4. Registration of Sieve Environment Item: imap.user 759 To: iana@iana.org 760 Subject: Registration of new Sieve environment item 761 Item name: imap.user 762 Description: The identity (IMAP login ID) of the IMAP user that 763 caused the action. 764 RFC number: [[this RFC]] 765 Contact address: Sieve mailing list 767 7.3.5. Registration of Sieve Environment Item: imap.email 769 To: iana@iana.org 770 Subject: Registration of new Sieve environment item 771 Item name: imap.email 772 Description: The primary email address of the IMAP user that caused 773 the action (the user identified by "imap.user"). 774 RFC number: [[this RFC]] 775 Contact address: Sieve mailing list 777 7.4. Registration of IMAP METADATA Mailbox Entry Name 779 The following information should be added to the IMAP METADATA 780 Mailbox Entry Registry, according to the Metadata extension 782 [RFC5464]. 783 (http://www.iana.org/assignments/imap-metadata/imap-metadata.xml) 785 To: iana@iana.org 786 Subject: IMAP METADATA Entry Registration 787 Type: Mailbox 788 Name: /shared/imapsieve/script 789 Description: This entry name is used to define mailbox metadata 790 associated with IMAP events in Sieve for the associated mailbox. 791 Specifically, this specifies the Sieve script that will be invoked 792 when IMAP events occur on the specified mailbox. 793 Content-type: text/plain; charset=utf-8 794 RFC number: [[this RFC]] 795 Contact address: Sieve mailing list 797 7.5. Registration of IMAP METADATA Server Entry Name 799 The following information should be added to the IMAP METADATA Server 800 Entry Registry, items according to the Metadata extension [RFC5464]. 801 (http://www.iana.org/assignments/imap-metadata/imap-metadata.xml) 803 To: iana@iana.org 804 Subject: IMAP METADATA Entry Registration 805 Type: Server 806 Name: /shared/imapsieve/script 807 Description: This entry name is used to define metadata associated 808 globally with IMAP events in Sieve for the associated server. 809 Specifically, this specifies the Sieve script that will be invoked 810 when IMAP events occur on any mailbox in the server that does not 811 have its own mailbox-level /shared/imapsieve/script entry. 812 Content-type: text/plain; charset=utf-8 813 RFC number: [[this RFC]] 814 Contact address: Sieve mailing list 816 8. References 818 8.1. Normative References 820 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 821 Requirement Levels", BCP 14, RFC 2119, March 1997. 823 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 824 4rev1", RFC 3501, March 2003. 826 [RFC3502] Crispin, M., "Internet Message Access Protocol (IMAP) - 827 MULTIAPPEND Extension", RFC 3502, March 2003. 829 [RFC3894] Degener, J., "Sieve Extension: Copying Without Side 830 Effects", RFC 3894, October 2004. 832 [RFC5183] Freed, N., "Sieve Email Filtering: Environment Extension", 833 RFC 5183, May 2008. 835 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 836 Language", RFC 5228, January 2008. 838 [RFC5232] Melnikov, A., "Sieve Email Filtering: Imap4flags 839 Extension", RFC 5232, January 2008. 841 [RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464, 842 February 2009. 844 [RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely 845 Managing Sieve Scripts", RFC 5804, July 2010. 847 [RFC6409] Gellens, R. and J. Klensin, "Message Submission for Mail", 848 STD 72, RFC 6409, November 2011. 850 8.2. Informative References 852 [RFC4315] Crispin, M., "Internet Message Access Protocol (IMAP) - 853 UIDPLUS extension", RFC 4315, December 2005. 855 [RFC5230] Showalter, T. and N. Freed, "Sieve Email Filtering: 856 Vacation Extension", RFC 5230, January 2008. 858 [RFC5235] Daboo, C., "Sieve Email Filtering: Spamtest and Virustest 859 Extensions", RFC 5235, January 2008. 861 [RFC5293] Degener, J. and P. Guenther, "Sieve Email Filtering: 862 Editheader Extension", RFC 5293, August 2008. 864 [RFC5429] Stone, A., "Sieve Email Filtering: Reject and Extended 865 Reject Extensions", RFC 5429, March 2009. 867 [RFC5435] Melnikov, A., Leiba, B., Segmuller, W., and T. Martin, 868 "Sieve Email Filtering: Extension for Notifications", 869 RFC 5435, January 2009. 871 [RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part 872 Tests, Iteration, Extraction, Replacement, and Enclosure", 873 RFC 5703, October 2009. 875 Author's Address 877 Barry Leiba 878 Huawei Technologies 880 Phone: +1 646 827 0648 881 Email: barryleiba@computer.org 882 URI: http://internetmessagingtechnology.org/