idnits 2.17.00 (12 Aug 2021) /tmp/idnits27312/draft-ietf-sieve-imap-sieve-07.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 10, 2012) is 3539 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 10, 2012 5 Intended status: Standards Track 6 Expires: March 14, 2013 8 Support for Internet Message Access Protocol (IMAP) Events in Sieve 9 draft-ietf-sieve-imap-sieve-07 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 14, 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 MULTIAPPEND Command . . . . . . . . . . . . . . . 7 68 2.2.3. The IMAP COPY Command . . . . . . . . . . . . . . . . . . 7 69 2.2.4. Changes to IMAP Message Flags . . . . . . . . . . . . . . 7 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 . . . . . . . . . . . . . . . . . . . . 12 79 3.6. The Notify Action . . . . . . . . . . . . . . . . . . . . 13 80 3.7. The Addheader and Deleteheader Actions . . . . . . . . . . 13 81 3.8. The Setflag, Deleteflag, and Removeflag Actions . . . . . 13 82 3.9. MIME Part Tests and Replacement . . . . . . . . . . . . . 13 83 3.10. Spamtest and Virustest . . . . . . . . . . . . . . . . . . 14 84 3.11. Inapplicable Actions . . . . . . . . . . . . . . . . . . . 14 85 3.12. Future Sieve Actions . . . . . . . . . . . . . . . . . . . 14 87 4. Interaction With Sieve Environment . . . . . . . . . . . . 15 88 4.1. Base Sieve Environment Items: location and phase . . . . . 15 89 4.2. New Sieve Environment Items: imapuser and imapemail . . . 15 90 4.3. New Sieve Environment Item: cause . . . . . . . . . . . . 15 91 4.4. New Sieve Environment Item: mailbox . . . . . . . . . . . 16 92 4.5. New Sieve Environment Item: changedflags . . . . . . . . . 16 93 4.6. Interaction With Sieve Tests (Comparisons) . . . . . . . . 16 95 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 17 96 6. Security Considerations . . . . . . . . . . . . . . . . . 18 98 7. IANA Considerations . . . . . . . . . . . . . . . . . . . 19 99 7.1. Registration of "imapsieve" IMAP capability . . . . . . . 19 100 7.2. Registration of "imapsieve" Sieve extension . . . . . . . 19 101 7.3. Registration of Sieve Environment Items . . . . . . . . . 19 102 7.3.1. Registration of Sieve Environment Item: cause . . . . . . 19 103 7.3.2. Registration of Sieve Environment Item: mailbox . . . . . 20 104 7.3.3. Registration of Sieve Environment Item: changedflags . . . 20 105 7.3.4. Registration of Sieve Environment Item: imapuser . . . . . 20 106 7.3.5. Registration of Sieve Environment Item: imapemail . . . . 20 107 7.4. Registration of IMAP METADATA Mailbox Entry Name . . . . . 20 108 7.5. Registration of IMAP METADATA Server Entry Name . . . . . 21 110 8. References . . . . . . . . . . . . . . . . . . . . . . . . 22 111 8.1. Normative References . . . . . . . . . . . . . . . . . . . 22 112 8.2. Informative References . . . . . . . . . . . . . . . . . . 22 114 Author's Address . . . . . . . . . . . . . . . . . . . . . 24 116 1. Introduction 118 1.1. Overview 120 Some applications have a need to apply Sieve filters [RFC5228] in 121 contexts other than initial mail delivery. This is especially true 122 in diverse service environments, such as when the client is 123 sporadically connected, is connected through a high-latency or high- 124 cost channel, or is on a limited-function device. For such clients, 125 it may be very important, for higher performance and reliability, to 126 take advantage of server capabilities, including those provided by 127 Sieve filtering (and Sieve extensions, such as Notify [RFC5435]). 129 This specification defines extensions to IMAP [RFC3501] to support 130 the invocation of Sieve scripts at times when the IMAP server creates 131 new messages or modifies existing ones. It also defines how Sieve 132 scripts will process these invocations. Support for IMAP events in 133 Sieve requires support for IMAP Metadata [RFC5464] and Sieve 134 Environment [RFC5183] as well, because Metadata is used to associate 135 scripts with IMAP mailboxes and Environment defines an important way 136 for Sieve scripts to test the conditions under which they have been 137 invoked. 139 Because this requires future Sieve extensions to specify their 140 interactions with this one (see Section 3.12), this document updates 141 the base Sieve specification, RFC 5228. 143 1.2. Differences Between IMAP Events and Mail Delivery 145 Invoking Sieve scripts in a context other than initial mail delivery 146 introduces new situations, which changes the applicability of Sieve 147 features and creates implementation challenges and user interface 148 issues. This section discusses some of those differences, 149 challenges, and issues. 151 At times other than message delivery, delivery "envelope" information 152 might not be available. With messages added through IMAP APPEND, 153 there might be no way to even guess who the intended recipient is, 154 and no concept of who "sent" the message. Sieve actions that relate 155 to contacting the sender, for example, will not be applicable. 157 Because IMAP events will often be triggered by user actions, and 158 because user interfaces allow bulk actions that differ from 159 individual message arrival, it now becomes possible for a single user 160 action, such as drag-and-drop, to initiate Sieve script processing on 161 a large number of messages at once. Implementations will have to 162 deal with such situations as a "COPY" action or flag changes on 163 dozens, or even thousands of messages. 165 Other issues might surface as this extension is deployed and 166 experience with it develops. 168 1.3. Conventions used in this document 170 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 171 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 172 document are to be interpreted as described in [RFC2119]. 174 2. The IMAP Events in Sieve Extension 176 2.1. The "imapsieve" Capability Strings 178 An IMAP server advertises support for IMAP events in Sieve through 179 the "imapsieve" capability. A server that advertises "imapsieve" is 180 claiming to be in compliance with this specification in all aspects. 181 The syntax of the "imapsieve" capability string is defined as 182 follows: 184 capability /= "IMAPSIEVE=" sieveurl-server 185 ; is defined in RFC 5804, Section 3 187 Only one "imapsieve" capability string, specifying one sieveurl- 188 server, is allowed to be present. The sieveurl-server identifies the 189 ManageSieve server that clients need to contact for managing Sieve 190 scripts associated with this IMAP server. 192 The corresponding Sieve implementation uses the Sieve capability 193 string "imapsieve", and Sieve scripts that depend upon the IMAP 194 events MUST include that string in their "required" lists. 196 Implementations that support IMAP events in Sieve MUST also support 197 IMAP Metadata [RFC5464] and Sieve Environment [RFC5183], because 198 Metadata is used to associate scripts with IMAP mailboxes and 199 Environment defines an important way for Sieve scripts to test the 200 conditions under which they have been invoked. Notwithstanding the 201 support requirement, scripts that directly use Environment MUST also 202 include its capability string in their "required" lists. 204 2.2. Existing IMAP Functions Affected by IMAP events in Sieve 206 The subsections below describe in detail the IMAP commands and 207 situations on which IMAP events in Sieve have an effect. Not all 208 Sieve actions make sense in the case of messages affected by IMAP 209 commands. See Section 3 for details. 211 It's important to note that since the base Sieve specification (see 212 [RFC5228]) and its extensions define functions for scripts that are 213 invoked during initial mail delivery, those function definitions are 214 necessarily tailored to and limited by that context. This document 215 extends those function definitions for use during IMAP events. By 216 nature of that, Sieve functions, in this extended context, may behave 217 somewhat differently, though their extended behaviour will still be 218 consistent with the functions' goals. 220 If more than one message is affected at the same time, each message 221 triggers the execution of a Sieve script separately. The scripts MAY 222 be run in parallel. 224 2.2.1. The IMAP APPEND Command 226 A message may be added to a mailbox through the IMAP APPEND command. 227 In a server that advertises "imapsieve", new messages added in this 228 way MUST trigger the execution of a Sieve script, subject to the 229 settings defined through Metadata (see Section 2.3.1). 231 2.2.2. The IMAP MULTIAPPEND Command 233 If the IMAP server supports the IMAP MultiAppend extension [RFC3502], 234 messages may be added to a mailbox through the IMAP MULTIAPPEND 235 command. In a server that advertises "imapsieve", new messages added 236 in this way MUST trigger the execution of a Sieve script, as with the 237 APPEND command, also subject to the settings defined through 238 Metadata. 240 2.2.3. The IMAP COPY Command 242 One or more messages may be added to a mailbox through the IMAP COPY 243 command. In a server that advertises "imapsieve", new messages added 244 in this way MUST trigger the execution of a Sieve script, subject to 245 the settings defined through Metadata. 247 2.2.4. Changes to IMAP Message Flags 249 One or more existing messages can have their flags changed in a 250 number of ways, including: 252 o The FETCH command (may cause the \Seen flag to be set). 254 o The STORE command (may cause the \Answered, \Deleted, \Draft, 255 \Flagged, and \Seen flags to be set or reset, and may cause 256 keywords to be set or reset). 258 o The invocation of a Sieve script on an existing message, where the 259 Sieve implementation supports the IMAP4Flags extension [RFC5232] 260 and the script uses one of the actions defined in that extension. 262 In a server that advertises "imapsieve", messages whose flags are 263 changed in any way (except as explained in the next sentence) MUST 264 trigger the execution of a Sieve script, subject to the settings 265 defined through Metadata. The exception is that in order to avoid 266 script loops, flag changes that are made as a result of a script that 267 was itself invoked because of flag changes SHOULD NOT result in a 268 further invocation of the script. In any case, implementations MUST 269 take steps to avoid such loops. 271 For flag-change events, the Sieve script will see the message flags 272 as they are AFTER the changes. 274 2.3. New Functions Defined by IMAP events in Sieve 276 2.3.1. Interaction with Metadata 278 Support for IMAP events in Sieve requires support for IMAP Metadata 279 [RFC5464] as well, since the latter is used to associate scripts with 280 IMAP mailboxes. 282 When an applicable event occurs on an IMAP mailbox, if there is an 283 IMAP metadata entry named "/shared/imapsieve/script" for the mailbox, 284 that entry is used. If there is not, but there is an IMAP metadata 285 entry named "/shared/imapsieve/script" for the server, that entry is 286 used (providing a way to define a global script for all mailboxes on 287 a server). If neither entry exists, then no script will be invoked. 289 If a "/shared/imapsieve/script" metadata entry was selected above, 290 its value is used as the name of the Sieve script that will be 291 invoked in response to the IMAP event. If the value is empty, then 292 no script is run. The selection of which metadata entry to use 293 happens before any examination of the contents of the entry. If the 294 mailbox entry is selected and is then found to be unusable or empty, 295 the server entry is not used as a backup: no script is run. 297 This specifies the mechanism for "activating" a script for a given 298 mailbox (or for all mailboxes), but does not specify a mechanism for 299 creating, storing, or validating the script. Implementations MUST 300 support ManageSieve [RFC5804], and can use the PUTSCRIPT command to 301 store the script without using the SETACTIVE command to activate it. 303 Script names used in "/shared/imapsieve/script" metadata entries are 304 the script names used on the corresponding ManageSieve server. If a 305 "/shared/imapsieve/script" metadata entry contains a script name that 306 doesn't exist in the ManageSieve server, then no Sieve script will be 307 invoked for IMAP Sieve events. 309 Only one Sieve script may currently be defined per mailbox, 310 eliminating the complexity and possible ambiguity involved with 311 coordinating the results of multiple scripts. Any sub-filtering is 312 done in the Sieve script. For example, if it's only necessary to 313 deal with flag changes, but not with new messages appended or copied, 314 the Sieve script will still be invoked for all events, and the script 315 is responsible for checking the event type. 317 The possibility is open for an extension to add support for multiple 318 scripts -- for example, per-client scripts on a multi-client user's 319 inbox, or per-user scripts on a mailbox that is shared among users. 321 Because this metadata name is associated with the mailbox, there can 322 (and it's expected that there will) be different scripts associated 323 with events for different mailboxes. Indeed, most mailboxes will 324 probably invoke no script at all. 326 3. Applicable Sieve Actions and Interactions 328 Since some Sieve actions relate specifically to the delivery of mail, 329 not all actions and extensions make sense when the messages are 330 created by other means or when changes are made to data associated 331 with existing messages. This section describes how actions in the 332 base Sieve specification, and those in extensions known at this 333 writing, relate to this specification. 335 In addition to what is specified here, interactions noted in the 336 individual specifications apply, and must be considered. 338 3.1. The Implicit Keep 340 For all cases that fall under IMAP events in Sieve, the implicit keep 341 means that the message is treated as it would have been if no Sieve 342 script were run. For APPEND, MULTIAPPEND and COPY, the message is 343 stored into the target mailbox normally. For flag changes, the 344 message is left in the mailbox. If actions have been taken that 345 change the message, those changes are considered transient and MUST 346 NOT be retained for any keep action (because IMAP messages are 347 immutable). No error is generated, but the original message, without 348 the changes, is kept. 350 3.2. The Keep Action 352 The keep action is applicable in all cases that fall under IMAP 353 events in Sieve. Its behaviour is as described for implicit keep, in 354 Section 3.1. 356 3.3. The Fileinto Action 358 If the Sieve implementation supports the fileinto action, that action 359 is applicable in all cases that fall under IMAP events in Sieve. If 360 the Copy extension [RFC3894] is available and the :copy option is 361 specified, the implicit keep is retained; otherwise, fileinto cancels 362 the implicit keep, as specified in the base Sieve specification. 364 For APPEND, MULTIAPPEND, and COPY, the message is stored into the 365 fileinto mailbox IN ADDITION TO the original target mailbox. For 366 flag changes, the message is COPIED into the fileinto mailbox, 367 without removing the original. In all cases, fileinto always creates 368 a new message, separate from the original. 370 If a keep action is not also in effect, the original message is then 371 marked with the \Deleted flag (and a flag-change Sieve script is not 372 invoked). The implementation MAY then expunge the original message 373 (WITHOUT expunging other messages in the mailbox); alternatively, it 374 might choose to have expunges batched or done by a user. If the 375 server does the expunge, the effect is as though a client had flagged 376 the message and done a UID EXPUNGE (see [RFC4315]) on the affected 377 message(s) only. Handling it this way allows clients to handle 378 messages consistently, and avoids hidden changes that might 379 invalidate their message caches. 381 3.4. The Redirect Action 383 The redirect action is applicable in all cases that fall under IMAP 384 events in Sieve. It causes the message to be sent, as specified in 385 the base Sieve specification, to the designated address. If the Copy 386 extension [RFC3894] is available and the :copy option is specified, 387 the implicit keep is retained; otherwise, redirect cancels the 388 implicit keep, as specified in the base Sieve specification. 390 It's possible that a message processed in this way does not have the 391 information necessary to be redirected properly. It might lack 392 necessary header information, and there might not be appropriate 393 information for the MAIL FROM command. In such cases, the "redirect" 394 action uses Message Submission [RFC6409], and it is up to the Sieve 395 engine to supply the missing information. The redirect address is, 396 of course, used for the "RCPT TO", and the "MAIL FROM" SHOULD be set 397 to the address of the owner of the mailbox. The message submission 398 server is allowed, according to the Message Submission protocol, to 399 perform necessary fix-up to the message (see Section 8 of RFC 6409). 400 It can also reject the submission attempt, if the message is too ill- 401 formed for submission. 403 Any site policies related to the origination of email have to be 404 enforced in the submission service, which will apply the same 405 policies to messages generated by the redirect action as it does to 406 messages submitted directly by user agents. 408 It is important to use the redirect action with great caution and 409 only with the understanding and consent of the user, as it causes a 410 message to be sent as a side effect of a user action (the storing or 411 copying of a message, the changing of a flag). The following 412 examples might represent appropriate use of redirect, if the user 413 specifically chooses them: 415 o The user wants messages she marks as "important" (through the 416 setting of the \Flagged flag) to be redirected to her alternate 417 email address. 419 o The user wants messages she files (copies) into her "Funny things 420 to share" mailbox to be redirected to a few friends she shares 421 these with. 423 o The user chooses a feature that takes messages the user copies to 424 his "Junk" mailbox and redirects them to a spam analysis service. 425 When the user chooses the feature, the mechanism and privacy 426 consequences are clearly explained. 428 But it is unlikely for examples such as these to ever be appropriate, 429 and the use of redirect in these sorts of scenarios is not advisable. 431 o Messages being redirected as a result of setting the \Seen flag. 432 The \Seen flag is set as a result of fetching the message, and 433 using redirect here is almost certainly too broad. 435 o Messages being redirected in a server-wide script to a spam 436 analysis service as a result of a user copying the message to his 437 "Junk" mailbox. 439 It would be dangerous and inappropriate for a server script to 440 redirect messages on behalf of all users, likely without their 441 understanding or consent. Therefore, the redirect action SHOULD NOT 442 be used in server-wide scripts. 444 It is also important to understand that the redirect action will not 445 have access to user-agent context, such as a setting to digitally 446 sign or encrypt all outgoing messages, or a setting to include a 447 particular Reply-To address. Users should be cautioned, when using 448 this action in their scripts, that this is the case. 450 For APPEND, MULTIAPPEND, and COPY, the message is stored into the 451 target mailbox in addition to being redirected. For flag changes, 452 the message remains in its original mailbox. 454 If a keep action is not also in effect, the original message is then 455 marked with the \Deleted flag (and a flag-change Sieve script is not 456 invoked). The implementation MAY then expunge the original message 457 (WITHOUT expunging other messages in the mailbox); alternatively, it 458 might choose to have expunges batched or done by a user. If the 459 server does the expunge, the effect is as though a client had flagged 460 the message and done a UID EXPUNGE (see [RFC4315]) on the affected 461 message(s) only. Handling it this way allows clients to handle 462 messages consistently, and avoids hidden changes that might 463 invalidate their message caches. 465 3.5. The Discard Action 467 The discard action is applicable in all cases that fall under IMAP 468 events in Sieve. For APPEND, MULTIAPPEND, and COPY, the message is 469 first stored into the target mailbox. If an explicit keep action is 470 also in effect, the discard action now does nothing. Otherwise, the 471 original message is then marked with the \Deleted flag (and a flag- 472 change Sieve script is not invoked). The implementation MAY then 473 expunge the original message (WITHOUT expunging other messages in the 474 mailbox); alternatively, it might choose to have expunges batched or 475 done by a user. If the server does the expunge, the effect is as 476 though a client had flagged the message and done a UID EXPUNGE (see 477 [RFC4315]) on the affected message(s) only. Handling it this way 478 allows clients to handle messages consistently, and avoids hidden 479 changes that might invalidate their message caches. 481 3.6. The Notify Action 483 If the Nofity extension [RFC5435] is available, the notify action is 484 applicable in all cases that fall under IMAP events in Sieve. The 485 result is that the requested notification is sent, and that the 486 message is otherwise handled as it would normally have been. 488 3.7. The Addheader and Deleteheader Actions 490 If the EditHeader extension [RFC5293] is available, it can be used to 491 make transient changes to header fields, which aren't saved in place, 492 such as for "redirect" or "fileinto" actions. Because messages in 493 IMAP mailboxes are immutable, such changes are not applicable for the 494 "keep" action (explicit or implicit). See Section 3.1. 496 3.8. The Setflag, Deleteflag, and Removeflag Actions 498 Implementations of IMAP events in Sieve MUST also support the 499 IMAP4Flags extension [RFC5232], and the actions associated with it 500 are all applicable to any case that falls under IMAP events in Sieve. 502 It is worth noting also that the "hasflag" test that is defined in 503 the IMAP4Flags extension might be particularly useful in scripts 504 triggered by flag changes ("hasflag" will see the new, changed 505 flags). The flag changes behave as though a client had made the 506 change. 508 As explained above, in order to avoid script loops flag changes that 509 are made as a result of a script that was itself invoked because of 510 flag changes SHOULD NOT result in another script invocation. In any 511 case, implementations MUST take steps to avoid such loops. 513 3.9. MIME Part Tests and Replacement 515 If the MIME Part Tests extension [RFC5703] is available, all of its 516 functions can be used, but any changes made to the message, using the 517 "replace" or "enclose" action, MUST be considered transient, and are 518 only applicable with actions such as "redirect" and "fileinto". 520 Because messages in IMAP mailboxes are immutable, such changes are 521 not applicable for the "keep" action (explicit or implicit). See 522 Section 3.1. 524 3.10. Spamtest and Virustest 526 If the Spamtest and Virustest extensions [RFC5235] are available, 527 they are applicable in all cases that fall under IMAP events in 528 Sieve. 530 3.11. Inapplicable Actions 532 The following actions and extensions are not applicable to any case 533 that falls under IMAP events in Sieve, because they are specifically 534 designed to respond to delivery of a new email message. Their 535 appearance in the "require" control or their use in an IMAP event 536 MUST result in an error condition that will terminate the Sieve 537 script: 539 reject [RFC5228] 541 ereject [RFC5429] 543 vacation [RFC5230] 545 Future extensions that are specifically designed to respond to 546 delivery of a new email message will likewise not be applicable to 547 this extension. 549 3.12. Future Sieve Actions 551 As noted above, future extensions that are specifically designed to 552 respond to delivery of a new email message will not be applicable to 553 this extension, because this extension does not involve acting at 554 new-message delivery time. 556 In general, future extensions to Sieve that define new actions MUST 557 specify the applicability of those actions to this specification. 559 4. Interaction With Sieve Environment 561 4.1. Base Sieve Environment Items: location and phase 563 The Sieve Environment extension defines a set of standard environment 564 items (see [RFC5183], Section 4.1). Two of those items are affected 565 when the script is invoked through an IMAP event. 567 The value of "location" is set to "MS" -- evaluation is being 568 performed by a Message Store. 570 The value of "phase" is set to "post" -- processing is taking place 571 after (or perhaps instead of, in the case of APPEND) final delivery. 573 4.2. New Sieve Environment Items: imapuser and imapemail 575 In the normal case, when Sieve is used in final delivery, there is no 576 identity for the "filer" -- the user who is creating or changing the 577 message. In this case, there is such an identity, and a Sieve script 578 might want to access that identity. 580 Implementations MUST set and make available two new environment 581 items: 583 "imapuser" -- the identity (login ID) of the IMAP user that caused 584 the action. This MUST be the empty string if it is accessed during 585 normal (final delivery) Sieve processing. 587 "imapemail" -- the primary email address of the IMAP user that caused 588 the action (the user identified by "imapuser"). In some 589 implementations, "imapuser" and "imapemail" might have the same 590 value. This MUST be the empty string if it is accessed during normal 591 (final delivery) Sieve processing. 593 4.3. New Sieve Environment Item: cause 595 Each mailbox uses a single script for all the change conditions 596 described in this document (append, copy, flag changes). To support 597 that, the implementation MUST set the Environment [RFC5183] item 598 "cause", which contains the name of the action that caused the script 599 to be invoked. Its value is one of the following: 601 o APPEND (for invocations resulting from APPEND or MULTIAPPEND) 603 o COPY (for invocations resulting from COPY) 605 o FLAG (for invocations resulting from flag changes) 606 Future extensions might define new events and, thus, new causes. 607 Such extensions will come with their own capability strings, and the 608 events they define will only be presented when their capabilities are 609 requested. Scripts that do not request those capabilities will not 610 see those events, and will not encounter the new cause strings. 612 4.4. New Sieve Environment Item: mailbox 614 The implementation MUST set the Environment [RFC5183] item "mailbox" 615 to the name of the mailbox that the affected message is in, in the 616 case of existing messages, or is targeted to be stored into, in the 617 case of new messages. The value of this item is fixed when the 618 script begins, and, in particular, MUST NOT change as a result of any 619 action, such as "fileinto". 621 4.5. New Sieve Environment Item: changedflags 623 If the IMAP4Flags extension [RFC5232] is available, AND the script 624 was invoked because of flag changes to an existing message, the 625 implementation MUST set the Environment [RFC5183] item "changedflags" 626 to the name(s) of the flag(s) that have changed. If the script was 627 not invoked because of flag changes, the value of this item MUST be 628 the empty string. The script will not know from this item whether 629 the flags have been set or reset, but it can use the "hasflag" test 630 to determine the current value. See example 2 in Section 5 for an 631 example of how this might be used. 633 4.6. Interaction With Sieve Tests (Comparisons) 635 Any tests against message envelope information, including the 636 "envelope" test in the Sieve base specification, as well as any such 637 test defined in extensions, are either inapplicable or have serious 638 interoperability issues when performed at other than final-delivery 639 time. Therefore, envelope tests MUST NOT be permitted in the cases 640 described here, and their use MUST generate a runtime error. 642 This extension does not affect the operation of other tests or 643 comparisons in the Sieve base specification. 645 5. Examples 647 Example 1: 648 If a new message is added to the "ActionItems" mailbox, a copy is 649 sent to the address "actionitems@example.com". 651 require ["copy", "environment", "imapsieve"]; 653 if anyof (environment :is "cause" "APPEND", 654 environment :is "cause" "COPY") { 655 if environment :is "mailbox" "ActionItems" { 656 redirect :copy "actionitems@example.com"; 657 } 658 } 660 Example 2: 661 If the script is called for any message with the \Flagged flag set 662 (tested through the IMAP4Flags extension [RFC5232]), a notification 663 is sent using the Notify extension [RFC5435]. No notification will 664 be sent, though, if we're called with an existing message that 665 already had that flag set. 667 require ["enotify", "imap4flags", "variables", 668 "environment", "imapsieve"]; 670 if environment :matches "mailbox" "*" { 671 set "mailbox" "${1}"; 672 } 674 if allof (hasflag "\\Flagged", 675 not environment :contains "changedflags" "\\Flagged") { 676 notify :message "Important message in ${mailbox}" 677 "xmpp:tim@example.com?message;subject=SIEVE"; 678 } 680 Example 3: 681 This shows an example IMAP CAPABILITY response when this extension is 682 supported. The client has done STARTTLS with the server, and is now 683 inspecting capabilities. (The untagged CAPABILITY response is split 684 here for readability only, but will be in one response message.) 686 C: A01 CAPABILITY 687 S: * CAPABILITY IMAP4rev1 AUTH=PLAIN UIDPLUS LIST-EXTENDED 688 ACL IMAPSIEVE=sieve://sieve.example.com MULTISEARCH 689 S: A01 OK done 691 6. Security Considerations 693 It is possible to introduce script processing loops by having a Sieve 694 script that is triggered by flag changes use the actions defined in 695 the IMAP4Flags extension [RFC5232]. Implementations MUST take steps 696 to prevent such loops. One way to avoid this problem is that if a 697 script is invoked by flag changes, and that script further changes 698 the flags, those flag changes SHOULD NOT trigger a Sieve script 699 invocation. 701 It is also possible to introduce loops through the "redirect" or 702 "notify" actions. See Section 10 of Sieve [RFC5228], Section 8 of 703 Sieve Notify [RFC5435], and the Security Considerations sections of 704 the applicable notification-method documents for loop-prevention 705 information. This extension does not change any of that advice. 707 Other security considerations are discussed in IMAP [RFC3501], and 708 Sieve [RFC5228], as well as in some of the other extension documents. 710 7. IANA Considerations 712 7.1. Registration of "imapsieve" IMAP capability 714 IANA is asked to add "IMAPSIEVE=" to the IMAP 4 Capabilities 715 registry, according to the IMAP 4 specification [RFC3501]. 716 (http://www.iana.org/assignments/imap4-capabilities) 718 7.2. Registration of "imapsieve" Sieve extension 720 The following information should be added to the Sieve Extensions 721 registry, according to the Sieve specification [RFC5228]. (http:// 722 www.iana.org/assignments/sieve-extensions/sieve-extensions.xml) 724 To: iana@iana.org 725 Subject: Registration of new Sieve extension 726 Capability name: imapsieve 727 Description: Add Sieve processing for IMAP events. 728 RFC number: [[this RFC]] 729 Contact address: Sieve mailing list 731 7.3. Registration of Sieve Environment Items 733 The following subsections register items in the Sieve Environment 734 Items registry, according to the Environment extension [RFC5183]. 735 (http://www.iana.org/assignments/sieve-environment-items/ sieve- 736 environment-items.xml) 738 7.3.1. Registration of Sieve Environment Item: cause 740 To: iana@iana.org 741 Subject: Registration of new Sieve environment item 742 Item name: cause 743 Description: The name of the action that caused the script to be 744 invoked. Its value is one of the following: 746 o APPEND (for invocations resulting from APPEND or MULTIAPPEND) 748 o COPY (for invocations resulting from COPY) 750 o FLAG (for invocations resulting from flag changes) 752 RFC number: [[this RFC]] 753 Contact address: Sieve mailing list 755 7.3.2. Registration of Sieve Environment Item: mailbox 757 To: iana@iana.org 758 Subject: Registration of new Sieve environment item 759 Item name: mailbox 760 Description: The name of the mailbox that the affected message is in, 761 in the case of existing messages, or is targeted to be stored into, 762 in the case of new messages. The value of this item is fixed when 763 the script begins, and, in particular, MUST NOT change as a result of 764 any action, such as "fileinto". 765 RFC number: [[this RFC]] 766 Contact address: Sieve mailing list 768 7.3.3. Registration of Sieve Environment Item: changedflags 770 To: iana@iana.org 771 Subject: Registration of new Sieve environment item 772 Item name: changedflags 773 Description: If the script was invoked because of flag changes to an 774 existing message, this contains the name(s) of the flag(s) that have 775 changed. Otherwise, the value of this item MUST be the empty string. 776 RFC number: [[this RFC]] 777 Contact address: Sieve mailing list 779 7.3.4. Registration of Sieve Environment Item: imapuser 781 To: iana@iana.org 782 Subject: Registration of new Sieve environment item 783 Item name: imapuser 784 Description: The identity (IMAP login ID) of the IMAP user that 785 caused the action. 786 RFC number: [[this RFC]] 787 Contact address: Sieve mailing list 789 7.3.5. Registration of Sieve Environment Item: imapemail 791 To: iana@iana.org 792 Subject: Registration of new Sieve environment item 793 Item name: imapemail 794 Description: The primary email address of the IMAP user that caused 795 the action (the user identified by "imapuser"). 796 RFC number: [[this RFC]] 797 Contact address: Sieve mailing list 799 7.4. Registration of IMAP METADATA Mailbox Entry Name 801 The following information should be added to the IMAP METADATA 802 Mailbox Entry Registry, according to the Metadata extension 804 [RFC5464]. 805 (http://www.iana.org/assignments/imap-metadata/imap-metadata.xml) 807 To: iana@iana.org 808 Subject: IMAP METADATA Entry Registration 809 Type: Mailbox 810 Name: /shared/imapsieve/script 811 Description: This entry name is used to define mailbox metadata 812 associated with IMAP events in Sieve for the associated mailbox. 813 Specifically, this specifies the Sieve script that will be invoked 814 when IMAP events occur on the specified mailbox. 815 Content-type: text/plain; charset=utf-8 816 RFC number: [[this RFC]] 817 Contact address: Sieve mailing list 819 7.5. Registration of IMAP METADATA Server Entry Name 821 The following information should be added to the IMAP METADATA Server 822 Entry Registry, items according to the Metadata extension [RFC5464]. 823 (http://www.iana.org/assignments/imap-metadata/imap-metadata.xml) 825 To: iana@iana.org 826 Subject: IMAP METADATA Entry Registration 827 Type: Server 828 Name: /shared/imapsieve/script 829 Description: This entry name is used to define metadata associated 830 globally with IMAP events in Sieve for the associated server. 831 Specifically, this specifies the Sieve script that will be invoked 832 when IMAP events occur on any mailbox in the server that does not 833 have its own mailbox-level /shared/imapsieve/script entry. 834 Content-type: text/plain; charset=utf-8 835 RFC number: [[this RFC]] 836 Contact address: Sieve mailing list 838 8. References 840 8.1. Normative References 842 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 843 Requirement Levels", BCP 14, RFC 2119, March 1997. 845 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 846 4rev1", RFC 3501, March 2003. 848 [RFC3502] Crispin, M., "Internet Message Access Protocol (IMAP) - 849 MULTIAPPEND Extension", RFC 3502, March 2003. 851 [RFC3894] Degener, J., "Sieve Extension: Copying Without Side 852 Effects", RFC 3894, October 2004. 854 [RFC5183] Freed, N., "Sieve Email Filtering: Environment Extension", 855 RFC 5183, May 2008. 857 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 858 Language", RFC 5228, January 2008. 860 [RFC5232] Melnikov, A., "Sieve Email Filtering: Imap4flags 861 Extension", RFC 5232, January 2008. 863 [RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464, 864 February 2009. 866 [RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely 867 Managing Sieve Scripts", RFC 5804, July 2010. 869 [RFC6409] Gellens, R. and J. Klensin, "Message Submission for Mail", 870 STD 72, RFC 6409, November 2011. 872 8.2. Informative References 874 [RFC4315] Crispin, M., "Internet Message Access Protocol (IMAP) - 875 UIDPLUS extension", RFC 4315, December 2005. 877 [RFC5230] Showalter, T. and N. Freed, "Sieve Email Filtering: 878 Vacation Extension", RFC 5230, January 2008. 880 [RFC5235] Daboo, C., "Sieve Email Filtering: Spamtest and Virustest 881 Extensions", RFC 5235, January 2008. 883 [RFC5293] Degener, J. and P. Guenther, "Sieve Email Filtering: 884 Editheader Extension", RFC 5293, August 2008. 886 [RFC5429] Stone, A., "Sieve Email Filtering: Reject and Extended 887 Reject Extensions", RFC 5429, March 2009. 889 [RFC5435] Melnikov, A., Leiba, B., Segmuller, W., and T. Martin, 890 "Sieve Email Filtering: Extension for Notifications", 891 RFC 5435, January 2009. 893 [RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part 894 Tests, Iteration, Extraction, Replacement, and Enclosure", 895 RFC 5703, October 2009. 897 Author's Address 899 Barry Leiba 900 Huawei Technologies 902 Phone: +1 646 827 0648 903 Email: barryleiba@computer.org 904 URI: http://internetmessagingtechnology.org/