idnits 2.17.1 draft-ietf-lemonade-imap-sieve-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 803. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 814. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 821. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 827. 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 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 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 (November 19, 2007) is 6000 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) ** Downref: Normative reference to an Experimental draft: draft-ietf-imapext-annotate (ref. 'Annotate') -- Possible downref: Normative reference to a draft: ref. 'Environment' ** Obsolete normative reference: RFC 3501 (ref. 'IMAP') (Obsoleted by RFC 9051) == Outdated reference: A later version (-17) exists of draft-daboo-imap-annotatemore-11 == Outdated reference: A later version (-13) exists of draft-ietf-sieve-3028bis-12 == Outdated reference: A later version (-11) exists of draft-ietf-sieve-editheader-07 == Outdated reference: A later version (-06) exists of draft-daboo-sieve-include-05 == Outdated reference: A later version (-12) exists of draft-martin-managesieve-07 == Outdated reference: A later version (-12) exists of draft-ietf-sieve-notify-07 == Outdated reference: A later version (-07) exists of draft-ietf-sieve-vacation-06 Summary: 3 errors (**), 0 flaws (~~), 9 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Lemonade Working Group B. Leiba 3 Internet-Draft IBM T.J. Watson Research Center 4 Intended status: Standards Track November 19, 2007 5 Expires: May 22, 2008 7 Support for Sieve in Internet Message Access Protocol (IMAP4) 8 draft-ietf-lemonade-imap-sieve-04 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on May 22, 2008. 35 Copyright Notice 37 Copyright (C) The IETF Trust (2007). 39 Abstract 41 Sieve defines an email filtering language that can, in principle, 42 plug into any point in the processing of an email message. As 43 defined in the base specification, it plugs into mail delivery. This 44 document defines how Sieve can plug into points in the IMAP protocol 45 where messages are created or changed, adding the option of user- 46 defined or installation-defined filtering (or, with Sieve extensions, 47 features such as notifications). 49 Note 51 While this document defines extensions to IMAP and Sieve, it is the 52 work of the Lemonade Working Group (Enhancements to Internet email to 53 support diverse service environments), and discussion of it is on the 54 lemonade mailing list at mailto:lemonade@ietf.org. Subscription 55 requests can be sent to 56 mailto:lemonade-request@ietf.org?body=subscribe (send an email 57 message with the word "subscribe" in the body). A WWW archive of 58 back messages is available at 59 http://www.ietf.org/mail-archive/web/lemonade/index.html 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 6 64 1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 1.2. Conventions used in this document . . . . . . . . . . . . 6 67 2. The IMAP "IMAPSieve" Extension . . . . . . . . . . . . . . 7 68 2.1. The "IMAPSieve" Capability String . . . . . . . . . . . . 7 69 2.2. Existing IMAP Functions Affected by IMAPSieve . . . . . . 7 70 2.2.1. The IMAP APPEND Command . . . . . . . . . . . . . . . . . 7 71 2.2.2. The IMAP MULTIAPPEND Command . . . . . . . . . . . . . . . 7 72 2.2.3. The IMAP COPY Command . . . . . . . . . . . . . . . . . . 8 73 2.2.4. Changes to IMAP Message Flags . . . . . . . . . . . . . . 8 74 2.2.5. New or Changed IMAP Message Annotations . . . . . . . . . 8 75 2.3. New Functions Defined by IMAPSieve . . . . . . . . . . . . 9 76 2.3.1. Changes to Metadata . . . . . . . . . . . . . . . . . . . 9 78 3. Applicable Sieve Actions and Interactions . . . . . . . . 11 79 3.1. The Implicit Keep . . . . . . . . . . . . . . . . . . . . 11 80 3.2. The Keep Action . . . . . . . . . . . . . . . . . . . . . 11 81 3.3. The Fileinto Action . . . . . . . . . . . . . . . . . . . 11 82 3.4. The Redirect Action . . . . . . . . . . . . . . . . . . . 12 83 3.5. The Reject Action . . . . . . . . . . . . . . . . . . . . 12 84 3.6. The Discard Action . . . . . . . . . . . . . . . . . . . . 12 85 3.7. The Notify Action . . . . . . . . . . . . . . . . . . . . 12 86 3.8. The Addheader and Deleteheader Actions . . . . . . . . . . 13 87 3.9. The Setflag, Deleteflag, and Removeflag Actions . . . . . 13 88 3.10. The Vacation Action . . . . . . . . . . . . . . . . . . . 13 89 3.11. New Sieve Environment Item: cause . . . . . . . . . . . . 13 90 3.12. New Sieve Environment Item: mailbox . . . . . . . . . . . 14 91 3.13. New Sieve Environment Item: changedflags . . . . . . . . . 14 92 3.14. New Sieve Environment Item: changedannotations . . . . . . 14 93 3.15. Interaction With Sieve Tests (Comparisons) . . . . . . . . 14 95 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 15 97 5. Security Considerations . . . . . . . . . . . . . . . . . 16 99 6. IANA Considerations . . . . . . . . . . . . . . . . . . . 17 100 6.1. Registration of imapsieve extension . . . . . . . . . . . 17 101 6.2. Registration of environment item: cause . . . . . . . . . 17 102 6.3. Registration of environment item: mailbox . . . . . . . . 17 103 6.4. Registration of environment item: changedflags . . . . . . 18 104 6.5. Registration of environment item: changedannotations . . . 18 105 6.6. Registration of IMAP METADATA mailbox entry name . . . . . 19 106 6.7. Registration of IMAP METADATA server entry name . . . . . 19 108 7. References . . . . . . . . . . . . . . . . . . . . . . . . 21 109 7.1. Normative References . . . . . . . . . . . . . . . . . . . 21 110 7.2. Non-Normative References . . . . . . . . . . . . . . . . . 21 112 Author's Address . . . . . . . . . . . . . . . . . . . . . 23 113 Intellectual Property and Copyright Statements . . . . . . 24 115 1. Introduction 117 1.1. Overview 119 Some applications have a need to apply [Sieve] filters in situations 120 other than initial mail delivery. This is especially true in diverse 121 service environments, such as when the client is sporadically 122 connected, is connected through a high-latency or high-cost channel, 123 or is on a limited-function device. For such clients, it may be very 124 important, for higher performance and reliability, to take advantage 125 of server capabilities, including those provided by Sieve filtering 126 (and Sieve extensions, such as [Notify]). 128 This specification defines extensions to [IMAP] to support the 129 invocation of Sieve scripts at times when the IMAP server creates new 130 messages, or modifies existing ones. It also defines how Sieve 131 scripts will process these invocations. Support for IMAPSieve 132 requires support for [Metadata] as well, since the latter is used to 133 associate scripts with IMAP mailboxes. 135 1.2. Conventions used in this document 137 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 138 "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to 139 be interpreted as described in [Keywds]. 141 2. The IMAP "IMAPSieve" Extension 143 2.1. The "IMAPSieve" Capability String 145 An IMAP server advertises support for this extension through the 146 capability string "IMAPSieve" (the string is not case-sensitive, and 147 is shown here with this capitalization for readability). A server 148 that advertises IMAPSieve is claiming to be in compliance with this 149 specification in all aspects. 151 Implementations that support IMAPSieve MUST also support 152 [Environment], because the latter defines an important way for Sieve 153 scripts to test the conditions under which they have been invoked. 155 2.2. Existing IMAP Functions Affected by IMAPSieve 157 The subsections below describe in detail the IMAP commands and 158 situations on which IMAPSieve has an effect. Not all Sieve actions 159 make sense in the case of messages affected by IMAP commands. See 160 Section 3 for details. 162 It's important to note that since the base Sieve specification (see 163 [Sieve]) and its extensions define functions for scripts that are 164 invoked during initial mail delivery, those function definitions are 165 necessarily tailored to and limited by that context. This document 166 extends those function definitions for use during IMAP events. By 167 nature of that, Sieve functions, in this extended context, may behave 168 somewhat differently, though their extended behaviour will still be 169 consistent with the functions' goals. 171 If more than one message is affected at the same time, each message 172 triggers the execution of a Sieve script separately. The scripts MAY 173 be run in parallel. 175 2.2.1. The IMAP APPEND Command 177 A message may be added to a mailbox through the IMAP APPEND command. 178 In a server that advertises IMAPSieve, new messages added in this way 179 MUST trigger the execution of a Sieve script, subject to the settings 180 defined through Metadata (see Section 2.3.1). 182 2.2.2. The IMAP MULTIAPPEND Command 184 If the IMAP server supports the IMAP [MultiAppend] extension, 185 messages may be added to a mailbox through the IMAP MULTIAPPEND 186 command. In a server that advertises IMAPSieve, new messages added 187 in this way MUST trigger the execution of a Sieve script, as with the 188 APPEND command, also subject to the settings defined through 189 Metadata. 191 2.2.3. The IMAP COPY Command 193 One or more messages may be added to a mailbox through the IMAP COPY 194 command. In a server that advertises IMAPSieve, new messages added 195 in this way MUST trigger the execution of a Sieve script, subject to 196 the settings defined through Metadata. 198 2.2.4. Changes to IMAP Message Flags 200 One or more existing messages can have their flags changed in a 201 number of ways, including: 203 o The FETCH command (may cause the \Seen flag to be set). 205 o The STORE command (may cause the \Answered, \Deleted, \Draft, 206 \Flagged, and \Seen flags to be set or reset, and may cause 207 keywords to be set or reset). 209 o The invocation of a Sieve script on an existing message, where the 210 Sieve implementation supports the [IMAP4Flags] extension and the 211 script uses one of the actions defined in that extension. 213 In a server that advertises IMAPSieve, messages whose flags are 214 changed in any way (except as explained in the next sentence) MUST 215 trigger the execution of a Sieve script, subject to the settings 216 defined through Metadata. The exception is that in order to avoid 217 script loops, flag changes that are made as a result of a script that 218 was itself invoked because of flag changes SHOULD NOT result in 219 another script invocation. In any case, implementations MUST take 220 steps to avoid such loops. 222 For flag-change events, the Sieve script will see the message flags 223 as they are AFTER the changes. 225 2.2.5. New or Changed IMAP Message Annotations 227 If the IMAP server supports the [Annotate] extension, one or more 228 existing messages can have annotations added or changed through the 229 ANNOTATE command. In a server that advertises IMAPSieve, messages 230 getting new or changed annotations MUST trigger the execution of a 231 Sieve script, subject to the settings defined through Metadata. 233 For annotation-change events, the Sieve script will see the message 234 annotations as they are AFTER the changes. 236 2.3. New Functions Defined by IMAPSieve 238 2.3.1. Changes to Metadata 240 Support for IMAPSieve requires support for [Metadata] as well, since 241 the latter is used to associate scripts with IMAP mailboxes. 243 When an applicable event occurs on an IMAP mailbox, if there is an 244 IMAP metadata entry named "/IMAPSieve/Script" for the mailbox, that 245 entry is used. If there is not, but there is an IMAP metadata entry 246 named "/IMAPSieve/Script" for the server, that entry is used 247 (providing a way to define a global script for all mailboxes on a 248 server). If neither entry exists, then no script will be invoked. 250 ALTERNATIVE TEXT FOR THE PREVIOUS PARAGRAPH, SUGGESTED BY RANDY 251 GELLENS: 253 When an applicable event occurs on an IMAP mailbox, all IMAP metadata 254 entries below the "/IMAPSieve/Script/client/" hierarchy for the 255 mailbox are run. If no per-client scripts exist, the implementation 256 checks for an IMAP metadata entry named "/IMAPSieve/Script" first on 257 the mailbox, and second on the server. If one is found, it is used. 258 This provides for per-client scripts on each mailbox, with a generic 259 per-mailbox script, and a global script for all mailboxes on a server 260 as defaults. If none exist, then no script is invoked. The entry 261 name below "/IMAPSieve/Script/client/" SHOULD be named .. For example, "Eudora.FC2302". 264 If an "/IMAPSieve/Script" metadata entry was selected above, the 265 shared value of that metadata name (its "value.shared" attribute) 266 MUST be the name of the Sieve script that will be invoked in response 267 to the IMAP event OR the name of another metadata entry, the name 268 prefixed with "metadata:" (such as "metadata:/IMAPSieve/ 269 ScriptContents"), that contains the actual script in its value.shared 270 attribute. Note that only the value.shared attribute is used; any 271 value.priv attributes are ignored. 273 This specifies the mechanism for "activating" a script for a given 274 mailbox (or for all mailboxes), but does not specify a mechanism for 275 creating, storing, or validating the script. Implementations MAY use 276 [Manage] to acomplish this, using the PUTSCRIPT command to store the 277 script without using the SETACTIVE command to activate it. In any 278 case, the script name that is specified in the /IMAPSieve/Script 279 metadata entry is in a form that depends upon how the server handles 280 the storing of Sieve scripts. 282 Only one Sieve script may be defined per mailbox, eliminating the 283 complexity and possible ambiguity involved with coordinating the 284 results of multiple scripts. Any sub-filtering is done in the Sieve 285 script. For example, if it's only necessary to deal with flag 286 changes, but not with new messages appended or copied, the Sieve 287 script will still be invoked for all events, and the script is 288 responsible for checking the event type. 290 ALTERNATIVE TEXT FOR THE PREVIOUS PARAGRAPH, SUGGESTED BY RANDY 291 GELLENS: 293 Multiple Sieve script may be defined per mailbox, allowing each 294 client to create a small scripts to serve the user, with freedom to 295 modify or delete its script at any time. Any sub-filtering is done 296 in the Sieve script. For example, if it's only necessary to deal 297 with flag changes, but not with new messages appended or copied, the 298 Sieve script will still be invoked for all events, and the script is 299 responsible for checking the event type. 301 Because this metadata name is associated with the mailbox, there can 302 (and it's expected that there will) be different scripts associated 303 with events for different mailboxes. Indeed, most mailboxes will 304 probably invoke no script at all. 306 THE REMAINDER OF THIS SECTION ARE COMMENTS SUGGESTED BY RANDY 307 GELLENS: 309 In multiple sections, the text "The implementation MAY then expunge 310 the original message" should be replaced with "After all Sieve 311 scripts have run, the implementation MAY then expunge the original 312 message". This allows each Sieve script to operate on the message. 313 One or more of the scripts may mark the message as \deleted, and 314 after all have run, the message MAY be expunged. 316 I also suggest adding a new section, called something such as 317 "Automatic Deletion of Old Scripts": 319 Implementations MAY keep track of the modification date of each 320 script under the "/IMAPSieve/Script/client/" hierarchy of each 321 mailbox. Any script that is older than an implementation-defined 322 period MAY be removed. The expiration period SHOULD be at least 323 ninety days. This allows implementations to prune scripts created by 324 clients no longer in use. Clients SHOULD refresh their scripts at 325 least every eighty days. 327 3. Applicable Sieve Actions and Interactions 329 Since some Sieve actions relate specifically to the delivery of mail, 330 not all actions make sense when the messages are created by other 331 means or when changes are made to data associated with existing 332 messages. This section describes how actions in the base Sieve 333 specification, and those in extensions known at this writing, relate 334 to this specification. 336 In addition to what is specified here, interactions noted in the 337 individual specifications apply, and must be considered. 339 3.1. The Implicit Keep 341 For all cases that fall under IMAPSieve, the implicit keep means that 342 the message is treated as it would have been if no Sieve script were 343 run. For APPEND, MULTIAPPEND and COPY, the message is stored into 344 the target mailbox normally. For flag or annotation changes, the 345 message is left in the mailbox. 347 3.2. The Keep Action 349 The keep action is applicable in all cases that fall under IMAPSieve. 350 Its behaviour is as described for implicit keep, in Section 3.1. 352 3.3. The Fileinto Action 354 If the Sieve implementation supports the fileinto action, that action 355 is applicable in all cases that fall under IMAPSieve. If the [Copy] 356 extension is available and the :copy option is specified, the 357 implicit keep is retained; otherwise, fileinto cancels the implicit 358 keep, as specified in the base Sieve specification. 360 For APPEND, MULTIAPPEND, and COPY, the message is stored into the 361 fileinto mailbox IN ADDITION TO the original target mailbox. For 362 flag or annotation changes, the message is COPIED into the fileinto 363 mailbox, without removing the original. 365 If a keep action is NOT also in effect, the original message is then 366 marked with the \Deleted flag (and a flag-change Sieve script is NOT 367 invoked). The implementation MAY then expunge the original message 368 (WITHOUT expunging other messages in the mailbox), or it MAY choose 369 to have expunges batched, or done by a user. The effect is as though 370 a client had flagged the message and done a UID EXPUNGE (see 371 [UIDPlus]). Handling it this way allows clients to handle messages 372 consistently, and avoids hidden changes that might invalidate their 373 message caches. 375 3.4. The Redirect Action 377 The redirect action is applicable in all cases that fall under 378 IMAPSieve. It causes the message to be sent, as specified in the 379 base Sieve specification, to the designated address. If the [Copy] 380 extension is available and the :copy option is specified, the 381 implicit keep is retained; otherwise, redirect cancels the implicit 382 keep, as specified in the base Sieve specification. 384 For APPEND, MULTIAPPEND, and COPY, the message is stored into the 385 target mailbox in addition to being redirected. For flag or 386 annotation changes, the message remains in its original mailbox. 388 If a keep action is NOT also in effect, the original message is then 389 marked with the \Deleted flag (and a flag-change Sieve script is NOT 390 invoked). The implementation MAY then expunge the original message 391 (WITHOUT expunging other messages in the mailbox), or it MAY choose 392 to have expunges batched, or done by a user. The effect is as though 393 a client had flagged the message and done a UID EXPUNGE (see 394 [UIDPlus]). Handling it this way allows clients to handle messages 395 consistently, and avoids hidden changes that might invalidate their 396 message caches. 398 3.5. The Reject Action 400 The reject action is NOT applicable to any case that falls under 401 IMAPSieve. Its use MUST result in an error condition that will 402 terminate the Sieve script. 404 3.6. The Discard Action 406 The discard action is applicable in all cases that fall under 407 IMAPSieve. For APPEND, MULTIAPPEND, and COPY, the message is first 408 stored into the target mailbox. If an explicit keep action is also 409 in effect, the discard action now does nothing. Otherwise, the 410 original message is then marked with the \Deleted flag (and a flag- 411 change Sieve script is NOT invoked). The implementation MAY then 412 expunge the original message (WITHOUT expunging other messages in the 413 mailbox), or it MAY choose to have expunges batched, or done by a 414 user. The effect is as though a client had flagged the message and 415 done a UID EXPUNGE (see [UIDPlus]). Handling it this way allows 416 clients to handle messages consistently, and avoids hidden changes 417 that might invalidate their message caches. 419 3.7. The Notify Action 421 If the [Notify] extension is available, the notify action is 422 applicable in all cases that fall under IMAPSieve. The result is 423 that the requested notification is sent, and that the message is 424 otherwise handled as it would normally have been. 426 3.8. The Addheader and Deleteheader Actions 428 Even if the [EditHeader] extension is available, since messages in 429 IMAP mailboxes are immutable these actions are NOT applicable. Use 430 of these MUST result in an error condition that will terminate the 431 Sieve script. Explanation: Using them for flag or annotation changes 432 to existing messages would cause the message to be changed. Using 433 them for APPEND, MULTIAPPEND, and COPY would cause unexpected 434 differences in the stored copy as compared to what the client 435 expected, and would make the client's message cache invalid 436 unexpectedly. 438 3.9. The Setflag, Deleteflag, and Removeflag Actions 440 If the [IMAP4Flags] extension is available, the actions associated 441 with it are all applicable to any case that falls under IMAPSieve. 442 It is worth noting also that the "hasflag" test that is defined in 443 the IMAP4Flags extension might be particularly useful in scripts 444 triggered by flag changes ("hasflag" will see the new, changed 445 flags). The flag changes behave as though a client had made the 446 change. 448 As explained above, in order to avoid script loops flag changes that 449 are made as a result of a script that was itself invoked because of 450 flag changes SHOULD NOT result in another script invocation. In any 451 case, implementations MUST take steps to avoid such loops. 453 3.10. The Vacation Action 455 Even if the [Vacation] extension is available, the vacation action is 456 NOT applicable to any case that falls under IMAPSieve. Its use MUST 457 result in an error condition that will terminate the Sieve script. 459 3.11. New Sieve Environment Item: cause 461 Implementations MAY invoke different Sieve scripts for the different 462 conditions described in this document (append, copy, flag changes, 463 annotation changes). If the actions to be taken are common, and the 464 implementation supports the [Include] extension, the common script 465 code can be included as specified there. 467 It may be preferable, though, to use a single script for all these 468 conditions. To support that, if the [Environment] extension is 469 available, the implementation MUST set the environment item "cause", 470 which contains the name of the action that caused the script to be 471 invoked. Its value is one of the following: 473 o APPEND (for invocations resulting from APPEND or MULTIAPPEND) 475 o COPY (for invocations resulting from COPY) 477 o FLAG (for invocations resulting from flag changes) 479 o ANNOTATE (for invocations resulting from new or changed 480 annotations) 482 3.12. New Sieve Environment Item: mailbox 484 If the [Environment] extension is available, the implementation MUST 485 set the environment item "mailbox" to the name of the mailbox that 486 the affected message is in, in the case of existing messages, or is 487 targeted to be stored into, in the case of new messages. The value 488 of this item is fixed when the script begins, and, in particular, 489 MUST NOT change as a result of any action, such as "fileinto". 491 3.13. New Sieve Environment Item: changedflags 493 If the [Environment] extension is available, the [IMAP4Flags] 494 extension is available, AND the script was invoked because of flag 495 changes to an existing message, the implementation MUST set the 496 environment item "changedflags" to the name(s) of the flag(s) that 497 have changed. If the script was not invoked because of flag changes, 498 the value of this item MUST be the empty string. The script will not 499 know from this item whether the flags have been set or reset, but it 500 can use the "hasflag" test to determine the current value. See 501 example 2 in Section 4 for an example of how this might be used. 503 3.14. New Sieve Environment Item: changedannotations 505 If the [Environment] extension is available, the [Annotate] extension 506 is available, AND the script was invoked because of annotation 507 changes to an existing message, the implementation MUST set the 508 environment item "changedannotations" to the name(s) of the 509 annotation(s) that have changed. If the script was not invoked 510 because of annotation changes, the value of this item MUST be the 511 empty string. 513 3.15. Interaction With Sieve Tests (Comparisons) 515 This extension does not affect the operation of any tests or 516 comparisons. 518 4. Examples 520 Example 1: 521 If a new message is added to the "ActionItems" mailbox, a copy is 522 sent to the address "actionitems@example.com". 524 require ["copy", "environment"]; 526 if anyof (environment :is "cause" "APPEND", 527 environment :is "cause" "COPY") { 528 if environment :is "mailbox" "ActionItems" { 529 redirect :copy "actionitems@example.com"; 530 } 531 } 533 Example 2: 534 If the script is called for any message with the \Flagged flag set 535 (tested through the [IMAP4Flags] extension), a notification is sent 536 using the [Notify] extension. No notification will be sent, though, 537 if we're called with an existing message that already had that flag 538 set. 540 require ["nofity", "imap4flags", "variables", "environment"]; 542 if environment :matches "mailbox" "*" { 543 set "mailbox" "${1}"; 544 } 546 if allof (hasflag "\\Flagged", 547 not environment :contains "changedflags" "\\Flagged") { 548 notify :message "Important message in ${mailbox}"; 549 } 551 5. Security Considerations 553 It is possible to introduce script processing loops by having a Sieve 554 script that is triggered by flag changes use the actions defined in 555 the [IMAP4Flags] extension. Implementations MUST take steps to 556 prevent such loops. One way to avoid this problem is that if a 557 script is invoked by flag changes, and that script further changes 558 the flags, those flag changes SHOULD NOT trigger a Sieve script 559 invocation. 561 Other security considerations are discussed in [IMAP], and [Sieve], 562 as well as in some of the other extension documents. 564 6. IANA Considerations 566 6.1. Registration of imapsieve extension 568 The following template specifies the IANA registration of the Sieve 569 extension specified in this document: 571 To: iana@iana.org 572 Subject: Registration of new Sieve extension 573 Capability name: imapsieve 574 Description: Add Sieve processing for IMAP events. 575 RFC number: this RFC 576 Contact address: Barry Leiba 578 This information should be added to the list of sieve extensions 579 given on http://www.iana.org/assignments/sieve-extensions. 581 6.2. Registration of environment item: cause 583 The following template specifies the IANA registration of a sieve 584 environment item specified in this document: 586 To: iana@iana.org 587 Subject: Registration of new Sieve environment item 588 Item name: cause 589 Description: The name of the action that caused the script to be 590 invoked. Its value is one of the following: 592 o APPEND (for invocations resulting from APPEND or MULTIAPPEND) 594 o COPY (for invocations resulting from COPY) 596 o FLAG (for invocations resulting from flag changes) 598 o ANNOTATE (for invocations resulting from new or changed 599 annotations) 601 RFC number: this RFC 602 Contact address: 603 Barry Leiba 605 This information should be added to the list of sieve environment 606 item names given in the [Environment] extension. 608 6.3. Registration of environment item: mailbox 610 The following template specifies the IANA registration of a sieve 611 environment item specified in this document: 613 To: iana@iana.org 614 Subject: Registration of new Sieve environment item 615 Item name: mailbox 616 Description: The name of the mailbox that the affected message is in, 617 in the case of existing messages, or is targeted to be stored into, 618 in the case of new messages. The value of this item is fixed when 619 the script begins, and, in particular, MUST NOT change as a result of 620 any action, such as "fileinto". 621 RFC number: this RFC 622 Contact address: 623 Barry Leiba 625 This information should be added to the list of sieve environment 626 item names given in the [Environment] extension. 628 6.4. Registration of environment item: changedflags 630 The following template specifies the IANA registration of a sieve 631 environment item specified in this document: 633 To: iana@iana.org 634 Subject: Registration of new Sieve environment item 635 Item name: changedflags 636 Description: If the script was invoked because of flag changes to an 637 existing message, this contains the name(s) of the flag(s) that have 638 changed. Otherwise, the value of this item MUST be the empty string. 639 RFC number: this RFC 640 Contact address: 641 Barry Leiba 643 This information should be added to the list of sieve environment 644 item names given in the [Environment] extension. 646 6.5. Registration of environment item: changedannotations 648 The following template specifies the IANA registration of a sieve 649 environment item specified in this document: 651 To: iana@iana.org 652 Subject: Registration of new Sieve environment item 653 Item name: changedannotations 654 Description: If the script was invoked because of annotation changes 655 to an existing message, this contains the name(s) of the 656 annotation(s) that have changed. Otherwise, the value of this item 657 MUST be the empty string. 658 RFC number: this RFC 659 Contact address: 660 Barry Leiba 662 This information should be added to the list of sieve environment 663 item names given in the [Environment] extension. 665 6.6. Registration of IMAP METADATA mailbox entry name 667 The following template specifies the IANA registration of an IMAP 668 METADATA entry name specified in this document: 670 To: iana@iana.org 671 Subject: IMAP METADATA Registration 672 Please register the following IMAP METADATA item: 673 [x] Entry [ ] Attribute 674 [x] Mailbox [ ] Server 675 Name: /IMAPSieve/Script 676 Description: This entry name is used to define mailbox metadata 677 associated with IMAPSieve events for the associated mailbox. 678 Specifically, this specifies the Sieve script that will be invoked 679 when IMAP events occur on the specified mailbox. 680 Content-type: text/plain; charset=utf-8 681 RFC number: this RFC 682 Contact person: Barry Leiba 683 Contact email: leiba@watson.ibm.com 685 This information should be added to the list of IMAP METADATA item 686 names given in the [Metadata] extension. 688 6.7. Registration of IMAP METADATA server entry name 690 The following template specifies the IANA registration of an IMAP 691 METADATA entry name specified in this document: 693 To: iana@iana.org 694 Subject: IMAP METADATA Registration 695 Please register the following IMAP METADATA item: 696 [x] Entry [ ] Attribute 697 [ ] Mailbox [x] Server 698 Name: /IMAPSieve/Script 699 Description: This entry name is used to define metadata associated 700 globally with IMAPSieve events for the associated server. 701 Specifically, this specifies the Sieve script that will be invoked 702 when IMAP events occur on any mailbox in the server that does not 703 have its own mailbox-level /IMAPSieve/Script entry. 704 Content-type: text/plain; charset=utf-8 705 RFC number: this RFC 706 Contact person: Barry Leiba 707 Contact email: leiba@watson.ibm.com 709 This information should be added to the list of IMAP METADATA item 710 names given in the [Metadata] extension. 712 7. References 714 7.1. Normative References 716 [Annotate] 717 Daboo, C. and R. Gellens, "IMAP ANNOTATE Extension", RFC 718 Editor Queue, draft-ietf-imapext-annotate-16, August 2006. 720 [Copy] Degener, J., "Sieve Extension: Copying Without Side 721 Effects", RFC 3894, October 2004. 723 [Environment] 724 Freed, N., "Sieve Email Filtering: Environment and Ihave 725 Extensions", work in 726 progress, draft-freed-sieve-environment-ihave-00, 727 November 2006. 729 [IMAP] Crispin, M., "Internet Message Access Protocol - Version 730 4rev1", RFC 3501, March 2003. 732 [IMAP4Flags] 733 Melnikov, A., "Sieve Mail Filtering Language: IMAP flag 734 Extension", RFC Editor 735 Queue, draft-ietf-sieve-imapflags-05, May 2006. 737 [Keywds] Bradner, S., "Key words for use in RFCs to Indicate 738 Requirement Levels", RFC 2119, March 1997. 740 [Metadata] 741 Daboo, C., "IMAP METADATA Extension", work in 742 progress, draft-daboo-imap-annotatemore-11, February 2007. 744 [MultiAppend] 745 Crispin, M., "Internet Message Access Protocol (IMAP) - 746 MULTIAPPEND Extension", RFC 3502, March 2003. 748 [Sieve] Guenther, P., Ed. and T. Showalter, Ed., "Sieve: An Email 749 Filtering Language", IESG 750 Evaluation, draft-ietf-sieve-3028bis-12, February 2007. 752 7.2. Non-Normative References 754 [EditHeader] 755 Degener, J. and P. Guenther, "Sieve Email Filtering: 756 Editheader Extension", work in 757 progress, draft-ietf-sieve-editheader-07, November 2006. 759 [Include] Daboo, C., "SIEVE Email Filtering: Include Extension", 760 work in progress, draft-daboo-sieve-include-05, June 2006. 762 [Manage] Martin, T. and A. Melnikov, Ed., "A Protocol for Remotely 763 Managing Sieve Scripts", work in 764 progress, draft-martin-managesieve-07, November 2006. 766 [Notify] Melnikov, A., Ed., Leiba, B., Ed., Segmuller, W., and T. 767 Martin, "Sieve Extension: Notifications", work in 768 progress, draft-ietf-sieve-notify-07, February 2007. 770 [UIDPlus] Crispin, M., "Internet Message Access Protocol (IMAP) - 771 UIDPLUS Extension", RFC 4315, December 2005. 773 [Vacation] 774 Showalter, T. and N. Freed, Ed., "Sieve Email Filtering: 775 Vacation Extension", RFC Editor 776 Queue, draft-ietf-sieve-vacation-06, February 2006. 778 Author's Address 780 Barry Leiba 781 IBM T.J. Watson Research Center 782 19 Skyline Drive 783 Hawthorne, NY 10532 784 US 786 Phone: +1 914 784 7941 787 Email: leiba@watson.ibm.com 789 Full Copyright Statement 791 Copyright (C) The IETF Trust (2007). 793 This document is subject to the rights, licenses and restrictions 794 contained in BCP 78, and except as set forth therein, the authors 795 retain all their rights. 797 This document and the information contained herein are provided on an 798 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 799 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 800 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 801 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 802 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 803 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 805 Intellectual Property 807 The IETF takes no position regarding the validity or scope of any 808 Intellectual Property Rights or other rights that might be claimed to 809 pertain to the implementation or use of the technology described in 810 this document or the extent to which any license under such rights 811 might or might not be available; nor does it represent that it has 812 made any independent effort to identify any such rights. Information 813 on the procedures with respect to rights in RFC documents can be 814 found in BCP 78 and BCP 79. 816 Copies of IPR disclosures made to the IETF Secretariat and any 817 assurances of licenses to be made available, or the result of an 818 attempt made to obtain a general license or permission for the use of 819 such proprietary rights by implementers or users of this 820 specification can be obtained from the IETF on-line IPR repository at 821 http://www.ietf.org/ipr. 823 The IETF invites any interested party to bring to its attention any 824 copyrights, patents or patent applications, or other proprietary 825 rights that may cover technology that may be required to implement 826 this standard. Please address the information to the IETF at 827 ietf-ipr@ietf.org. 829 Acknowledgment 831 Funding for the RFC Editor function is provided by the IETF 832 Administrative Support Activity (IASA).