RFC 5232

Sieve Email Filtering: Imap4flags Extension

📅 published January 2008, from ietf

RFC 5232: Sieve Email Filtering: Imap4flags Extension 💌

Okay bestie, this is RFC 5232 🎀 It's a Standards Track doc from the Network Working Group, dated January 2008, written by A. Melnikov of Isode Limited 🦋 Nothing in its header says it obsoletes or updates any other RFC, so it stands on its own 💅

Status of This Memo 📜

This doc specifies an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions for improvements 🌸 For the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1) 🔍 Distribution of this memo is unlimited 🫶

Abstract 🌟

Recent discussions have shown that it's super desirable to set different IMAP (RFC 3501) flags when a message gets delivered 📬 One way to do that is with a Sieve interpreter that runs as part of a Mail Delivery Agent 💖

This doc describes an extension to the Sieve mail filtering language for setting IMAP flags 🧚 It lets you set both IMAP system flags and IMAP keywords 🍓

Table of Contents 📚

   1. Introduction ....................................................2
      1.1. Conventions Used ...........................................2
   2. General Requirements for Flag Handling ..........................3
   3. Actions .........................................................3
      3.1. Action setflag .............................................4
      3.2. Action addflag .............................................4
      3.3. Action removeflag ..........................................5
   4. Test hasflag ....................................................6
   5. Tagged Argument :flags ..........................................7
   6. Interaction with Other Sieve Actions ............................8
   7. Security Considerations .........................................8
   8. IANA Considerations .............................................8
   9. Extended Example ................................................8
   10. Acknowledgments ...............................................10
   11. Normative References ..........................................10

1. Introduction ✨

This is an extension to the Sieve language defined by [SIEVE] for setting [IMAP] flags 💅 It adds a new tagged argument to "keep" and "fileinto" that describes the list of flags that have to be set when the message is delivered to the specified mailbox. It also adds several actions to help manipulate lists of flags, plus a test to check whether a flag belongs to a list.

From the user's perspective, this extension gives you a few things:

  • First, it lets you manipulate sets of IMAP flags 🌈
  • Second, it lets you attach a set of IMAP flags to a message that gets delivered to a mailstore using the keep/fileinto actions 📥
  • Third, it maintains an internal variable 🧠 That variable holds the default flags that get attached to a message delivered using the keep, implicit keep, or fileinto actions, whenever the :flags tagged argument isn't specified. When the Sieve [VARIABLES] extension is also supported by the Sieve engine, you get support for multiple variables containing sets of IMAP flags 👑

The capability string for this extension is "imap4flags" 🎀 All conformant implementations MUST implement all Sieve actions (setflag, addflag, removeflag), the "hasflag" test, and the ":flags" tagged argument described in this document. No exceptions, periodt 💀

The "imap4flags" extension can be used with or without the "variables" extension [VARIABLES]. When the "variables" extension is enabled in a script using <require "variables">, the script can use explicit variable names in setflag/addflag/removeflag actions and the hasflag test. See also Section 3 for more details 🦋 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 [SIEVE]. Hard no, bestie 🙅‍♀️

1.1. Conventions Used

Conventions for notations are as in [SIEVE], Section 1.1, including use of the "Usage:" label for the definition of action and tagged arguments syntax 📝

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 🫶

2. General Requirements for Flag Handling 🎀

These notes apply to processing of the addflag/removeflag/setflag actions, the "hasflag" test, and the ":flags" tagged argument 💖

A Sieve interpreter MUST ignore empty strings (i.e., "") in a list-of-flags parameter 🙈

A string containing a space-separated list of flag names is equivalent to a string list made up of those flags. This requirement exists to simplify amalgamation of multiple flag lists 🧩

The Sieve interpreter SHOULD check the list of flags for validity as described by [IMAP] ABNF. In particular, according to [IMAP], non-ASCII characters are not allowed in flag names. However, spaces MUST always be allowed as delimiters in strings representing a list of flags. In such strings, multiple spaces between flag names MUST be treated as a single space character, and leading and trailing spaces MUST be ignored ✨

If a flag validity check fails, the flag MUST be ignored 🚫

Note that it is not possible to use this extension to set or clear the \Recent flag, or any other special system flag that is not settable in [IMAP]. Any such flags MUST be ignored if included in a flag list 🙅‍♀️

3. Actions 🔥

All actions described in this specification (setflag, addflag, removeflag) operate on string variables that contain a set of [IMAP] flags. On variable substitution, a set of flags is represented as a string containing a space-separated list of flag names 🧁

Any setflag/addflag/removeflag action MAY alter the flag list in any way that leaves its semantics as a set of case-insensitive words unaltered. For example, it may reorder the flags, alter the case of the letters in them, or add or remove duplicates or extraneous spaces. Scripts MUST NOT make assumptions about the ordering of flags in lists or the preservation of their case 🌀 Don't build your script around the order or the casing, because it's not guaranteed 💅

Note that the parameter specifying a variable name to setflag/addflag/removeflag actions and the hasflag test is optional. If the parameter isn't specified, the actions operate on the internal variable, which has the empty value when the script starts execution. If the SIEVE interpreter doesn't support the "variables" extension [VARIABLES], the presence of the variable name parameter will cause a runtime error [SIEVE] 😭

The "addflag" action adds flags to an existing set. The "removeflag" action removes flags from an existing set. The "setflag" action replaces an existing set of flags with a new set. The "set" action defined in [VARIABLES] can also be used to replace an existing set of flags with a new set. However, it should be noted that the "set" action can't perform any flag reordering, duplicate elimination, etc. 👀

The :flags tagged argument to "keep" and "fileinto" actions is used to associate a set of flags with the current message 🎯 If the :flags tagged argument isn't specified with those two actions, the current value of the internal variable is used instead. The value of the internal variable also applies to the implicit keep 🫧

Note that when keep/fileinto is used multiple times in a script and duplicate message elimination is performed (as described in Section 2.10.3 of [SIEVE]), the last flag list value MUST win 👑

3.1. Action setflag

Usage:   setflag [<variablename: string>]
         <list-of-flags: string-list>

Setflag is used for setting [IMAP] system flags or keywords. Setflag replaces any previously set flags 🔄

Example:

if size :over 500K {
    setflag "\\Deleted";
}

A more substantial example is the following:

Example:

if header :contains "from" "boss@frobnitzm.example.edu" {
    setflag "flagvar" "\\Flagged";
    fileinto :flags "${flagvar}" "INBOX.From Boss";
}

3.2. Action addflag

Usage:   addflag [<variablename: string>]
         <list-of-flags: string-list>

Addflag is used to add flags to a list of [IMAP] flags. It doesn't replace any previously set flags. This means that multiple occurrences of addflag are treated additively ➕

The following examples demonstrate the requirements described in Section 2.1. The following two actions:

addflag "flagvar" "\\Deleted";
addflag "flagvar" "\\Answered";

produce the same result as the single action:

addflag "flagvar" ["\\Deleted", "\\Answered"];

or:

addflag "flagvar" "\\Deleted \\Answered";

or:

addflag "flagvar" "\\Answered \\Deleted";

3.3. Action removeflag

Usage:   removeflag [<variablename: string>]
         <list-of-flags: string-list>

Removeflag is used to remove flags from a list of [IMAP] flags. Removeflag clears flags previously set by "set"/"addflag". Calling removeflag with a flag that wasn't set before isn't an error, and it gets ignored 🫠 Note that if an implementation doesn't perform automatic duplicate elimination, it MUST remove all occurrences of the flags specified in the second parameter to removeflag. Empty strings in the list-of-flags MUST be ignored. Also note that flag names are case-insensitive, as described in [IMAP]. Multiple removeflag actions are treated additively 🧹

Example:

if header :contains "Disposition-Notification-To"
   "mel@example.com" {
    addflag "flagvar" "$MDNRequired";
}
if header :contains "from" "imap@cac.washington.example.edu" {
    removeflag "flagvar" "$MDNRequired";
    fileinto :flags "${flagvar}" "INBOX.imap-list";
}

4. Test hasflag ✨

okay bestie, this test is the one that checks whether your flags are hanging out together 🫶 It's giving pattern matching with a glow-up. The hasflag test is true if any of the variables matches any flag name. The match type defaults to :is, and if you leave out the list of variables, it uses the internal variable instead 💅

Usage: hasflag [MATCH-TYPE] [COMPARATOR]
       [<variable-list: string-list>]
       <list-of-flags: string-list>

The default comparator is "i;ascii-casemap". It's the same case-insensitive comparison that [IMAP] uses for its flags, so "A" and "a" are the same to it 🦋

The "relational" extension [RELATIONAL] adds a match type called :count 🔢 The :count of a variable is the number of distinct flags in it. The count of a list of variables is the sum of the counts of each member variable. literally so organized 😭

Example:

If the internal variable has the value "A B", the following test

 hasflag :is "b A"

evaluates to true. The above test can also be written as

 hasflag ["b","A"]

Example:

If the variable "MyVar" has value "NonJunk Junk gnus-forward
$Forwarded NotJunk JunkRecorded $Junk $NotJunk", the following
tests evaluate to true:

 hasflag :contains "MyVar" "Junk"
 hasflag :contains "MyVar" "forward"
 hasflag :contains "MyVar" ["label", "forward"]
 hasflag :contains "MyVar" ["junk", "forward"]

Note that the last of these tests can be rewritten
as

 hasflag :contains "MyVar" "junk forward"

or

 hasflag :contains "MyVar" "forward junk"

However, the last two forms are not recommended.

And the following tests will evaluate to false:

 hasflag :contains "MyVar" "label"

 hasflag :contains "MyVar" ["label1", "label2"]

Example:

If the variable "MyFlags" has the value "A B", the following test

  hasflag :count "ge" :comparator "i;ascii-numeric"
          "MyFlags" "2"

evaluates to true, as the variable contains 2 distinct flags.

5. Tagged Argument :flags 🎀

This spec adds a brand new optional tagged argument called :flags, and it changes how the actions keep and fileinto behave 🌸

The :flags tagged argument says the flags in the next argument should be set when fileinto/keep delivers the message to the target mailbox or the user's main mailbox. If you don't include :flags, then keep or fileinto uses the current value of the internal variable when it delivers the message to the target mailbox 📬

Usage:

":flags" <list-of-flags: string-list>

The copy of the message that gets filed into the mailbox will have only the flags listed after the :flags tagged argument 💖

The Sieve interpreter MUST ignore all flags that it can't store permanently. That means the interpreter MUST NOT treat failing to store any flag as a runtime failure that stops the Sieve script. no crashing over flags, bestie 😭

For example, if the mailbox "INBOX.From Boss" can't store any flags, then

fileinto :flags "\\Deleted" "INBOX.From Boss";

and

fileinto "INBOX.From Boss";

are equivalent 🧚

This document doesn't say how the Sieve interpreter sets the [IMAP] flags. The interpreter might work as an IMAP client, or it might have direct access to the mailstore. Either way is fine by this spec 🌈

6. Interaction with Other Sieve Actions 💅

This extension only works on the message that Sieve is processing right now. It doesn't touch another message that gets generated as a side effect of some action, or any other message already in the mailstore 🦋

The extension in this document also doesn't change the implicit keep (see Section 2.10.2 of [SIEVE]). so the implicit keep stays exactly as it is 🫶

7. Security Considerations 🔐

Security considerations are discussed in [IMAP], [SIEVE], and [VARIABLES]. go read those, they matter 😭

This extension intentionally doesn't allow setting [IMAP] flags on an arbitrary message in the [IMAP] message store. no sneaky flag-changing on random messages, it's not that kind of extension 🙅‍♀️

It is believed that this extension doesn't introduce any additional security concerns. the authors don't think it adds new security risks, but the bigger picture is in those other documents, so don't skip them 💀

8. IANA Considerations 📋

This is the template for the IANA registration of the variables Sieve extension in this document:

To: iana@iana.org
Subject: Registration of new Sieve extension

Capability name: imap4flags
Description:     Adds actions and tests for manipulating IMAP flags
RFC number:      RFC 5232
Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>

This information has been added to the list of Sieve extensions given on http://www.iana.org/assignments/sieve-extensions. so it's officially on the list now, iconic ✨

9. Extended Example 🍓

Here's a full Sieve script that puts everything together. It's giving a whole cast of filters working as one team 👑

#
# Example Sieve Filter
# Declare any optional features or extension used by the script
#
require ["fileinto", "imap4flags", "variables"];

#
# Move large messages to a special mailbox
#
if size :over 1M
        {
        addflag "MyFlags" "Big";
        if header :is "From" "boss@company.example.com"
                   {
# The message will be marked as "\Flagged Big" when filed into
# mailbox "Big messages"
                   addflag "MyFlags" "\\Flagged";
                   }
        fileinto :flags "${MyFlags}" "Big messages";
        }

if header :is "From" "grandma@example.net"
        {
        addflag "MyFlags" ["\\Answered", "$MDNSent"];
# If the message is bigger than 1Mb it will be marked as
# "Big \Answered $MDNSent" when filed into mailbox "grandma".
# If the message is shorter than 1Mb it will be marked as
# "\Answered $MDNSent"
        fileinto :flags "${MyFlags}" "GrandMa";
        }

#
# Handle messages from known mailing lists
# Move messages from IETF filter discussion list to filter folder
#
if header :is "Sender" "owner-ietf-mta-filters@example.org"
        {
        set "MyFlags" "\\Flagged $Work";
# Message will have both "\Flagged" and $Work flags
        keep :flags "${MyFlags}";
        }

#
# Keep all messages to or from people in my company
#
elsif anyof address :domain :is ["From", "To"] "company.example.com"
        {
        keep :flags "${MyFlags}"; # keep in "Inbox" folder
        }

# Try to catch unsolicited email.  If a message is not to me,
# or it contains a subject known to be spam, file it away.
#
elsif anyof (not address :all :contains
               ["To", "Cc"] "me@company.example.com",
             header :matches "subject"
               ["*make*money*fast*", "*university*dipl*mas*"])

        {
        remove "MyFlags" "\\Flagged";
        fileinto :flags "${MyFlags}" "spam";
        }
else
        {
        # Move all other external mail to "personal"
        # folder.
        fileinto :flags "${MyFlags}" "personal";
        }

10. Acknowledgments 🫶

This document was revised partly because of comments and discussions that happened on and off the Sieve mailing list 💬

Big thanks to everyone who took the time to review the document and make suggestions. The author especially appreciates Tim Showalter, Barry Leiba, Randall Gellens, Ken Murchison, Cyrus Daboo, Matthew Elvey, Jutta Degener, Ned Freed, Marc Mutz, Nigel Swinson, Kjetil Torgrim Homme, Mark E. Mallett, Dave Cridland, Arnt Gulbrandsen, Philip Guenther, Rob Austein, Sam Hartman, Eric Gray, and Cullen Jennings. the whole squad 👑

Special thanks to Tony Hansen and David Lamb for helping the author better explain the concept 🥹

11. Normative References 📚

[SIEVE]      Guenther, P., Ed., and T. Showalter, Ed., "Sieve: An
             Email Filtering Language", RFC 5228, January 2008.

[IMAP]       Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
             4rev1", RFC 3501, March 2003.

[VARIABLES]  Homme, K., "Sieve Email Filtering: Variables Extension",
             RFC 5229, January 2008.

[RELATIONAL] Segmuller, W. and B. Leiba "Sieve Email Filtering:
             Relational Extension", RFC 5231, January 2008.

Author's Address 📮

Alexey Melnikov
Isode Limited

5 Castle Business Village
Hampton, Middlesex
United Kingdom, TW12 2BX

EMail: alexey.melnikov@isode.com

Full Copyright Statement ⚖️

Copyright (C) The IETF Trust (2008).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property 🧾

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.

📦 where this page comes from