7Network Working Group A. Melnikov
8Request for Comments: 5232 Isode Limited
9Category: Standards Track January 2008
12 Sieve Email Filtering: Imap4flags Extension
16 This document specifies an Internet standards track protocol for the
17 Internet community, and requests discussion and suggestions for
18 improvements. Please refer to the current edition of the "Internet
19 Official Protocol Standards" (STD 1) for the standardization state
20 and status of this protocol. Distribution of this memo is unlimited.
24 Recent discussions have shown that it is desirable to set different
25 IMAP (RFC 3501) flags on message delivery. This can be done, for
26 example, by a Sieve interpreter that works as a part of a Mail
29 This document describes an extension to the Sieve mail filtering
30 language for setting IMAP flags. The extension allows setting of
31 both IMAP system flags and IMAP keywords.
35 1. Introduction ....................................................2
36 1.1. Conventions Used ...........................................2
37 2. General Requirements for Flag Handling ..........................3
38 3. Actions .........................................................3
39 3.1. Action setflag .............................................4
40 3.2. Action addflag .............................................4
41 3.3. Action removeflag ..........................................5
42 4. Test hasflag ....................................................6
43 5. Tagged Argument :flags ..........................................7
44 6. Interaction with Other Sieve Actions ............................8
45 7. Security Considerations .........................................8
46 8. IANA Considerations .............................................8
47 9. Extended Example ................................................8
48 10. Acknowledgments ...............................................10
49 11. Normative References ..........................................10
58Melnikov Standards Track [Page 1]
60RFC 5232 Sieve: Imap4flags Extension January 2008
65 This is an extension to the Sieve language defined by [SIEVE] for
66 setting [IMAP] flags. It adds a new tagged argument to "keep" and
67 "fileinto" that describes the list of flags that have to be set when
68 the message is delivered to the specified mailbox. It also adds
69 several actions to help manipulate list of flags and a test to check
70 whether a flag belongs to a list.
72 From the user's perspective, this extension provides several
73 capabilities. First, it allows manipulation of sets of IMAP flags.
74 Second, it gives the ability to associate a set of IMAP flags with a
75 message that is delivered to a mailstore using the keep/fileinto
76 actions. Third, it maintains an internal variable. The internal
77 variable contains the default flags that will be associated with a
78 message that is delivered using the keep, implicit keep, or fileinto
79 actions, when the :flags tagged argument is not specified. When the
80 Sieve [VARIABLES] extension is also supported by the Sieve engine, it
81 enables support for multiple variables containing sets of IMAP flags.
83 The capability string associated with the extension defined in this
84 document is "imap4flags". All conformant implementations MUST
85 implement all Sieve actions (setflag, addflag, removeflag), the
86 "hasflag" test, and the ":flags" tagged argument described in this
89 The "imap4flags" extension can be used with or without the
90 "variables" extension [VARIABLES]. When the "variables" extension is
91 enabled in a script using <require "variables">, the script can use
92 explicit variable names in setflag/addflag/removeflag actions and the
93 hasflag test. See also Section 3 for more details. When the
94 "variables" extension is not enabled, the explicit variable name
95 parameter to setflag/addflag/removeflag/hasflag MUST NOT be used and
96 MUST cause an error according to [SIEVE].
100 Conventions for notations are as in [SIEVE], Section 1.1, including
101 use of "Usage:" label for the definition of action and tagged
104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
106 document are to be interpreted as described in RFC 2119.
114Melnikov Standards Track [Page 2]
116RFC 5232 Sieve: Imap4flags Extension January 2008
1192. General Requirements for Flag Handling
121 The following notes apply to processing of addflag/removeflag/setflag
122 actions, the "hasflag" test and the ":flags" tagged argument.
124 A Sieve interpreter MUST ignore empty strings (i.e., "") in a list-
127 A string containing a space-separated list of flag names is
128 equivalent to a string list consisting of the flags. This
129 requirement is to simplify amalgamation of multiple flag lists.
131 The Sieve interpreter SHOULD check the list of flags for validity as
132 described by [IMAP] ABNF. In particular, according to [IMAP], non-
133 ASCII characters are not allowed in flag names. However, spaces MUST
134 always be allowed as delimiters in strings representing a list of
135 flags. In such strings, multiple spaces between flag names MUST be
136 treated as a single space character, and leading and trailing spaces
139 If a flag validity check fails, the flag MUST be ignored.
141 Note that it is not possible to use this extension to set or clear
142 the \Recent flag or any other special system flag that is not
143 settable in [IMAP]. Any such flags MUST be ignored if included in a
148 All actions described in this specification (setflag, addflag,
149 removeflag) operate on string variables that contain a set of [IMAP]
150 flags. On variable substitution, a set of flags is represented as a
151 string containing a space-separated list of flag names.
153 Any setflag/addflag/removeflag action MAY alter the flag list in any
154 way that leaves its semantics as a set of case-insensitive words
155 unaltered. For example, it may reorder the flags, alter the case of
156 the letters in them, or add or remove duplicates or extraneous
157 spaces. Scripts MUST NOT make assumptions about the ordering of
158 flags in lists or the preservation of their case.
160 Note that the parameter specifying a variable name to
161 setflag/addflag/removeflag actions and the hasflag test is optional.
162 If the parameter is not specified, the actions operate on the
163 internal variable, which has the empty value when the script starts
164 execution. If the SIEVE interpreter doesn't support the "variables"
165 extension [VARIABLES], the presence of the variable name parameter
166 will cause a runtime error [SIEVE].
170Melnikov Standards Track [Page 3]
172RFC 5232 Sieve: Imap4flags Extension January 2008
175 The "addflag" action adds flags to an existing set. The "removeflag"
176 action removes flags from an existing set. The "setflag" action
177 replaces an existing set of flags with a new set. The "set" action
178 defined in [VARIABLES] can be used to replace an existing set of
179 flags with a new set as well. However, it should be noted that the
180 "set" action can't perform any flag reordering, duplicate
183 The :flags tagged argument to "keep" and "fileinto" actions is used
184 to associate a set of flags with the current message. If the :flags
185 tagged argument is not specified with those two actions, the current
186 value of the internal variable is used instead. The value of the
187 internal variable also applies to the implicit keep.
189 Note that when keep/fileinto is used multiple times in a script and
190 duplicate message elimination is performed (as described in Section
191 2.10.3 of [SIEVE]), the last flag list value MUST win.
195 Usage: setflag [<variablename: string>]
196 <list-of-flags: string-list>
198 Setflag is used for setting [IMAP] system flags or keywords.
199 Setflag replaces any previously set flags.
202 Example: if size :over 500K {
206 A more substantial example is the following:
209 if header :contains "from" "boss@frobnitzm.example.edu" {
210 setflag "flagvar" "\\Flagged";
211 fileinto :flags "${flagvar}" "INBOX.From Boss";
216 Usage: addflag [<variablename: string>]
217 <list-of-flags: string-list>
219 Addflag is used to add flags to a list of [IMAP] flags. It doesn't
220 replace any previously set flags. This means that multiple
221 occurrences of addflag are treated additively.
226Melnikov Standards Track [Page 4]
228RFC 5232 Sieve: Imap4flags Extension January 2008
231 The following examples demonstrate requirements described in Section
232 2.1. The following two actions
234 addflag "flagvar" "\\Deleted";
235 addflag "flagvar" "\\Answered";
237 produce the same result as the single action
239 addflag "flagvar" ["\\Deleted", "\\Answered"];
243 addflag "flagvar" "\\Deleted \\Answered";
247 addflag "flagvar" "\\Answered \\Deleted";
2493.3. Action removeflag
251 Usage: removeflag [<variablename: string>]
252 <list-of-flags: string-list>
254 Removeflag is used to remove flags from a list of [IMAP] flags.
255 Removeflag clears flags previously set by "set"/"addflag". Calling
256 removeflag with a flag that wasn't set before is not an error and is
257 ignored. Note that if an implementation doesn't perform automatic
258 duplicate elimination, it MUST remove all occurrences of the flags
259 specified in the second parameter to removeflag. Empty strings in
260 the list-of-flags MUST be ignored. Also note that flag names are
261 case-insensitive, as described in [IMAP]. Multiple removeflag
262 actions are treated additively.
265 if header :contains "Disposition-Notification-To"
267 addflag "flagvar" "$MDNRequired";
269 if header :contains "from" "imap@cac.washington.example.edu" {
270 removeflag "flagvar" "$MDNRequired";
271 fileinto :flags "${flagvar}" "INBOX.imap-list";
282Melnikov Standards Track [Page 5]
284RFC 5232 Sieve: Imap4flags Extension January 2008
289 Usage: hasflag [MATCH-TYPE] [COMPARATOR]
290 [<variable-list: string-list>]
291 <list-of-flags: string-list>
293 The hasflag test evaluates to true if any of the variables matches
294 any flag name. The type of match defaults to ":is". If the list of
295 variables is omitted, value of the internal variable is used instead.
297 The default comparator is "i;ascii-casemap", which is the same case-
298 insensitive comparison as defined for IMAP flags by [IMAP].
300 The "relational" extension [RELATIONAL] adds a match type called
301 ":count". The :count of a variable returns the number of distinct
302 flags in it. The count of a list of variables is the sum of the
303 counts of the member variables.
306 If the internal variable has the value "A B", the following test
310 evaluates to true. The above test can also be written as
315 If the variable "MyVar" has value "NonJunk Junk gnus-forward
316 $Forwarded NotJunk JunkRecorded $Junk $NotJunk", the following
317 tests evaluate to true:
319 hasflag :contains "MyVar" "Junk"
320 hasflag :contains "MyVar" "forward"
321 hasflag :contains "MyVar" ["label", "forward"]
322 hasflag :contains "MyVar" ["junk", "forward"]
324 Note that the last of these tests can be rewritten
327 hasflag :contains "MyVar" "junk forward"
331 hasflag :contains "MyVar" "forward junk"
333 However, the last two forms are not recommended.
338Melnikov Standards Track [Page 6]
340RFC 5232 Sieve: Imap4flags Extension January 2008
343 And the following tests will evaluate to false:
345 hasflag :contains "MyVar" "label"
347 hasflag :contains "MyVar" ["label1", "label2"]
350 If the variable "MyFlags" has the value "A B", the following test
352 hasflag :count "ge" :comparator "i;ascii-numeric"
355 evaluates to true, as the variable contains 2 distinct flags.
3575. Tagged Argument :flags
359 This specification adds a new optional tagged argument ":flags" that
360 alters the behavior of actions "keep" and "fileinto".
362 The :flags tagged argument specifies that the flags provided in the
363 subsequent argument should be set when fileinto/keep delivers the
364 message to the target mailbox/user's main mailbox. If the :flags
365 tagged argument is not specified, "keep" or "fileinto" will use the
366 current value of the internal variable when delivering the message to
369 Usage: ":flags" <list-of-flags: string-list>
371 The copy of the message filed into the mailbox will have only flags
372 listed after the :flags tagged argument.
374 The Sieve interpreter MUST ignore all flags that it can't store
375 permanently. This means that the interpreter MUST NOT treat failure
376 to store any flag as a runtime failure to execute the Sieve script.
377 For example, if the mailbox "INBOX.From Boss" can't store any flags,
380 fileinto :flags "\\Deleted" "INBOX.From Boss";
384 fileinto "INBOX.From Boss";
388 This document doesn't dictate how the Sieve interpreter will set the
389 [IMAP] flags. In particular, the Sieve interpreter may work as an
390 IMAP client or may have direct access to the mailstore.
394Melnikov Standards Track [Page 7]
396RFC 5232 Sieve: Imap4flags Extension January 2008
3996. Interaction with Other Sieve Actions
401 This extension works only on the message that is currently being
402 processed by Sieve; it doesn't affect another message generated as a
403 side effect of any action or any other message already in the
406 The extension described in this document doesn't change the implicit
407 keep (see Section 2.10.2 of [SIEVE]).
4097. Security Considerations
411 Security considerations are discussed in [IMAP], [SIEVE], and
414 This extension intentionally doesn't allow setting [IMAP] flags on an
415 arbitrary message in the [IMAP] message store.
417 It is believed that this extension doesn't introduce any additional
4208. IANA Considerations
422 The following template specifies the IANA registration of the
423 variables Sieve extension specified in this document:
426 Subject: Registration of new Sieve extension
428 Capability name: imap4flags
429 Description: Adds actions and tests for manipulating IMAP flags
431 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
433 This information has been added to the list of Sieve extensions given
434 on http://www.iana.org/assignments/sieve-extensions.
439 # Example Sieve Filter
440 # Declare any optional features or extension used by the script
442 require ["fileinto", "imap4flags", "variables"];
445 # Move large messages to a special mailbox
450Melnikov Standards Track [Page 8]
452RFC 5232 Sieve: Imap4flags Extension January 2008
457 addflag "MyFlags" "Big";
458 if header :is "From" "boss@company.example.com"
460 # The message will be marked as "\Flagged Big" when filed into
461 # mailbox "Big messages"
462 addflag "MyFlags" "\\Flagged";
464 fileinto :flags "${MyFlags}" "Big messages";
467 if header :is "From" "grandma@example.net"
469 addflag "MyFlags" ["\\Answered", "$MDNSent"];
470 # If the message is bigger than 1Mb it will be marked as
471 # "Big \Answered $MDNSent" when filed into mailbox "grandma".
472 # If the message is shorter than 1Mb it will be marked as
473 # "\Answered $MDNSent"
474 fileinto :flags "${MyFlags}" "GrandMa";
478 # Handle messages from known mailing lists
479 # Move messages from IETF filter discussion list to filter folder
481 if header :is "Sender" "owner-ietf-mta-filters@example.org"
483 set "MyFlags" "\\Flagged $Work";
484 # Message will have both "\Flagged" and $Work flags
485 keep :flags "${MyFlags}";
489 # Keep all messages to or from people in my company
491 elsif anyof address :domain :is ["From", "To"] "company.example.com"
493 keep :flags "${MyFlags}"; # keep in "Inbox" folder
496 # Try to catch unsolicited email. If a message is not to me,
497 # or it contains a subject known to be spam, file it away.
499 elsif anyof (not address :all :contains
500 ["To", "Cc"] "me@company.example.com",
501 header :matches "subject"
502 ["*make*money*fast*", "*university*dipl*mas*"])
506Melnikov Standards Track [Page 9]
508RFC 5232 Sieve: Imap4flags Extension January 2008
512 remove "MyFlags" "\\Flagged";
513 fileinto :flags "${MyFlags}" "spam";
517 # Move all other external mail to "personal"
519 fileinto :flags "${MyFlags}" "personal";
524 This document has been revised in part based on comments and
525 discussions that took place on and off the Sieve mailing list.
527 The help of those who took the time to review the document and make
528 suggestions is appreciated, especially that of Tim Showalter, Barry
529 Leiba, Randall Gellens, Ken Murchison, Cyrus Daboo, Matthew Elvey,
530 Jutta Degener, Ned Freed, Marc Mutz, Nigel Swinson, Kjetil Torgrim
531 Homme, Mark E. Mallett, Dave Cridland, Arnt Gulbrandsen, Philip
532 Guenther, Rob Austein, Sam Hartman, Eric Gray, and Cullen Jennings.
534 Special thanks to Tony Hansen and David Lamb for helping me better
53711. Normative References
539 [SIEVE] Guenther, P., Ed., and T. Showalter, Ed., "Sieve: An
540 Email Filtering Language", RFC 5228, January 2008.
542 [IMAP] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
543 4rev1", RFC 3501, March 2003.
545 [VARIABLES] Homme, K., "Sieve Email Filtering: Variables Extension",
546 RFC 5229, January 2008.
548 [RELATIONAL] Segmuller, W. and B. Leiba "Sieve Email Filtering:
549 Relational Extension", RFC 5231, January 2008.
562Melnikov Standards Track [Page 10]
564RFC 5232 Sieve: Imap4flags Extension January 2008
572 5 Castle Business Village
574 United Kingdom, TW12 2BX
576 EMail: alexey.melnikov@isode.com
618Melnikov Standards Track [Page 11]
620RFC 5232 Sieve: Imap4flags Extension January 2008
623Full Copyright Statement
625 Copyright (C) The IETF Trust (2008).
627 This document is subject to the rights, licenses and restrictions
628 contained in BCP 78, and except as set forth therein, the authors
629 retain all their rights.
631 This document and the information contained herein are provided on an
632 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
633 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
634 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
635 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
636 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
637 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
641 The IETF takes no position regarding the validity or scope of any
642 Intellectual Property Rights or other rights that might be claimed to
643 pertain to the implementation or use of the technology described in
644 this document or the extent to which any license under such rights
645 might or might not be available; nor does it represent that it has
646 made any independent effort to identify any such rights. Information
647 on the procedures with respect to rights in RFC documents can be
648 found in BCP 78 and BCP 79.
650 Copies of IPR disclosures made to the IETF Secretariat and any
651 assurances of licenses to be made available, or the result of an
652 attempt made to obtain a general license or permission for the use of
653 such proprietary rights by implementers or users of this
654 specification can be obtained from the IETF on-line IPR repository at
655 http://www.ietf.org/ipr.
657 The IETF invites any interested party to bring to its attention any
658 copyrights, patents or patent applications, or other proprietary
659 rights that may cover technology that may be required to implement
660 this standard. Please address the information to the IETF at
674Melnikov Standards Track [Page 12]