idnits 2.17.00 (12 Aug 2021) /tmp/idnits26331/draft-ietf-sieve-imap-sieve-02.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 8, 2011) is 3969 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) ** Obsolete normative reference: RFC 4409 (Obsoleted by RFC 6409) == Outdated reference: draft-ietf-sieve-include has been published as RFC 6609 Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). 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 Intended status: Standards Track July 8, 2011 5 Expires: January 9, 2012 7 Support for Sieve in Internet Message Access Protocol (IMAP4) 8 draft-ietf-sieve-imap-sieve-02 10 Abstract 12 Sieve defines an email filtering language that can, in principle, 13 plug into any point in the processing of an email message. As 14 defined in the base specification, it plugs into mail delivery. This 15 document defines how Sieve can plug into points in the IMAP protocol 16 where messages are created or changed, adding the option of user- 17 defined or installation-defined filtering (or, with Sieve extensions, 18 features such as notifications). 20 Note 22 This document defines extensions to IMAP and Sieve. It is the work 23 of the Sieve Working Group, but had previously been in the lemonade 24 mailing list, as draft-ietf-lemonade-imap-sieve. 26 1. Discussion of this document should be taken to the Sieve mailing 27 list at mailto:sieve@ietf.org 29 2. Subscription requests can be sent to 30 mailto:sieve@ietf.org?body=subscribe (send an email message with 31 the word "subscribe" in the body). 33 3. A WWW archive of back messages is available at 34 http://www.ietf.org/mail-archive/web/sieve/index.html 36 4. Older messages, which were posted to the lemonade mailing list, 37 are archived at 38 http://www.ietf.org/mail-archive/web/lemonade/index.html 40 Status of this Memo 42 This Internet-Draft is submitted in full conformance with the 43 provisions of BCP 78 and BCP 79. 45 Internet-Drafts are working documents of the Internet Engineering 46 Task Force (IETF). Note that other groups may also distribute 47 working documents as Internet-Drafts. The list of current Internet- 48 Drafts is at http://datatracker.ietf.org/drafts/current/. 50 Internet-Drafts are draft documents valid for a maximum of six months 51 and may be updated, replaced, or obsoleted by other documents at any 52 time. It is inappropriate to use Internet-Drafts as reference 53 material or to cite them other than as "work in progress." 55 This Internet-Draft will expire on January 9, 2012. 57 Copyright Notice 59 Copyright (c) 2011 IETF Trust and the persons identified as the 60 document authors. All rights reserved. 62 This document is subject to BCP 78 and the IETF Trust's Legal 63 Provisions Relating to IETF Documents 64 (http://trustee.ietf.org/license-info) in effect on the date of 65 publication of this document. Please review these documents 66 carefully, as they describe your rights and restrictions with respect 67 to this document. Code Components extracted from this document must 68 include Simplified BSD License text as described in Section 4.e of 69 the Trust Legal Provisions and are provided without warranty as 70 described in the Simplified BSD License. 72 Table of Contents 74 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 5 75 1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5 76 1.2. Conventions used in this document . . . . . . . . . . . . 5 78 2. The IMAPSieve Extension . . . . . . . . . . . . . . . . . 6 79 2.1. The "IMAPSieve" Capability String . . . . . . . . . . . . 6 80 2.2. Existing IMAP Functions Affected by IMAPSieve . . . . . . 6 81 2.2.1. The IMAP APPEND Command . . . . . . . . . . . . . . . . . 7 82 2.2.2. The IMAP MULTIAPPEND Command . . . . . . . . . . . . . . . 7 83 2.2.3. The IMAP COPY Command . . . . . . . . . . . . . . . . . . 7 84 2.2.4. Changes to IMAP Message Flags . . . . . . . . . . . . . . 7 85 2.3. New Functions Defined by IMAPSieve . . . . . . . . . . . . 8 86 2.3.1. Interaction with Metadata . . . . . . . . . . . . . . . . 8 88 3. Applicable Sieve Actions and Interactions . . . . . . . . 10 89 3.1. The Implicit Keep . . . . . . . . . . . . . . . . . . . . 10 90 3.2. The Keep Action . . . . . . . . . . . . . . . . . . . . . 10 91 3.3. The Fileinto Action . . . . . . . . . . . . . . . . . . . 10 92 3.4. The Redirect Action . . . . . . . . . . . . . . . . . . . 11 93 3.5. The Discard Action . . . . . . . . . . . . . . . . . . . . 11 94 3.6. The Notify Action . . . . . . . . . . . . . . . . . . . . 12 95 3.7. The Addheader and Deleteheader Actions . . . . . . . . . . 12 96 3.8. The Setflag, Deleteflag, and Removeflag Actions . . . . . 12 97 3.9. MIME Part Tests and Replacement . . . . . . . . . . . . . 12 98 3.10. Spamtest and Virustest . . . . . . . . . . . . . . . . . . 13 99 3.11. Inapplicable Actions . . . . . . . . . . . . . . . . . . . 13 101 4. New Sieve Environment Items . . . . . . . . . . . . . . . 14 102 4.1. New Sieve Environment Items: imapuser and imapemail . . . 14 103 4.2. New Sieve Environment Item: cause . . . . . . . . . . . . 14 104 4.3. New Sieve Environment Item: mailbox . . . . . . . . . . . 14 105 4.4. New Sieve Environment Item: changedflags . . . . . . . . . 15 106 4.5. Interaction With Sieve Tests (Comparisons) . . . . . . . . 15 108 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 16 110 6. Security Considerations . . . . . . . . . . . . . . . . . 17 112 7. IANA Considerations . . . . . . . . . . . . . . . . . . . 18 113 7.1. Registration of IMAPSIEVE IMAP capability . . . . . . . . 18 114 7.2. Registration of imapsieve Sieve extension . . . . . . . . 18 115 7.3. Registration of environment item: cause . . . . . . . . . 18 116 7.4. Registration of environment item: mailbox . . . . . . . . 19 117 7.5. Registration of environment item: changedflags . . . . . . 19 118 7.6. Registration of environment item: imapuser . . . . . . . . 19 119 7.7. Registration of environment item: imapemail . . . . . . . 20 120 7.8. Registration of IMAP METADATA mailbox entry name . . . . . 20 121 7.9. Registration of IMAP METADATA server entry name . . . . . 21 123 8. References . . . . . . . . . . . . . . . . . . . . . . . . 22 124 8.1. Normative References . . . . . . . . . . . . . . . . . . . 22 125 8.2. Non-Normative References . . . . . . . . . . . . . . . . . 22 127 Author's Address . . . . . . . . . . . . . . . . . . . . . 24 129 1. Introduction 131 1.1. Overview 133 Some applications have a need to apply Sieve filters [RFC5228] in 134 situations other than initial mail delivery. This is especially true 135 in diverse service environments, such as when the client is 136 sporadically connected, is connected through a high-latency or high- 137 cost channel, or is on a limited-function device. For such clients, 138 it may be very important, for higher performance and reliability, to 139 take advantage of server capabilities, including those provided by 140 Sieve filtering (and Sieve extensions, such as Notify [RFC5435]). 142 This specification defines extensions to IMAP [RFC3501] to support 143 the invocation of Sieve scripts at times when the IMAP server creates 144 new messages or modifies existing ones. It also defines how Sieve 145 scripts will process these invocations. Support for IMAPSieve 146 requires support for IMAP Metadata [RFC5464] and Sieve Environment 147 [RFC5183] as well, because Metadata is used to associate scripts with 148 IMAP mailboxes and Environment defines an important way for Sieve 149 scripts to test the conditions under which they have been invoked. 151 1.2. Conventions used in this document 153 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to 155 be interpreted as described in [RFC2119]. 157 2. The IMAPSieve Extension 159 2.1. The "IMAPSieve" Capability String 161 [[anchor1: Should we use "imapsieve" for both of these, as here? Or 162 should we use something like "SieveEvents" for the IMAP capability 163 and "IMAPEvents" for the Sieve capability? I rather think it's less 164 confusing to use the same string for both.]] 166 An IMAP server advertises support for this extension through the 167 capability string "IMAPSieve" (the string is not case-sensitive, and 168 is shown here with this capitalization for readability). A server 169 that advertises IMAPSieve is claiming to be in compliance with this 170 specification in all aspects. 172 The corresponding Sieve implementation uses the Sieve capability 173 string "IMAPSieve (also case-insensitive), and scripts that depend 174 upon the IMAP events MUST include that string in their "required" 175 lists. 177 Implementations that support IMAPSieve MUST also support IMAP 178 Metadata [RFC5464] and Sieve Environment [RFC5183], because Metadata 179 is used to associate scripts with IMAP mailboxes and Environment 180 defines an important way for Sieve scripts to test the conditions 181 under which they have been invoked. Notwithstanding the support 182 requirement, scripts that directly use Environment MUST also include 183 its capability string in their "required" lists. 185 2.2. Existing IMAP Functions Affected by IMAPSieve 187 The subsections below describe in detail the IMAP commands and 188 situations on which IMAPSieve has an effect. Not all Sieve actions 189 make sense in the case of messages affected by IMAP commands. See 190 Section 3 for details. 192 It's important to note that since the base Sieve specification (see 193 [RFC5228]) and its extensions define functions for scripts that are 194 invoked during initial mail delivery, those function definitions are 195 necessarily tailored to and limited by that context. This document 196 extends those function definitions for use during IMAP events. By 197 nature of that, Sieve functions, in this extended context, may behave 198 somewhat differently, though their extended behaviour will still be 199 consistent with the functions' goals. 201 If more than one message is affected at the same time, each message 202 triggers the execution of a Sieve script separately. The scripts MAY 203 be run in parallel. 205 2.2.1. The IMAP APPEND Command 207 A message may be added to a mailbox through the IMAP APPEND command. 208 In a server that advertises IMAPSieve, new messages added in this way 209 MUST trigger the execution of a Sieve script, subject to the settings 210 defined through Metadata (see Section 2.3.1). 212 2.2.2. The IMAP MULTIAPPEND Command 214 If the IMAP server supports the IMAP MultiAppend extension [RFC3502], 215 messages may be added to a mailbox through the IMAP MULTIAPPEND 216 command. In a server that advertises IMAPSieve, new messages added 217 in this way MUST trigger the execution of a Sieve script, as with the 218 APPEND command, also subject to the settings defined through 219 Metadata. 221 2.2.3. The IMAP COPY Command 223 One or more messages may be added to a mailbox through the IMAP COPY 224 command. In a server that advertises IMAPSieve, new messages added 225 in this way MUST trigger the execution of a Sieve script, subject to 226 the settings defined through Metadata. 228 2.2.4. Changes to IMAP Message Flags 230 One or more existing messages can have their flags changed in a 231 number of ways, including: 233 o The FETCH command (may cause the \Seen flag to be set). 235 o The STORE command (may cause the \Answered, \Deleted, \Draft, 236 \Flagged, and \Seen flags to be set or reset, and may cause 237 keywords to be set or reset). 239 o The invocation of a Sieve script on an existing message, where the 240 Sieve implementation supports the IMAP4Flags extension [RFC5232] 241 and the script uses one of the actions defined in that extension. 243 In a server that advertises IMAPSieve, messages whose flags are 244 changed in any way (except as explained in the next sentence) MUST 245 trigger the execution of a Sieve script, subject to the settings 246 defined through Metadata. The exception is that in order to avoid 247 script loops, flag changes that are made as a result of a script that 248 was itself invoked because of flag changes SHOULD NOT result in 249 another script invocation. In any case, implementations MUST take 250 steps to avoid such loops. 252 For flag-change events, the Sieve script will see the message flags 253 as they are AFTER the changes. 255 2.3. New Functions Defined by IMAPSieve 257 2.3.1. Interaction with Metadata 259 Support for IMAPSieve requires support for IMAP Metadata [RFC5464] as 260 well, since the latter is used to associate scripts with IMAP 261 mailboxes. 263 When an applicable event occurs on an IMAP mailbox, if there is an 264 IMAP metadata entry named "/IMAPSieve/Script" for the mailbox, that 265 entry is used. If there is not, but there is an IMAP metadata entry 266 named "/IMAPSieve/Script" for the server, that entry is used 267 (providing a way to define a global script for all mailboxes on a 268 server). If neither entry exists, then no script will be invoked. 270 If an "/IMAPSieve/Script" metadata entry was selected above, the 271 shared value of that metadata name (its "value.shared" attribute) 272 MUST be the name of the Sieve script that will be invoked in response 273 to the IMAP event OR the name of another metadata entry, the name 274 prefixed with "metadata:" (such as "metadata:/IMAPSieve/ 275 ScriptContents"), that contains the actual script in its value.shared 276 attribute. Note that only the value.shared attribute is used; any 277 value.priv attributes are ignored. 279 [[COMMENT FROM NED: But the real question is why should we limit 280 ourselves this way? Why not make the contents of "/IMAPSieve/Script" 281 a URL? (The metadata: prefix can then be defined as a URL.) If we 282 want to reach into ManageSieve, use a sieve: URL. (I do see a big 283 problem with this currently - RFC 5804 appears to have badly botched 284 the specification of sieve: URLs - the authority field is mandatory 285 when it shouldn't be, and the owner field is encoded into the URL 286 path when it should have been extracted from the authority field if 287 it is present. The way it's done now, you cannot write 288 sieve:///scriptname and have it mean what it should mean: Select out 289 of the mailbox owner's scripts. -------- Now, there is no doubt that 290 allowing URLs creates additional concerns, mostly security related. 291 But we've dealt with this sort of thing before, e.g., in BURL. All 292 we have to say is that metadata:foo MUST be implemented and sieve:bar 293 (modulo some fixes to RFC 5804) SHOULD work if ManageSieve is 294 available. -------- If this goes too far, then at a minimum I believe 295 this section needs to be more explicit about how, if ManageSieve is 296 used, the mapping from script collections in ManageSieve to a mailbox 297 works.]] 299 This specifies the mechanism for "activating" a script for a given 300 mailbox (or for all mailboxes), but does not specify a mechanism for 301 creating, storing, or validating the script. Implementations MAY use 302 ManageSieve [RFC5804] to acomplish this, using the PUTSCRIPT command 303 to store the script without using the SETACTIVE command to activate 304 it. In any case, the script name that is specified in the 305 /IMAPSieve/Script metadata entry is in a form that depends upon how 306 the server handles the storing of Sieve scripts. 308 Only one Sieve script may currently be defined per mailbox, 309 eliminating the complexity and possible ambiguity involved with 310 coordinating the results of multiple scripts. Any sub-filtering is 311 done in the Sieve script. For example, if it's only necessary to 312 deal with flag changes, but not with new messages appended or copied, 313 the Sieve script will still be invoked for all events, and the script 314 is responsible for checking the event type. 316 The possibility is open for an extension to add support for multiple 317 scripts -- for example, per-client scripts on a multi-client user's 318 inbox, or per-user scripts on a mailbox that is shared among users. 320 Because this metadata name is associated with the mailbox, there can 321 (and it's expected that there will) be different scripts associated 322 with events for different mailboxes. Indeed, most mailboxes will 323 probably invoke no script at all. 325 3. Applicable Sieve Actions and Interactions 327 Since some Sieve actions relate specifically to the delivery of mail, 328 not all actions and extensions make sense when the messages are 329 created by other means or when changes are made to data associated 330 with existing messages. This section describes how actions in the 331 base Sieve specification, and those in extensions known at this 332 writing, relate to this specification. 334 In addition to what is specified here, interactions noted in the 335 individual specifications apply, and must be considered. 337 3.1. The Implicit Keep 339 For all cases that fall under IMAPSieve, the implicit keep means that 340 the message is treated as it would have been if no Sieve script were 341 run. For APPEND, MULTIAPPEND and COPY, the message is stored into 342 the target mailbox normally. For flag changes, the message is left 343 in the mailbox. If actions have been taken that change the message, 344 those changes are considered transient and MUST NOT be retained for 345 any keep action (because IMAP messages are immutable). No error is 346 generated, but the original message, without the changes, is kept. 348 3.2. The Keep Action 350 The keep action is applicable in all cases that fall under IMAPSieve. 351 Its behaviour is as described for implicit keep, in Section 3.1. 353 3.3. The Fileinto Action 355 If the Sieve implementation supports the fileinto action, that action 356 is applicable in all cases that fall under IMAPSieve. If the Copy 357 extension [RFC3894] is available and the :copy option is specified, 358 the implicit keep is retained; otherwise, fileinto cancels the 359 implicit keep, as specified in the base Sieve specification. 361 For APPEND, MULTIAPPEND, and COPY, the message is stored into the 362 fileinto mailbox IN ADDITION TO the original target mailbox. For 363 flag changes, the message is COPIED into the fileinto mailbox, 364 without removing the original. 366 If a keep action is NOT also in effect, the original message is then 367 marked with the \Deleted flag (and a flag-change Sieve script is NOT 368 invoked). The implementation MAY then expunge the original message 369 (WITHOUT expunging other messages in the mailbox), or it MAY choose 370 to have expunges batched, or done by a user. If the server does the 371 expunge, the effect is as though a client had flagged the message and 372 done a UID EXPUNGE (see [RFC4315]) on the affected message(s) only. 374 Handling it this way allows clients to handle messages consistently, 375 and avoids hidden changes that might invalidate their message caches. 377 3.4. The Redirect Action 379 The redirect action is applicable in all cases that fall under 380 IMAPSieve. It causes the message to be sent, as specified in the 381 base Sieve specification, to the designated address. If the Copy 382 extension [RFC3894] is available and the :copy option is specified, 383 the implicit keep is retained; otherwise, redirect cancels the 384 implicit keep, as specified in the base Sieve specification. 386 It's possible that a message processed in this way does not have the 387 information necessary to be redirected properly. It might lack 388 necessary header information, and there might not be appropriate 389 information for the MAIL FROM command. In such cases, the "redirect" 390 action uses Message Submission [RFC4409], and it is up to the Sieve 391 engine to supply the missing information. The redirect address is, 392 of course, used for the "RCPT TO", and the "MAIL FROM" SHOULD be set 393 to the address of the owner of the mailbox. The message submission 394 server is allowed, according to the Message Submission protocol, to 395 perform necessary fix-up to the message (see section 8 of RFC 4409). 396 It can also reject the submission attempt, if the message is too ill- 397 formed for submission. 399 For APPEND, MULTIAPPEND, and COPY, the message is stored into the 400 target mailbox in addition to being redirected. For flag changes, 401 the message remains in its original mailbox. 403 If a keep action is NOT also in effect, the original message is then 404 marked with the \Deleted flag (and a flag-change Sieve script is NOT 405 invoked). The implementation MAY then expunge the original message 406 (WITHOUT expunging other messages in the mailbox), or it MAY choose 407 to have expunges batched, or done by a user. If the server does the 408 expunge, the effect is as though a client had flagged the message and 409 done a UID EXPUNGE (see [RFC4315]) on the affected message(s) only. 410 Handling it this way allows clients to handle messages consistently, 411 and avoids hidden changes that might invalidate their message caches. 413 3.5. The Discard Action 415 The discard action is applicable in all cases that fall under 416 IMAPSieve. For APPEND, MULTIAPPEND, and COPY, the message is first 417 stored into the target mailbox. If an explicit keep action is also 418 in effect, the discard action now does nothing. Otherwise, the 419 original message is then marked with the \Deleted flag (and a flag- 420 change Sieve script is NOT invoked). The implementation MAY then 421 expunge the original message (WITHOUT expunging other messages in the 422 mailbox), or it MAY choose to have expunges batched, or done by a 423 user. If the server does the expunge, the effect is as though a 424 client had flagged the message and done a UID EXPUNGE (see [RFC4315]) 425 on the affected message(s) only. Handling it this way allows clients 426 to handle messages consistently, and avoids hidden changes that might 427 invalidate their message caches. 429 3.6. The Notify Action 431 If the Nofity extension [RFC5435] is available, the notify action is 432 applicable in all cases that fall under IMAPSieve. The result is 433 that the requested notification is sent, and that the message is 434 otherwise handled as it would normally have been. 436 3.7. The Addheader and Deleteheader Actions 438 If the EditHeader extension [RFC5293] is available, it can be used to 439 make transient changes to header fields, which aren't saved in place, 440 such as for "redirect" or "fileinto" actions. Because messages in 441 IMAP mailboxes are immutable, such changes are NOT applicable for the 442 "keep" acton (explicit or implicit). See Section 3.1. 444 3.8. The Setflag, Deleteflag, and Removeflag Actions 446 Implementations of the IMAPSieve extension MUST also support the 447 IMAP4Flags extension [RFC5232], and the actions associated with it 448 are all applicable to any case that falls under IMAPSieve. 450 It is worth noting also that the "hasflag" test that is defined in 451 the IMAP4Flags extension might be particularly useful in scripts 452 triggered by flag changes ("hasflag" will see the new, changed 453 flags). The flag changes behave as though a client had made the 454 change. 456 As explained above, in order to avoid script loops flag changes that 457 are made as a result of a script that was itself invoked because of 458 flag changes SHOULD NOT result in another script invocation. In any 459 case, implementations MUST take steps to avoid such loops. 461 3.9. MIME Part Tests and Replacement 463 If the MIME Part Tests extension [RFC5703] is available, all of its 464 functions can be used, but any changes made to the message, using the 465 "replace" or "enclose" action, MUST be considered transient, and are 466 only applicable with actions such as "redirect" and "fileinto". 467 Because messages in IMAP mailboxes are immutable, such changes are 468 NOT applicable for the "keep" acton (explicit or implicit). See 469 Section 3.1. 471 3.10. Spamtest and Virustest 473 If the Spamtest and Virustest extensions [RFC5235] are available, 474 they are applicable in all cases that fall under IMAPSieve. 476 3.11. Inapplicable Actions 478 The following actions and extensions are NOT applicable to any case 479 that falls under IMAPSieve. Their use or their appearance in the 480 "require" control MUST result in an error condition that will 481 terminate the Sieve script: 483 reject [RFC5228] 485 ereject [RFC5429] 487 vacation [RFC5230] 489 4. New Sieve Environment Items 491 4.1. New Sieve Environment Items: imapuser and imapemail 493 In the normal case, when Sieve is used in final delivery, there is no 494 identity for the "filer" -- the user who is creating or changing the 495 message. In this case, there is such an identity, and a Sieve script 496 might want to access that identity. 498 Implementations MUST set and make available two new environment 499 items: 501 "imapuser" -- the identity (login ID) of the IMAP user that caused 502 the action. This MUST be the empty string if it is accessed during 503 normal (final delivery) Sieve processing. 505 "imapemail" -- the primary email address of the IMAP user that caused 506 the action (the user identified by "imapuser"). In some 507 implementations, "imapuser" and "imapemail" might have the same 508 value. This MUST be the empty string if it is accessed during normal 509 (final delivery) Sieve processing. 511 4.2. New Sieve Environment Item: cause 513 Implementations MAY invoke different Sieve scripts for the different 514 conditions described in this document (append, copy, flag changes). 515 If the actions to be taken are common, and the implementation 516 supports the Include extension [I-D.ietf-sieve-include], the common 517 script code can be included as specified there. 519 Each mailbox uses a single script for all the change conditions 520 described in this document (append, copy, flag changes). To support 521 that, the implementation MUST set the Environment [RFC5183] item 522 "cause", which contains the name of the action that caused the script 523 to be invoked. Its value is one of the following: 525 o APPEND (for invocations resulting from APPEND or MULTIAPPEND) 527 o COPY (for invocations resulting from COPY) 529 o FLAG (for invocations resulting from flag changes) 531 4.3. New Sieve Environment Item: mailbox 533 The implementation MUST set the Environment [RFC5183] item "mailbox" 534 to the name of the mailbox that the affected message is in, in the 535 case of existing messages, or is targeted to be stored into, in the 536 case of new messages. The value of this item is fixed when the 537 script begins, and, in particular, MUST NOT change as a result of any 538 action, such as "fileinto". 540 4.4. New Sieve Environment Item: changedflags 542 If the IMAP4Flags extension [RFC5232] is available, AND the script 543 was invoked because of flag changes to an existing message, the 544 implementation MUST set the Environment [RFC5183] item "changedflags" 545 to the name(s) of the flag(s) that have changed. If the script was 546 not invoked because of flag changes, the value of this item MUST be 547 the empty string. The script will not know from this item whether 548 the flags have been set or reset, but it can use the "hasflag" test 549 to determine the current value. See example 2 in Section 5 for an 550 example of how this might be used. 552 4.5. Interaction With Sieve Tests (Comparisons) 554 This extension does not affect the operation of tests or comparisons 555 in the Sieve base specification. 557 5. Examples 559 Example 1: 560 If a new message is added to the "ActionItems" mailbox, a copy is 561 sent to the address "actionitems@example.com". 563 require ["copy", "environment"]; 565 if anyof (environment :is "cause" "APPEND", 566 environment :is "cause" "COPY") { 567 if environment :is "mailbox" "ActionItems" { 568 redirect :copy "actionitems@example.com"; 569 } 570 } 572 Example 2: 573 If the script is called for any message with the \Flagged flag set 574 (tested through the IMAP4Flags extension [RFC5232]), a notification 575 is sent using the Notify extension [RFC5435]. No notification will 576 be sent, though, if we're called with an existing message that 577 already had that flag set. 579 require ["enotify", "imap4flags", "variables", "environment"]; 581 if environment :matches "mailbox" "*" { 582 set "mailbox" "${1}"; 583 } 585 if allof (hasflag "\\Flagged", 586 not environment :contains "changedflags" "\\Flagged") { 587 notify :message "Important message in ${mailbox}" 588 "xmpp:tim@example.com?message;subject=SIEVE"; 589 } 591 6. Security Considerations 593 It is possible to introduce script processing loops by having a Sieve 594 script that is triggered by flag changes use the actions defined in 595 the IMAP4Flags extension [RFC5232]. Implementations MUST take steps 596 to prevent such loops. One way to avoid this problem is that if a 597 script is invoked by flag changes, and that script further changes 598 the flags, those flag changes SHOULD NOT trigger a Sieve script 599 invocation. 601 It is also possible to introduce loops through the "redirect" or 602 "notify" actions. See section 10 of Sieve [RFC5228], section 8 of 603 Sieve Notify [RFC5435], and the Security Considerations sections of 604 the applicable notification-method documents for loop-prevention 605 information. This extension does not change any of that advice. 607 Other security considerations are discussed in IMAP [RFC3501], and 608 Sieve [RFC5228], as well as in some of the other extension documents. 610 7. IANA Considerations 612 7.1. Registration of IMAPSIEVE IMAP capability 614 This document defines a new IMAP capability. IANA is asked to add 615 "IMAPSIEVE" to the IMAP 4 Capabilities registry. 617 7.2. Registration of imapsieve Sieve extension 619 The following template specifies the IANA registration of the Sieve 620 extension specified in this document: 622 To: iana@iana.org 623 Subject: Registration of new Sieve extension 624 Capability name: imapsieve 625 Description: Add Sieve processing for IMAP events. 626 RFC number: this RFC 627 Contact address: Barry Leiba 629 This information should be added to the list of sieve extensions 630 given on http://www.iana.org/assignments/sieve-extensions. 632 7.3. Registration of environment item: cause 634 The following template specifies the IANA registration of a sieve 635 environment item specified in this document: 637 To: iana@iana.org 638 Subject: Registration of new Sieve environment item 639 Item name: cause 640 Description: The name of the action that caused the script to be 641 invoked. Its value is one of the following: 643 o APPEND (for invocations resulting from APPEND or MULTIAPPEND) 645 o COPY (for invocations resulting from COPY) 647 o FLAG (for invocations resulting from flag changes) 649 RFC number: this RFC 650 Contact address: 651 Barry Leiba 653 This information should be added to the list of sieve environment 654 item names given in the Environment extension [RFC5183]. 656 7.4. Registration of environment item: mailbox 658 The following template specifies the IANA registration of a sieve 659 environment item specified in this document: 661 To: iana@iana.org 662 Subject: Registration of new Sieve environment item 663 Item name: mailbox 664 Description: The name of the mailbox that the affected message is in, 665 in the case of existing messages, or is targeted to be stored into, 666 in the case of new messages. The value of this item is fixed when 667 the script begins, and, in particular, MUST NOT change as a result of 668 any action, such as "fileinto". 669 RFC number: this RFC 670 Contact address: 671 Barry Leiba 673 This information should be added to the list of sieve environment 674 item names given in the Environment extension [RFC5183]. 676 7.5. Registration of environment item: changedflags 678 The following template specifies the IANA registration of a sieve 679 environment item specified in this document: 681 To: iana@iana.org 682 Subject: Registration of new Sieve environment item 683 Item name: changedflags 684 Description: If the script was invoked because of flag changes to an 685 existing message, this contains the name(s) of the flag(s) that have 686 changed. Otherwise, the value of this item MUST be the empty string. 687 RFC number: this RFC 688 Contact address: 689 Barry Leiba 691 This information should be added to the list of sieve environment 692 item names given in the Environment extension [RFC5183]. 694 7.6. Registration of environment item: imapuser 696 The following template specifies the IANA registration of a sieve 697 environment item specified in this document: 699 To: iana@iana.org 700 Subject: Registration of new Sieve environment item 701 Item name: imapuser 702 Description: The identity (IMAP login ID) of the IMAP user that 703 caused the action. 705 RFC number: this RFC 706 Contact address: 707 Barry Leiba 709 This information should be added to the list of sieve environment 710 item names given in the Environment extension [RFC5183]. 712 7.7. Registration of environment item: imapemail 714 The following template specifies the IANA registration of a sieve 715 environment item specified in this document: 717 To: iana@iana.org 718 Subject: Registration of new Sieve environment item 719 Item name: imapemail 720 Description: The primary email address of the IMAP user that caused 721 the action (the user identified by "imapuser"). 722 RFC number: this RFC 723 Contact address: 724 Barry Leiba 726 This information should be added to the list of sieve environment 727 item names given in the Environment extension [RFC5183]. 729 7.8. Registration of IMAP METADATA mailbox entry name 731 The following template specifies the IANA registration of an IMAP 732 METADATA entry name specified in this document: 734 To: iana@iana.org 735 Subject: IMAP METADATA Registration 736 Please register the following IMAP METADATA item: 737 [x] Entry [ ] Attribute 738 [x] Mailbox [ ] Server 739 Name: /IMAPSieve/Script 740 Description: This entry name is used to define mailbox metadata 741 associated with IMAPSieve events for the associated mailbox. 742 Specifically, this specifies the Sieve script that will be invoked 743 when IMAP events occur on the specified mailbox. 744 Content-type: text/plain; charset=utf-8 745 RFC number: this RFC 746 Contact person: Barry Leiba 747 Contact email: barryleiba@computer.org 749 This information should be added to the list of IMAP METADATA item 750 names given in the Metadata extension [RFC5464]. 752 7.9. Registration of IMAP METADATA server entry name 754 The following template specifies the IANA registration of an IMAP 755 METADATA entry name specified in this document: 757 To: iana@iana.org 758 Subject: IMAP METADATA Registration 759 Please register the following IMAP METADATA item: 760 [x] Entry [ ] Attribute 761 [ ] Mailbox [x] Server 762 Name: /IMAPSieve/Script 763 Description: This entry name is used to define metadata associated 764 globally with IMAPSieve events for the associated server. 765 Specifically, this specifies the Sieve script that will be invoked 766 when IMAP events occur on any mailbox in the server that does not 767 have its own mailbox-level /IMAPSieve/Script entry. 768 Content-type: text/plain; charset=utf-8 769 RFC number: this RFC 770 Contact person: Barry Leiba 771 Contact email: barryleiba@computer.org 773 This information should be added to the list of IMAP METADATA item 774 names given in the Metadata extension [RFC5464]. 776 8. References 778 8.1. Normative References 780 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 781 Requirement Levels", BCP 14, RFC 2119, March 1997. 783 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 784 4rev1", RFC 3501, March 2003. 786 [RFC3502] Crispin, M., "Internet Message Access Protocol (IMAP) - 787 MULTIAPPEND Extension", RFC 3502, March 2003. 789 [RFC3894] Degener, J., "Sieve Extension: Copying Without Side 790 Effects", RFC 3894, October 2004. 792 [RFC4409] Gellens, R. and J. Klensin, "Message Submission for Mail", 793 RFC 4409, April 2006. 795 [RFC5183] Freed, N., "Sieve Email Filtering: Environment Extension", 796 RFC 5183, May 2008. 798 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 799 Language", RFC 5228, January 2008. 801 [RFC5232] Melnikov, A., "Sieve Email Filtering: Imap4flags 802 Extension", RFC 5232, January 2008. 804 [RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464, 805 February 2009. 807 8.2. Non-Normative References 809 [I-D.ietf-sieve-include] 810 Daboo, C. and A. Stone, "Sieve Email Filtering: Include 811 Extension", draft-ietf-sieve-include-06 (work in 812 progress), July 2010. 814 [RFC4315] Crispin, M., "Internet Message Access Protocol (IMAP) - 815 UIDPLUS extension", RFC 4315, December 2005. 817 [RFC5230] Showalter, T. and N. Freed, "Sieve Email Filtering: 818 Vacation Extension", RFC 5230, January 2008. 820 [RFC5235] Daboo, C., "Sieve Email Filtering: Spamtest and Virustest 821 Extensions", RFC 5235, January 2008. 823 [RFC5293] Degener, J. and P. Guenther, "Sieve Email Filtering: 825 Editheader Extension", RFC 5293, August 2008. 827 [RFC5429] Stone, A., "Sieve Email Filtering: Reject and Extended 828 Reject Extensions", RFC 5429, March 2009. 830 [RFC5435] Melnikov, A., Leiba, B., Segmuller, W., and T. Martin, 831 "Sieve Email Filtering: Extension for Notifications", 832 RFC 5435, January 2009. 834 [RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part 835 Tests, Iteration, Extraction, Replacement, and Enclosure", 836 RFC 5703, October 2009. 838 [RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely 839 Managing Sieve Scripts", RFC 5804, July 2010. 841 Author's Address 843 Barry Leiba 844 Huawei Technologies 846 Phone: +1 646 827 0648 847 Email: barryleiba@computer.org 848 URI: http://internetmessagingtechnology.org/