Sieve Email Filtering: Imap4flags Extension
Extracted elements (25)
A string containing a space-separated list of flag names is defined as equivalent to a string list of those flags. This design choice is explicitly intended to simplify amalgamation of multiple flag lists in scripts.
The :flags tagged argument passes only the listed flags to the filed copy; the document explicitly does not dictate whether the Sieve interpreter implements flag setting as an IMAP client or via direct mailstore access, preserving implementation flexibility.
The hasflag test defaults to ':is' match type with 'i;ascii-casemap' comparator, matching the case-insensitive comparison semantics defined for IMAP flags by RFC 3501, ensuring behavioral consistency with the underlying IMAP protocol.
The extension operates only on the message currently being processed by the Sieve interpreter; it does not affect messages generated as side effects of any action or any other message already in the mailstore.
The imap4flags extension can be used with or without the 'variables' extension (RFC 5229). When 'variables' is not required, the explicit variable name parameter is prohibited; when it is required, explicit variable names may be used in all flag manipulation actions and tests.
The imap4flags extension does not change the implicit keep behavior defined in the base Sieve specification (RFC 5228, Section 2.10.2); the implicit keep uses the current value of the internal variable for flags.
The 'relational' extension (RFC 5231) adds a ':count' match type usable with hasflag; the :count of a variable returns the number of distinct flags it contains, and the count of a list of variables is the sum of individual counts.
A Sieve interpreter MUST ignore empty strings (i.e., "") in a list-of-flags parameter.
All conformant implementations MUST implement all three Sieve actions (setflag, addflag, removeflag), the hasflag test, and the :flags tagged argument described in this document.
If a flag validity check fails, the flag MUST be ignored. Any flags that cannot be set in IMAP (such as \Recent) MUST be ignored if included in a flag list.
If an implementation does not perform automatic duplicate elimination, it MUST remove all occurrences of the flags specified in the second parameter to removeflag.
Scripts MUST NOT make assumptions about the ordering of flags in lists or the preservation of their case; implementations MAY reorder, change case, or remove duplicates.
Spaces MUST always be allowed as delimiters in flag list strings; multiple spaces between flag names MUST be treated as a single space, and leading and trailing spaces MUST be ignored.
The Sieve interpreter MUST ignore all flags that it cannot store permanently, and MUST NOT treat failure to store any flag as a runtime failure to execute the Sieve script.
The Sieve interpreter SHOULD check the list of flags for validity as described by the IMAP ABNF; non-ASCII characters are not allowed in flag names.
When keep/fileinto is used multiple times in a script and duplicate message elimination is performed, the last flag list value MUST win.
When the 'variables' extension is not enabled, the explicit variable name parameter to setflag/addflag/removeflag/hasflag MUST NOT be used and MUST cause an error according to the base Sieve specification.
The addflag action adds flags to an existing flag set without replacing previously set flags; multiple occurrences are treated additively. Usage: addflag [<variablename: string>] <list-of-flags: string-list>.
The :flags tagged argument to keep and fileinto specifies the flag set to apply when delivering the message to the target mailbox; if omitted, the current value of the internal variable is used. Usage: ':flags' <list-of-flags: string-list>.
The hasflag test evaluates to true if any of the named variables (or the internal variable if omitted) contains any of the specified flag names. The default match type is ':is' and the default comparator is 'i;ascii-casemap'. Usage: hasflag [MATCH-TYPE] [COMPARATOR] [<variable-list: string-list>] <list-of-flags: string-list>.
The internal variable is an implicit string variable maintained by the Sieve engine that holds the default set of flags; it starts with an empty value and is used by keep, implicit keep, and fileinto when the :flags tagged argument is not specified.
The removeflag action removes specified flags from an existing flag set; calling it with a flag not previously set is not an error and is ignored. Usage: removeflag [<variablename: string>] <list-of-flags: string-list>.
The setflag action replaces any previously set flags on a variable (or the internal variable if no variable name is specified) with a new list of IMAP system flags or keywords. Usage: setflag [<variablename: string>] <list-of-flags: string-list>.
This document registers the 'imap4flags' capability name in the IANA Sieve extensions registry, with description 'Adds actions and tests for manipulating IMAP flags', contact [email protected].
The extension intentionally does not allow setting IMAP flags on an arbitrary message in the IMAP message store; it is scoped exclusively to the message currently being delivered. The document states it introduces no additional security concerns beyond those in RFC 3501, RFC 5228, and RFC 5229.