idnits 2.17.1 draft-ietf-sieve-imap-sieve-04.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. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 30, 2012) is 4346 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 (==), 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 May 30, 2012 5 Expires: December 1, 2012 7 Support for Internet Message Access Protocol (IMAP) Events in Sieve 8 draft-ietf-sieve-imap-sieve-04 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 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on December 1, 2012. 37 Copyright Notice 39 Copyright (c) 2012 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4 55 1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 1.2. Differences Between IMAP Events and Mail Delivery . . . . 4 57 1.3. Conventions used in this document . . . . . . . . . . . . 5 59 2. The IMAP Events in Sieve Extension . . . . . . . . . . . . 6 60 2.1. The "imapsieve" Capability Strings . . . . . . . . . . . . 6 61 2.2. Existing IMAP Functions Affected by IMAP events in 62 Sieve . . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 2.2.1. The IMAP APPEND Command . . . . . . . . . . . . . . . . . 7 64 2.2.2. The IMAP MULTIAPPEND Command . . . . . . . . . . . . . . . 7 65 2.2.3. The IMAP COPY Command . . . . . . . . . . . . . . . . . . 7 66 2.2.4. Changes to IMAP Message Flags . . . . . . . . . . . . . . 7 67 2.3. New Functions Defined by IMAP events in Sieve . . . . . . 8 68 2.3.1. Interaction with Metadata . . . . . . . . . . . . . . . . 8 70 3. Applicable Sieve Actions and Interactions . . . . . . . . 10 71 3.1. The Implicit Keep . . . . . . . . . . . . . . . . . . . . 10 72 3.2. The Keep Action . . . . . . . . . . . . . . . . . . . . . 10 73 3.3. The Fileinto Action . . . . . . . . . . . . . . . . . . . 10 74 3.4. The Redirect Action . . . . . . . . . . . . . . . . . . . 11 75 3.5. The Discard Action . . . . . . . . . . . . . . . . . . . . 11 76 3.6. The Notify Action . . . . . . . . . . . . . . . . . . . . 12 77 3.7. The Addheader and Deleteheader Actions . . . . . . . . . . 12 78 3.8. The Setflag, Deleteflag, and Removeflag Actions . . . . . 12 79 3.9. MIME Part Tests and Replacement . . . . . . . . . . . . . 12 80 3.10. Spamtest and Virustest . . . . . . . . . . . . . . . . . . 13 81 3.11. Inapplicable Actions . . . . . . . . . . . . . . . . . . . 13 83 4. Interaction With Sieve Environment . . . . . . . . . . . . 14 84 4.1. Base Sieve Environment Items: location and phase . . . . . 14 85 4.2. New Sieve Environment Items: imapuser and imapemail . . . 14 86 4.3. New Sieve Environment Item: cause . . . . . . . . . . . . 14 87 4.4. New Sieve Environment Item: mailbox . . . . . . . . . . . 15 88 4.5. New Sieve Environment Item: changedflags . . . . . . . . . 15 89 4.6. Interaction With Sieve Tests (Comparisons) . . . . . . . . 15 91 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 16 93 6. Security Considerations . . . . . . . . . . . . . . . . . 17 95 7. IANA Considerations . . . . . . . . . . . . . . . . . . . 18 96 7.1. Registration of "imapsieve" IMAP capability . . . . . . . 18 97 7.2. Registration of "imapsieve" Sieve extension . . . . . . . 18 98 7.3. Registration of Sieve Environment Items . . . . . . . . . 18 99 7.3.1. Registration of Sieve Environment Item: cause . . . . . . 18 100 7.3.2. Registration of Sieve Environment Item: mailbox . . . . . 19 101 7.3.3. Registration of Sieve Environment Item: changedflags . . . 19 102 7.3.4. Registration of Sieve Environment Item: imapuser . . . . . 19 103 7.3.5. Registration of Sieve Environment Item: imapemail . . . . 19 104 7.4. Registration of IMAP METADATA Mailbox Entry Name . . . . . 19 105 7.5. Registration of IMAP METADATA Server Entry Name . . . . . 20 107 8. References . . . . . . . . . . . . . . . . . . . . . . . . 21 108 8.1. Normative References . . . . . . . . . . . . . . . . . . . 21 109 8.2. Informative References . . . . . . . . . . . . . . . . . . 21 111 Author's Address . . . . . . . . . . . . . . . . . . . . . 23 113 1. Introduction 115 1.1. Overview 117 Some applications have a need to apply Sieve filters [RFC5228] in 118 contexts other than initial mail delivery. This is especially true 119 in diverse service environments, such as when the client is 120 sporadically connected, is connected through a high-latency or high- 121 cost channel, or is on a limited-function device. For such clients, 122 it may be very important, for higher performance and reliability, to 123 take advantage of server capabilities, including those provided by 124 Sieve filtering (and Sieve extensions, such as Notify [RFC5435]). 126 This specification defines extensions to IMAP [RFC3501] to support 127 the invocation of Sieve scripts at times when the IMAP server creates 128 new messages or modifies existing ones. It also defines how Sieve 129 scripts will process these invocations. Support for IMAP events in 130 Sieve requires support for IMAP Metadata [RFC5464] and Sieve 131 Environment [RFC5183] as well, because Metadata is used to associate 132 scripts with IMAP mailboxes and Environment defines an important way 133 for Sieve scripts to test the conditions under which they have been 134 invoked. 136 1.2. Differences Between IMAP Events and Mail Delivery 138 Invoking Sieve scripts in a context other than initial mail delivery 139 introduces new situations, which changes the applicability of Sieve 140 features and creates implementation challenges and user interface 141 issues. This section discusses some of those differences, 142 challenges, and issues. 144 At times other than message delivery, delivery "envelope" 145 information, might not be available. With messages added through 146 IMAP APPEND, there might be no way to even guess who the intended 147 recipient is, and no concept of who "sent" the message. Sieve 148 actions that relate to contacting the sender, for example, will not 149 be applicable. 151 Because IMAP events will often be triggered by user actions, and 152 because user interfaces allow bulk actions that differ from 153 individual message arrival, it now becomes possible for a single user 154 action, such as drag-and-drop, to initiate Sieve script processing on 155 a large number of messages at once. Implementations will have to 156 deal with such situations as a "COPY" action or flag changes on 157 dozens, or even thousands of messages. 159 Other issues might surface as this extension is deployed and 160 experience with it develops. 162 1.3. Conventions used in this document 164 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 165 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 166 document are to be interpreted as described in [RFC2119]. 168 2. The IMAP Events in Sieve Extension 170 2.1. The "imapsieve" Capability Strings 172 An IMAP server advertises support for IMAP events in Sieve through 173 the "imapsieve" capability. A server that advertises "imapsieve" is 174 claiming to be in compliance with this specification in all aspects. 175 The syntax of the "imapsieve" capability string is defined as 176 follows: 178 capability /= "IMAPSIEVE=" sieveurl-server 179 ; is defined in RFC 5804, Section 3 181 Only one "imapsieve" capability string, specifying one sieveurl- 182 server, can be present. 184 The corresponding Sieve implementation uses the Sieve capability 185 string "imapsieve", and Sieve scripts that depend upon the IMAP 186 events MUST include that string in their "required" lists. 188 Implementations that support IMAP events in Sieve MUST also support 189 IMAP Metadata [RFC5464] and Sieve Environment [RFC5183], because 190 Metadata is used to associate scripts with IMAP mailboxes and 191 Environment defines an important way for Sieve scripts to test the 192 conditions under which they have been invoked. Notwithstanding the 193 support requirement, scripts that directly use Environment MUST also 194 include its capability string in their "required" lists. 196 2.2. Existing IMAP Functions Affected by IMAP events in Sieve 198 The subsections below describe in detail the IMAP commands and 199 situations on which IMAP events in Sieve have an effect. Not all 200 Sieve actions make sense in the case of messages affected by IMAP 201 commands. See Section 3 for details. 203 It's important to note that since the base Sieve specification (see 204 [RFC5228]) and its extensions define functions for scripts that are 205 invoked during initial mail delivery, those function definitions are 206 necessarily tailored to and limited by that context. This document 207 extends those function definitions for use during IMAP events. By 208 nature of that, Sieve functions, in this extended context, may behave 209 somewhat differently, though their extended behaviour will still be 210 consistent with the functions' goals. 212 If more than one message is affected at the same time, each message 213 triggers the execution of a Sieve script separately. The scripts MAY 214 be run in parallel. 216 2.2.1. The IMAP APPEND Command 218 A message may be added to a mailbox through the IMAP APPEND command. 219 In a server that advertises "imapsieve", new messages added in this 220 way MUST trigger the execution of a Sieve script, subject to the 221 settings defined through Metadata (see Section 2.3.1). 223 2.2.2. The IMAP MULTIAPPEND Command 225 If the IMAP server supports the IMAP MultiAppend extension [RFC3502], 226 messages may be added to a mailbox through the IMAP MULTIAPPEND 227 command. In a server that advertises "imapsieve", new messages added 228 in this way MUST trigger the execution of a Sieve script, as with the 229 APPEND command, also subject to the settings defined through 230 Metadata. 232 2.2.3. The IMAP COPY Command 234 One or more messages may be added to a mailbox through the IMAP COPY 235 command. In a server that advertises "imapsieve", new messages added 236 in this way MUST trigger the execution of a Sieve script, subject to 237 the settings defined through Metadata. 239 2.2.4. Changes to IMAP Message Flags 241 One or more existing messages can have their flags changed in a 242 number of ways, including: 244 o The FETCH command (may cause the \Seen flag to be set). 246 o The STORE command (may cause the \Answered, \Deleted, \Draft, 247 \Flagged, and \Seen flags to be set or reset, and may cause 248 keywords to be set or reset). 250 o The invocation of a Sieve script on an existing message, where the 251 Sieve implementation supports the IMAP4Flags extension [RFC5232] 252 and the script uses one of the actions defined in that extension. 254 In a server that advertises "imapsieve", messages whose flags are 255 changed in any way (except as explained in the next sentence) MUST 256 trigger the execution of a Sieve script, subject to the settings 257 defined through Metadata. The exception is that in order to avoid 258 script loops, flag changes that are made as a result of a script that 259 was itself invoked because of flag changes SHOULD NOT result in 260 another script invocation. In any case, implementations MUST take 261 steps to avoid such loops. 263 For flag-change events, the Sieve script will see the message flags 264 as they are AFTER the changes. 266 2.3. New Functions Defined by IMAP events in Sieve 268 2.3.1. Interaction with Metadata 270 Support for IMAP events in Sieve requires support for IMAP Metadata 271 [RFC5464] as well, since the latter is used to associate scripts with 272 IMAP mailboxes. 274 When an applicable event occurs on an IMAP mailbox, if there is an 275 IMAP metadata entry named "/IMAPSieve/Script" for the mailbox, that 276 entry is used. If there is not, but there is an IMAP metadata entry 277 named "/IMAPSieve/Script" for the server, that entry is used 278 (providing a way to define a global script for all mailboxes on a 279 server). If neither entry exists, then no script will be invoked. 281 If an "/IMAPSieve/Script" metadata entry was selected above, the 282 shared value of that metadata name (its "value.shared" attribute) 283 MUST be the name of the Sieve script that will be invoked in response 284 to the IMAP event. Note that only the value.shared attribute is 285 used; any value.priv attributes are ignored. 287 This specifies the mechanism for "activating" a script for a given 288 mailbox (or for all mailboxes), but does not specify a mechanism for 289 creating, storing, or validating the script. Implementations MUST 290 support ManageSieve [RFC5804], and can use the PUTSCRIPT command to 291 store the script without using the SETACTIVE command to activate it. 293 Script names used in "/IMAPSieve/Script" metadata entries are the 294 script names used on the corresponding ManageSieve server. If an 295 "/IMAPSieve/Script" metadata entry contains a script name that 296 doesn't exist in the ManageSieve server, then no Sieve script will be 297 invoked for IMAP Sieve events. 299 Only one Sieve script may currently be defined per mailbox, 300 eliminating the complexity and possible ambiguity involved with 301 coordinating the results of multiple scripts. Any sub-filtering is 302 done in the Sieve script. For example, if it's only necessary to 303 deal with flag changes, but not with new messages appended or copied, 304 the Sieve script will still be invoked for all events, and the script 305 is responsible for checking the event type. 307 The possibility is open for an extension to add support for multiple 308 scripts -- for example, per-client scripts on a multi-client user's 309 inbox, or per-user scripts on a mailbox that is shared among users. 311 Because this metadata name is associated with the mailbox, there can 312 (and it's expected that there will) be different scripts associated 313 with events for different mailboxes. Indeed, most mailboxes will 314 probably invoke no script at all. 316 3. Applicable Sieve Actions and Interactions 318 Since some Sieve actions relate specifically to the delivery of mail, 319 not all actions and extensions make sense when the messages are 320 created by other means or when changes are made to data associated 321 with existing messages. This section describes how actions in the 322 base Sieve specification, and those in extensions known at this 323 writing, relate to this specification. 325 In addition to what is specified here, interactions noted in the 326 individual specifications apply, and must be considered. 328 3.1. The Implicit Keep 330 For all cases that fall under IMAP events in Sieve, the implicit keep 331 means that the message is treated as it would have been if no Sieve 332 script were run. For APPEND, MULTIAPPEND and COPY, the message is 333 stored into the target mailbox normally. For flag changes, the 334 message is left in the mailbox. If actions have been taken that 335 change the message, those changes are considered transient and MUST 336 NOT be retained for any keep action (because IMAP messages are 337 immutable). No error is generated, but the original message, without 338 the changes, is kept. 340 3.2. The Keep Action 342 The keep action is applicable in all cases that fall under IMAP 343 events in Sieve. Its behaviour is as described for implicit keep, in 344 Section 3.1. 346 3.3. The Fileinto Action 348 If the Sieve implementation supports the fileinto action, that action 349 is applicable in all cases that fall under IMAP events in Sieve. If 350 the Copy extension [RFC3894] is available and the :copy option is 351 specified, the implicit keep is retained; otherwise, fileinto cancels 352 the implicit keep, as specified in the base Sieve specification. 354 For APPEND, MULTIAPPEND, and COPY, the message is stored into the 355 fileinto mailbox IN ADDITION TO the original target mailbox. For 356 flag changes, the message is COPIED into the fileinto mailbox, 357 without removing the original. 359 If a keep action is NOT also in effect, the original message is then 360 marked with the \Deleted flag (and a flag-change Sieve script is NOT 361 invoked). The implementation MAY then expunge the original message 362 (WITHOUT expunging other messages in the mailbox), or it MAY choose 363 to have expunges batched, or done by a user. If the server does the 364 expunge, the effect is as though a client had flagged the message and 365 done a UID EXPUNGE (see [RFC4315]) on the affected message(s) only. 366 Handling it this way allows clients to handle messages consistently, 367 and avoids hidden changes that might invalidate their message caches. 369 3.4. The Redirect Action 371 The redirect action is applicable in all cases that fall under IMAP 372 events in Sieve. It causes the message to be sent, as specified in 373 the base Sieve specification, to the designated address. If the Copy 374 extension [RFC3894] is available and the :copy option is specified, 375 the implicit keep is retained; otherwise, redirect cancels the 376 implicit keep, as specified in the base Sieve specification. 378 It's possible that a message processed in this way does not have the 379 information necessary to be redirected properly. It might lack 380 necessary header information, and there might not be appropriate 381 information for the MAIL FROM command. In such cases, the "redirect" 382 action uses Message Submission [RFC6409], and it is up to the Sieve 383 engine to supply the missing information. The redirect address is, 384 of course, used for the "RCPT TO", and the "MAIL FROM" SHOULD be set 385 to the address of the owner of the mailbox. The message submission 386 server is allowed, according to the Message Submission protocol, to 387 perform necessary fix-up to the message (see section 8 of RFC 6409). 388 It can also reject the submission attempt, if the message is too ill- 389 formed for submission. 391 For APPEND, MULTIAPPEND, and COPY, the message is stored into the 392 target mailbox in addition to being redirected. For flag changes, 393 the message remains in its original mailbox. 395 If a keep action is NOT also in effect, the original message is then 396 marked with the \Deleted flag (and a flag-change Sieve script is NOT 397 invoked). The implementation MAY then expunge the original message 398 (WITHOUT expunging other messages in the mailbox), or it MAY choose 399 to have expunges batched, or done by a user. If the server does the 400 expunge, the effect is as though a client had flagged the message and 401 done a UID EXPUNGE (see [RFC4315]) on the affected message(s) only. 402 Handling it this way allows clients to handle messages consistently, 403 and avoids hidden changes that might invalidate their message caches. 405 3.5. The Discard Action 407 The discard action is applicable in all cases that fall under IMAP 408 events in Sieve. For APPEND, MULTIAPPEND, and COPY, the message is 409 first stored into the target mailbox. If an explicit keep action is 410 also in effect, the discard action now does nothing. Otherwise, the 411 original message is then marked with the \Deleted flag (and a flag- 412 change Sieve script is NOT invoked). The implementation MAY then 413 expunge the original message (WITHOUT expunging other messages in the 414 mailbox), or it MAY choose to have expunges batched, or done by a 415 user. If the server does the expunge, the effect is as though a 416 client had flagged the message and done a UID EXPUNGE (see [RFC4315]) 417 on the affected message(s) only. Handling it this way allows clients 418 to handle messages consistently, and avoids hidden changes that might 419 invalidate their message caches. 421 3.6. The Notify Action 423 If the Nofity extension [RFC5435] is available, the notify action is 424 applicable in all cases that fall under IMAP events in Sieve. The 425 result is that the requested notification is sent, and that the 426 message is otherwise handled as it would normally have been. 428 3.7. The Addheader and Deleteheader Actions 430 If the EditHeader extension [RFC5293] is available, it can be used to 431 make transient changes to header fields, which aren't saved in place, 432 such as for "redirect" or "fileinto" actions. Because messages in 433 IMAP mailboxes are immutable, such changes are NOT applicable for the 434 "keep" acton (explicit or implicit). See Section 3.1. 436 3.8. The Setflag, Deleteflag, and Removeflag Actions 438 Implementations of IMAP events in Sieve MUST also support the 439 IMAP4Flags extension [RFC5232], and the actions associated with it 440 are all applicable to any case that falls under IMAP events in Sieve. 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.9. MIME Part Tests and Replacement 455 If the MIME Part Tests extension [RFC5703] is available, all of its 456 functions can be used, but any changes made to the message, using the 457 "replace" or "enclose" action, MUST be considered transient, and are 458 only applicable with actions such as "redirect" and "fileinto". 459 Because messages in IMAP mailboxes are immutable, such changes are 460 NOT applicable for the "keep" acton (explicit or implicit). See 461 Section 3.1. 463 3.10. Spamtest and Virustest 465 If the Spamtest and Virustest extensions [RFC5235] are available, 466 they are applicable in all cases that fall under IMAP events in 467 Sieve. 469 3.11. Inapplicable Actions 471 The following actions and extensions are NOT applicable to any case 472 that falls under IMAP events in Sieve, because they are specifically 473 designed to respond to delivery of a new email message. Their 474 appearance in the "require" control or their use in an IMAP event 475 MUST result in an error condition that will terminate the Sieve 476 script: 478 reject [RFC5228] 480 ereject [RFC5429] 482 vacation [RFC5230] 484 Future extensions that are specifically designed to respond to 485 delivery of a new email message will likewise not be applicable to 486 this extension. 488 4. Interaction With Sieve Environment 490 4.1. Base Sieve Environment Items: location and phase 492 The Sieve Environment extension defines a set of standard environment 493 items (see [RFC5183], Section 4.1). Two of those items are affected 494 when the script is invoked through an IMAP event. 496 The value of "location" is set to "MS" -- evaluation is being 497 performed by a Message Store. 499 The value of "phase" is set to "post" -- processing is taking place 500 after (or perhaps instead of, in the case of APPEND) final delivery. 502 4.2. New Sieve Environment Items: imapuser and imapemail 504 In the normal case, when Sieve is used in final delivery, there is no 505 identity for the "filer" -- the user who is creating or changing the 506 message. In this case, there is such an identity, and a Sieve script 507 might want to access that identity. 509 Implementations MUST set and make available two new environment 510 items: 512 "imapuser" -- the identity (login ID) of the IMAP user that caused 513 the action. This MUST be the empty string if it is accessed during 514 normal (final delivery) Sieve processing. 516 "imapemail" -- the primary email address of the IMAP user that caused 517 the action (the user identified by "imapuser"). In some 518 implementations, "imapuser" and "imapemail" might have the same 519 value. This MUST be the empty string if it is accessed during normal 520 (final delivery) Sieve processing. 522 4.3. New Sieve Environment Item: cause 524 Each mailbox uses a single script for all the change conditions 525 described in this document (append, copy, flag changes). To support 526 that, the implementation MUST set the Environment [RFC5183] item 527 "cause", which contains the name of the action that caused the script 528 to be invoked. Its value is one of the following: 530 o APPEND (for invocations resulting from APPEND or MULTIAPPEND) 532 o COPY (for invocations resulting from COPY) 534 o FLAG (for invocations resulting from flag changes) 535 Future extensions might define new events and, thus, new causes. 536 Such extensions will come with their own capability strings, and the 537 events they define will only be presented when their capabilities are 538 requested. Scripts that do not request those capabilities will not 539 see those events, and will not encounter the new cause strings. 541 4.4. New Sieve Environment Item: mailbox 543 The implementation MUST set the Environment [RFC5183] item "mailbox" 544 to the name of the mailbox that the affected message is in, in the 545 case of existing messages, or is targeted to be stored into, in the 546 case of new messages. The value of this item is fixed when the 547 script begins, and, in particular, MUST NOT change as a result of any 548 action, such as "fileinto". 550 4.5. New Sieve Environment Item: changedflags 552 If the IMAP4Flags extension [RFC5232] is available, AND the script 553 was invoked because of flag changes to an existing message, the 554 implementation MUST set the Environment [RFC5183] item "changedflags" 555 to the name(s) of the flag(s) that have changed. If the script was 556 not invoked because of flag changes, the value of this item MUST be 557 the empty string. The script will not know from this item whether 558 the flags have been set or reset, but it can use the "hasflag" test 559 to determine the current value. See example 2 in Section 5 for an 560 example of how this might be used. 562 4.6. Interaction With Sieve Tests (Comparisons) 564 Any tests against message envelope information, including the 565 "envelope" test in the Sieve base specification, as well as any such 566 test defined in extensions, are either inapplicable or have serious 567 interoperability issues when performed at other than final-delivery 568 time. Therefore, envelope tests MUST NOT be permitted in the cases 569 described here, and their use MUST generate a runtime error. 571 This extension does not affect the operation of other tests or 572 comparisons in the Sieve base specification. 574 5. Examples 576 Example 1: 577 If a new message is added to the "ActionItems" mailbox, a copy is 578 sent to the address "actionitems@example.com". 580 require ["copy", "environment", "imapsieve"]; 582 if anyof (environment :is "cause" "APPEND", 583 environment :is "cause" "COPY") { 584 if environment :is "mailbox" "ActionItems" { 585 redirect :copy "actionitems@example.com"; 586 } 587 } 589 Example 2: 590 If the script is called for any message with the \Flagged flag set 591 (tested through the IMAP4Flags extension [RFC5232]), a notification 592 is sent using the Notify extension [RFC5435]. No notification will 593 be sent, though, if we're called with an existing message that 594 already had that flag set. 596 require ["enotify", "imap4flags", "variables", 597 "environment", "imapsieve"]; 599 if environment :matches "mailbox" "*" { 600 set "mailbox" "${1}"; 601 } 603 if allof (hasflag "\\Flagged", 604 not environment :contains "changedflags" "\\Flagged") { 605 notify :message "Important message in ${mailbox}" 606 "xmpp:tim@example.com?message;subject=SIEVE"; 607 } 609 Example 3: 610 This shows an example IMAP CAPABILITY response when this extension is 611 supported. The client has done STARTTLS with the server, and is now 612 inspecting capabilities. (The untagged CAPABILITY response is split 613 here for readability only, but will be in one response message.) 615 C: A01 CAPABILITY 616 S: * CAPABILITY IMAP4rev1 AUTH=PLAIN UIDPLUS LIST-EXTENDED 617 ACL IMAPSIEVE=sieve://sieve.example.com MULTISEARCH 618 S: A01 OK done 620 6. Security Considerations 622 It is possible to introduce script processing loops by having a Sieve 623 script that is triggered by flag changes use the actions defined in 624 the IMAP4Flags extension [RFC5232]. Implementations MUST take steps 625 to prevent such loops. One way to avoid this problem is that if a 626 script is invoked by flag changes, and that script further changes 627 the flags, those flag changes SHOULD NOT trigger a Sieve script 628 invocation. 630 It is also possible to introduce loops through the "redirect" or 631 "notify" actions. See section 10 of Sieve [RFC5228], section 8 of 632 Sieve Notify [RFC5435], and the Security Considerations sections of 633 the applicable notification-method documents for loop-prevention 634 information. This extension does not change any of that advice. 636 Other security considerations are discussed in IMAP [RFC3501], and 637 Sieve [RFC5228], as well as in some of the other extension documents. 639 7. IANA Considerations 641 7.1. Registration of "imapsieve" IMAP capability 643 IANA is asked to add "IMAPSIEVE=" to the IMAP 4 Capabilities 644 registry, according to the IMAP 4 specification [RFC3501]. 645 (http://www.iana.org/assignments/imap4-capabilities) 647 7.2. Registration of "imapsieve" Sieve extension 649 The following information should be added to the Sieve Extensions 650 registry, according to the Sieve specification [RFC5228]. (http:// 651 www.iana.org/assignments/sieve-extensions/sieve-extensions.xml) 653 To: iana@iana.org 654 Subject: Registration of new Sieve extension 655 Capability name: imapsieve 656 Description: Add Sieve processing for IMAP events. 657 RFC number: [[this RFC]] 658 Contact address: Sieve mailing list 660 7.3. Registration of Sieve Environment Items 662 The following subsections register items in the Sieve Environment 663 Items registry, according to the Environment extension [RFC5183]. 664 (http://www.iana.org/assignments/sieve-environment-items/ sieve- 665 environment-items.xml) 667 7.3.1. Registration of Sieve Environment Item: cause 669 To: iana@iana.org 670 Subject: Registration of new Sieve environment item 671 Item name: cause 672 Description: The name of the action that caused the script to be 673 invoked. Its value is one of the following: 675 o APPEND (for invocations resulting from APPEND or MULTIAPPEND) 677 o COPY (for invocations resulting from COPY) 679 o FLAG (for invocations resulting from flag changes) 681 RFC number: [[this RFC]] 682 Contact address: Sieve mailing list 684 7.3.2. Registration of Sieve Environment Item: mailbox 686 To: iana@iana.org 687 Subject: Registration of new Sieve environment item 688 Item name: mailbox 689 Description: The name of the mailbox that the affected message is in, 690 in the case of existing messages, or is targeted to be stored into, 691 in the case of new messages. The value of this item is fixed when 692 the script begins, and, in particular, MUST NOT change as a result of 693 any action, such as "fileinto". 694 RFC number: [[this RFC]] 695 Contact address: Sieve mailing list 697 7.3.3. Registration of Sieve Environment Item: changedflags 699 To: iana@iana.org 700 Subject: Registration of new Sieve environment item 701 Item name: changedflags 702 Description: If the script was invoked because of flag changes to an 703 existing message, this contains the name(s) of the flag(s) that have 704 changed. Otherwise, the value of this item MUST be the empty string. 705 RFC number: [[this RFC]] 706 Contact address: Sieve mailing list 708 7.3.4. Registration of Sieve Environment Item: imapuser 710 To: iana@iana.org 711 Subject: Registration of new Sieve environment item 712 Item name: imapuser 713 Description: The identity (IMAP login ID) of the IMAP user that 714 caused the action. 715 RFC number: [[this RFC]] 716 Contact address: Sieve mailing list 718 7.3.5. Registration of Sieve Environment Item: imapemail 720 To: iana@iana.org 721 Subject: Registration of new Sieve environment item 722 Item name: imapemail 723 Description: The primary email address of the IMAP user that caused 724 the action (the user identified by "imapuser"). 725 RFC number: [[this RFC]] 726 Contact address: Sieve mailing list 728 7.4. Registration of IMAP METADATA Mailbox Entry Name 730 The following information should be added to the IMAP METADATA 731 Mailbox Entry Registry, according to the Metadata extension 733 [RFC5464]. 734 (http://www.iana.org/assignments/imap-metadata/imap-metadata.xml) 736 To: iana@iana.org 737 Subject: IMAP METADATA Registration 738 Please register the following IMAP METADATA item: 739 [x] Entry [ ] Attribute 740 [x] Mailbox [ ] Server 741 Name: /IMAPSieve/Script 742 Description: This entry name is used to define mailbox metadata 743 associated with IMAP events in Sieve for the associated mailbox. 744 Specifically, this specifies the Sieve script that will be invoked 745 when IMAP events occur on the specified mailbox. 746 Content-type: text/plain; charset=utf-8 747 RFC number: [[this RFC]] 748 Contact address: Sieve mailing list 750 7.5. Registration of IMAP METADATA Server Entry Name 752 The following information should be added to the IMAP METADATA Server 753 Entry Registry, items according to the Metadata extension [RFC5464]. 754 (http://www.iana.org/assignments/imap-metadata/imap-metadata.xml) 756 To: iana@iana.org 757 Subject: IMAP METADATA Registration 758 Please register the following IMAP METADATA item: 759 [x] Entry [ ] Attribute 760 [ ] Mailbox [x] Server 761 Name: /IMAPSieve/Script 762 Description: This entry name is used to define metadata associated 763 globally with IMAP events in Sieve for the associated server. 764 Specifically, this specifies the Sieve script that will be invoked 765 when IMAP events occur on any mailbox in the server that does not 766 have its own mailbox-level /IMAPSieve/Script entry. 767 Content-type: text/plain; charset=utf-8 768 RFC number: [[this RFC]] 769 Contact address: Sieve mailing list 771 8. References 773 8.1. Normative References 775 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 776 Requirement Levels", BCP 14, RFC 2119, March 1997. 778 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 779 4rev1", RFC 3501, March 2003. 781 [RFC3502] Crispin, M., "Internet Message Access Protocol (IMAP) - 782 MULTIAPPEND Extension", RFC 3502, March 2003. 784 [RFC3894] Degener, J., "Sieve Extension: Copying Without Side 785 Effects", RFC 3894, October 2004. 787 [RFC5183] Freed, N., "Sieve Email Filtering: Environment Extension", 788 RFC 5183, May 2008. 790 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 791 Language", RFC 5228, January 2008. 793 [RFC5232] Melnikov, A., "Sieve Email Filtering: Imap4flags 794 Extension", RFC 5232, January 2008. 796 [RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464, 797 February 2009. 799 [RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely 800 Managing Sieve Scripts", RFC 5804, July 2010. 802 [RFC6409] Gellens, R. and J. Klensin, "Message Submission for Mail", 803 STD 72, RFC 6409, November 2011. 805 8.2. Informative References 807 [RFC4315] Crispin, M., "Internet Message Access Protocol (IMAP) - 808 UIDPLUS extension", RFC 4315, December 2005. 810 [RFC5230] Showalter, T. and N. Freed, "Sieve Email Filtering: 811 Vacation Extension", RFC 5230, January 2008. 813 [RFC5235] Daboo, C., "Sieve Email Filtering: Spamtest and Virustest 814 Extensions", RFC 5235, January 2008. 816 [RFC5293] Degener, J. and P. Guenther, "Sieve Email Filtering: 817 Editheader Extension", RFC 5293, August 2008. 819 [RFC5429] Stone, A., "Sieve Email Filtering: Reject and Extended 820 Reject Extensions", RFC 5429, March 2009. 822 [RFC5435] Melnikov, A., Leiba, B., Segmuller, W., and T. Martin, 823 "Sieve Email Filtering: Extension for Notifications", 824 RFC 5435, January 2009. 826 [RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part 827 Tests, Iteration, Extraction, Replacement, and Enclosure", 828 RFC 5703, October 2009. 830 Author's Address 832 Barry Leiba 833 Huawei Technologies 835 Phone: +1 646 827 0648 836 Email: barryleiba@computer.org 837 URI: http://internetmessagingtechnology.org/