GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


rfc:rfc5228

Network Working Group P. Guenther, Ed. Request for Comments: 5228 Sendmail, Inc. Obsoletes: 3028 T. Showalter, Ed. Category: Standards Track January 2008

                 Sieve: An Email Filtering Language

Status of This Memo

 This document specifies an Internet standards track protocol for the
 Internet community, and requests discussion and suggestions for
 improvements.  Please refer to the current edition of the "Internet
 Official Protocol Standards" (STD 1) for the standardization state
 and status of this protocol.  Distribution of this memo is unlimited.

Abstract

 This document describes a language for filtering email messages at
 time of final delivery.  It is designed to be implementable on either
 a mail client or mail server.  It is meant to be extensible, simple,
 and independent of access protocol, mail architecture, and operating
 system.  It is suitable for running on a mail server where users may
 not be allowed to execute arbitrary programs, such as on black box
 Internet Message Access Protocol (IMAP) servers, as the base language
 has no variables, loops, or ability to shell out to external
 programs.

Guenther & Showalter Standards Track [Page 1] RFC 5228 Sieve: An Email Filtering Language January 2008

Table of Contents

 1. Introduction ....................................................4
    1.1. Conventions Used in This Document ..........................4
    1.2. Example Mail Messages ......................................5
 2. Design ..........................................................6
    2.1. Form of the Language .......................................6
    2.2. Whitespace .................................................7
    2.3. Comments ...................................................7
    2.4. Literal Data ...............................................7
         2.4.1. Numbers .............................................7
         2.4.2. Strings .............................................8
                2.4.2.1. String Lists ...............................9
                2.4.2.2. Headers ....................................9
                2.4.2.3. Addresses .................................10
                2.4.2.4. Encoding Characters Using
                         "encoded-character" .......................10
    2.5. Tests .....................................................11
         2.5.1. Test Lists .........................................12
    2.6. Arguments .................................................12
         2.6.1. Positional Arguments ...............................12
         2.6.2. Tagged Arguments ...................................12
         2.6.3. Optional Arguments .................................13
         2.6.4. Types of Arguments .................................13
    2.7. String Comparison .........................................13
         2.7.1. Match Type .........................................14
         2.7.2. Comparisons across Character Sets ..................15
         2.7.3. Comparators ........................................15
         2.7.4. Comparisons against Addresses ......................16
    2.8. Blocks ....................................................17
    2.9. Commands ..................................................17
    2.10. Evaluation ...............................................18
         2.10.1. Action Interaction ................................18
         2.10.2. Implicit Keep .....................................18
         2.10.3. Message Uniqueness in a Mailbox ...................19
         2.10.4. Limits on Numbers of Actions ......................19
         2.10.5. Extensions and Optional Features ..................19
         2.10.6. Errors ............................................20
         2.10.7. Limits on Execution ...............................20
 3. Control Commands ...............................................21
    3.1. Control if ................................................21
    3.2. Control require ...........................................22
    3.3. Control stop ..............................................22
 4. Action Commands ................................................23
    4.1. Action fileinto ...........................................23
    4.2. Action redirect ...........................................23
    4.3. Action keep ...............................................24
    4.4. Action discard ............................................25

Guenther & Showalter Standards Track [Page 2] RFC 5228 Sieve: An Email Filtering Language January 2008

 5. Test Commands ..................................................26
    5.1. Test address ..............................................26
    5.2. Test allof ................................................27
    5.3. Test anyof ................................................27
    5.4. Test envelope .............................................27
    5.5. Test exists ...............................................28
    5.6. Test false ................................................28
    5.7. Test header ...............................................29
    5.8. Test not ..................................................29
    5.9. Test size .................................................29
    5.10. Test true ................................................30
 6. Extensibility ..................................................30
    6.1. Capability String .........................................31
    6.2. IANA Considerations .......................................31
         6.2.1. Template for Capability Registrations ..............32
         6.2.2. Handling of Existing Capability Registrations ......32
         6.2.3. Initial Capability Registrations ...................32
    6.3. Capability Transport ......................................33
 7. Transmission ...................................................33
 8. Parsing ........................................................34
    8.1. Lexical Tokens ............................................34
    8.2. Grammar ...................................................36
    8.3. Statement Elements ........................................36
 9. Extended Example ...............................................37
 10. Security Considerations .......................................38
 11. Acknowledgments ...............................................39
 12. Normative References ..........................................39
 13. Informative References ........................................40
 14. Changes from RFC 3028 .........................................41

Guenther & Showalter Standards Track [Page 3] RFC 5228 Sieve: An Email Filtering Language January 2008

1. Introduction

 This memo documents a language that can be used to create filters for
 electronic mail.  It is not tied to any particular operating system
 or mail architecture.  It requires the use of [IMAIL]-compliant
 messages, but should otherwise generalize to many systems.
 The language is powerful enough to be useful but limited in order to
 allow for a safe server-side filtering system.  The intention is to
 make it impossible for users to do anything more complex (and
 dangerous) than write simple mail filters, along with facilitating
 the use of graphical user interfaces (GUIs) for filter creation and
 manipulation.  The base language was not designed to be Turing-
 complete: it does not have a loop control structure or functions.
 Scripts written in Sieve are executed during final delivery, when the
 message is moved to the user-accessible mailbox.  In systems where
 the Mail Transfer Agent (MTA) does final delivery, such as
 traditional Unix mail, it is reasonable to filter when the MTA
 deposits mail into the user's mailbox.
 There are a number of reasons to use a filtering system.  Mail
 traffic for most users has been increasing due to increased usage of
 email, the emergence of unsolicited email as a form of advertising,
 and increased usage of mailing lists.
 Experience at Carnegie Mellon has shown that if a filtering system is
 made available to users, many will make use of it in order to file
 messages from specific users or mailing lists.  However, many others
 did not make use of the Andrew system's FLAMES filtering language
 [FLAMES] due to difficulty in setting it up.
 Because of the expectation that users will make use of filtering if
 it is offered and easy to use, this language has been made simple
 enough to allow many users to make use of it, but rich enough that it
 can be used productively.  However, it is expected that GUI-based
 editors will be the preferred way of editing filters for a large
 number of users.

1.1. Conventions Used in This Document

 In the sections of this document that discuss the requirements of
 various keywords and operators, the following conventions have been
 adopted.
 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 [KEYWORDS].

Guenther & Showalter Standards Track [Page 4] RFC 5228 Sieve: An Email Filtering Language January 2008

 Each section on a command (test, action, or control) has a line
 labeled "Usage:".  This line describes the usage of the command,
 including its name and its arguments.  Required arguments are listed
 inside angle brackets ("<" and ">").  Optional arguments are listed
 inside square brackets ("[" and "]").  Each argument is followed by
 its type, so "<key: string>" represents an argument called "key" that
 is a string.  Literal strings are represented with double-quoted
 strings.  Alternatives are separated with slashes, and parentheses
 are used for grouping, similar to [ABNF].
 In the "Usage:" line, there are three special pieces of syntax that
 are frequently repeated, MATCH-TYPE, COMPARATOR, and ADDRESS-PART.
 These are discussed in sections 2.7.1, 2.7.3, and 2.7.4,
 respectively.
 The formal grammar for these commands is defined in section 8 and is
 the authoritative reference on how to construct commands, but the
 formal grammar does not specify the order, semantics, number or types
 of arguments to commands, or the legal command names.  The intent is
 to allow for extension without changing the grammar.

1.2. Example Mail Messages

 The following mail messages will be used throughout this document in
 examples.
 Message A
 -----------------------------------------------------------
 Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST)
 From: coyote@desert.example.org
 To: roadrunner@acme.example.com
 Subject: I have a present for you
 Look, I'm sorry about the whole anvil thing, and I really
 didn't mean to try and drop it on you from the top of the
 cliff.  I want to try to make it up to you.  I've got some
 great birdseed over here at my place--top of the line
 stuff--and if you come by, I'll have it all wrapped up
 for you.  I'm really sorry for all the problems I've caused
 for you over the years, but I know we can work this out.
 --
 Wile E. Coyote   "Super Genius"   coyote@desert.example.org
 -----------------------------------------------------------

Guenther & Showalter Standards Track [Page 5] RFC 5228 Sieve: An Email Filtering Language January 2008

 Message B
 -----------------------------------------------------------
 From: youcouldberich!@reply-by-postal-mail.invalid
 Sender: b1ff@de.res.example.com
 To: rube@landru.example.com
 Date:  Mon, 31 Mar 1997 18:26:10 -0800
 Subject: $$$ YOU, TOO, CAN BE A MILLIONAIRE! $$$
 YOU MAY HAVE ALREADY WON TEN MILLION DOLLARS, BUT I DOUBT
 IT!  SO JUST POST THIS TO SIX HUNDRED NEWSGROUPS!  IT WILL
 GUARANTEE THAT YOU GET AT LEAST FIVE RESPONSES WITH MONEY!
 MONEY! MONEY! COLD HARD CASH!  YOU WILL RECEIVE OVER
 $20,000 IN LESS THAN TWO MONTHS!  AND IT'S LEGAL!!!!!!!!!
 !!!!!!!!!!!!!!!!!!111111111!!!!!!!11111111111!!1  JUST
 SEND $5 IN SMALL, UNMARKED BILLS TO THE ADDRESSES BELOW!
 -----------------------------------------------------------

2. Design

2.1. Form of the Language

 The language consists of a set of commands.  Each command consists of
 a set of tokens delimited by whitespace.  The command identifier is
 the first token and it is followed by zero or more argument tokens.
 Arguments may be literal data, tags, blocks of commands, or test
 commands.
 With the exceptions of strings and comments, the language is limited
 to US-ASCII characters.  Strings and comments may contain octets
 outside the US-ASCII range.  Specifically, they will normally be in
 UTF-8, as specified in [UTF-8].  NUL (US-ASCII 0) is never permitted
 in scripts, while CR and LF can only appear as the CRLF line ending.
    Note: While this specification permits arbitrary octets to appear
    in Sieve scripts inside strings and comments, this has made it
    difficult to robustly handle Sieve scripts in programs that are
    sensitive to the encodings used.  The "encoded-character"
    capability (section 2.4.2.4) provides an alternative means of
    representing such octets in strings using just US-ASCII
    characters.  As such, the use of non-UTF-8 text in scripts should
    be considered a deprecated feature that may be abandoned.
 Tokens other than strings are considered case-insensitive.

Guenther & Showalter Standards Track [Page 6] RFC 5228 Sieve: An Email Filtering Language January 2008

2.2. Whitespace

 Whitespace is used to separate tokens.  Whitespace is made up of
 tabs, newlines (CRLF, never just CR or LF), and the space character.
 The amount of whitespace used is not significant.

2.3. Comments

 Two types of comments are offered.  Comments are semantically
 equivalent to whitespace and can be used anyplace that whitespace is
 (with one exception in multi-line strings, as described in the
 grammar).
 Hash comments begin with a "#" character that is not contained within
 a string and continue until the next CRLF.
 Example:  if size :over 100k { # this is a comment
              discard;
           }
 Bracketed comments begin with the token "/*" and end with "*/"
 outside of a string.  Bracketed comments may span multiple lines.
 Bracketed comments do not nest.
 Example:  if size :over 100K { /* this is a comment
              this is still a comment */ discard /* this is a comment
              */ ;
           }

2.4. Literal Data

 Literal data means data that is not executed, merely evaluated "as
 is", to be used as arguments to commands.  Literal data is limited to
 numbers, strings, and string lists.

2.4.1. Numbers

 Numbers are given as ordinary decimal numbers.  As a shorthand for
 expressing larger values, such as message sizes, a suffix of "K",
 "M", or "G" MAY be appended to indicate a multiple of a power of two.
 To be comparable with the power-of-two-based versions of SI units
 that computers frequently use, "K" specifies kibi-, or 1,024 (2^10)
 times the value of the number; "M" specifies mebi-, or 1,048,576
 (2^20) times the value of the number; and "G" specifies gibi-, or
 1,073,741,824 (2^30) times the value of the number [BINARY-SI].

Guenther & Showalter Standards Track [Page 7] RFC 5228 Sieve: An Email Filtering Language January 2008

 Implementations MUST support integer values in the inclusive range
 zero to 2,147,483,647 (2^31 - 1), but MAY support larger values.
 Only non-negative integers are permitted by this specification.

2.4.2. Strings

 Scripts involve large numbers of string values as they are used for
 pattern matching, addresses, textual bodies, etc.  Typically, short
 quoted strings suffice for most uses, but a more convenient form is
 provided for longer strings such as bodies of messages.
 A quoted string starts and ends with a single double quote (the <">
 character, US-ASCII 34).  A backslash ("\", US-ASCII 92) inside of a
 quoted string is followed by either another backslash or a double
 quote.  These two-character sequences represent a single backslash or
 double quote within the value, respectively.
 Scripts SHOULD NOT escape other characters with a backslash.
 An undefined escape sequence (such as "\a" in a context where "a" has
 no special meaning) is interpreted as if there were no backslash (in
 this case, "\a" is just "a"), though that may be changed by
 extensions.
 Non-printing characters such as tabs, CRLF, and control characters
 are permitted in quoted strings.  Quoted strings MAY span multiple
 lines.  An unencoded NUL (US-ASCII 0) is not allowed in strings; see
 section 2.4.2.4 for how it can be encoded.
 As message header data is converted to [UTF-8] for comparison (see
 section 2.7.2), most string values will use the UTF-8 encoding.
 However, implementations MUST accept all strings that match the
 grammar in section 8.  The ability to use non-UTF-8 encoded strings
 matches existing practice and has proven to be useful both in tests
 for invalid data and in arguments containing raw MIME parts for
 extension actions that generate outgoing messages.
 For entering larger amounts of text, such as an email message, a
 multi-line form is allowed.  It starts with the keyword "text:",
 followed by a CRLF, and ends with the sequence of a CRLF, a single
 period, and another CRLF.  The CRLF before the final period is
 considered part of the value.  In order to allow the message to
 contain lines with a single dot, lines are dot-stuffed.  That is,
 when composing a message body, an extra '.' is added before each line
 that begins with a '.'.  When the server interprets the script, these
 extra dots are removed.  Note that a line that begins with a dot
 followed by a non-dot character is not interpreted as dot-stuffed;

Guenther & Showalter Standards Track [Page 8] RFC 5228 Sieve: An Email Filtering Language January 2008

 that is, ".foo" is interpreted as ".foo".  However, because this is
 potentially ambiguous, scripts SHOULD be properly dot-stuffed so such
 lines do not appear.
 Note that a hashed comment or whitespace may occur in between the
 "text:" and the CRLF, but not within the string itself.  Bracketed
 comments are not allowed here.

2.4.2.1. String Lists

 When matching patterns, it is frequently convenient to match against
 groups of strings instead of single strings.  For this reason, a list
 of strings is allowed in many tests, implying that if the test is
 true using any one of the strings, then the test is true.
 For instance, the test 'header :contains ["To", "Cc"]
 ["me@example.com", "me00@landru.example.com"]' is true if either a To
 header or Cc header of the input message contains either of the email
 addresses "me@example.com" or "me00@landru.example.com".
 Conversely, in any case where a list of strings is appropriate, a
 single string is allowed without being a member of a list: it is
 equivalent to a list with a single member.  This means that the test
 'exists "To"' is equivalent to the test 'exists ["To"]'.

2.4.2.2. Headers

 Headers are a subset of strings.  In the Internet Message
 Specification [IMAIL], each header line is allowed to have whitespace
 nearly anywhere in the line, including after the field name and
 before the subsequent colon.  Extra spaces between the header name
 and the ":" in a header field are ignored.
 A header name never contains a colon.  The "From" header refers to a
 line beginning "From:" (or "From   :", etc.).  No header will match
 the string "From:" due to the trailing colon.
 Similarly, no header will match a syntactically invalid header name.
 An implementation MUST NOT cause an error for syntactically invalid
 header names in tests.
 Header lines are unfolded as described in [IMAIL] section 2.2.3.
 Interpretation of header data SHOULD be done according to [MIME3]
 section 6.2 (see section 2.7.2 below for details).

Guenther & Showalter Standards Track [Page 9] RFC 5228 Sieve: An Email Filtering Language January 2008

2.4.2.3. Addresses

 A number of commands call for email addresses, which are also a
 subset of strings.  When these addresses are used in outbound
 contexts, addresses must be compliant with [IMAIL], but are further
 constrained within this document.  Using the symbols defined in
 [IMAIL], section 3, the syntax of an address is:
 sieve-address = addr-spec                ; simple address
               / phrase "<" addr-spec ">" ; name & addr-spec
 That is, routes and group syntax are not permitted.  If multiple
 addresses are required, use a string list.  Named groups are not
 permitted.
 It is an error for a script to execute an action with a value for use
 as an outbound address that doesn't match the "sieve-address" syntax.

2.4.2.4. Encoding Characters Using "encoded-character"

 When the "encoded-character" extension is in effect, certain
 character sequences in strings are replaced by their decoded value.
 This happens after escape sequences are interpreted and dot-
 unstuffing has been done.  Implementations SHOULD support "encoded-
 character".
 Arbitrary octets can be embedded in strings by using the syntax
 encoded-arb-octets.  The sequence is replaced by the octets with the
 hexadecimal values given by each hex-pair.
 blank                = WSP / CRLF
 encoded-arb-octets   = "${hex:" hex-pair-seq "}"
 hex-pair-seq         = *blank hex-pair *(1*blank hex-pair) *blank
 hex-pair             = 1*2HEXDIG
 Where WSP and HEXDIG non-terminals are defined in Appendix B.1 of
 [ABNF].
 It may be inconvenient or undesirable to enter Unicode characters
 verbatim, and for these cases the syntax encoded-unicode-char can be
 used.  The sequence is replaced by the UTF-8 encoding of the
 specified Unicode characters, which are identified by the hexadecimal
 value of unicode-hex.
 encoded-unicode-char = "${unicode:" unicode-hex-seq "}"
 unicode-hex-seq      = *blank unicode-hex
                        *(1*blank unicode-hex) *blank
 unicode-hex          = 1*HEXDIG

Guenther & Showalter Standards Track [Page 10] RFC 5228 Sieve: An Email Filtering Language January 2008

 It is an error for a script to use a hexadecimal value that isn't in
 either the range 0 to D7FF or the range E000 to 10FFFF.  (The range
 D800 to DFFF is excluded as those character numbers are only used as
 part of the UTF-16 encoding form and are not applicable to the UTF-8
 encoding that the syntax here represents.)
    Note: Implementations MUST NOT raise an error for an out-of-range
    Unicode value unless the sequence containing it is well-formed
    according to the grammar.
 The capability string for use with the require command is "encoded-
 character".
 In the following script, message B is discarded, since the specified
 test string is equivalent to "$$$".
 Example:  require "encoded-character";
           if header :contains "Subject" "$${hex:24 24}" {
              discard;
           }
 The following examples demonstrate valid and invalid encodings and
 how they are handled:
   "$${hex:40}"         -> "$@"
   "${hex: 40 }"        -> "@"
   "${HEX: 40}"         -> "@"
   "${hex:40"           -> "${hex:40"
   "${hex:400}"         -> "${hex:400}"
   "${hex:4${hex:30}}"  -> "${hex:40}"
   "${unicode:40}"      -> "@"
   "${ unicode:40}"     -> "${ unicode:40}"
   "${UNICODE:40}"      -> "@"
   "${UnICoDE:0000040}" -> "@"
   "${Unicode:40}"      -> "@"
   "${Unicode:Cool}"    -> "${Unicode:Cool}"
   "${unicode:200000}"  -> error
   "${Unicode:DF01}     -> error

2.5. Tests

 Tests are given as arguments to commands in order to control their
 actions.  In this document, tests are given to if/elsif to decide
 which block of code is run.

Guenther & Showalter Standards Track [Page 11] RFC 5228 Sieve: An Email Filtering Language January 2008

2.5.1. Test Lists

 Some tests ("allof" and "anyof", which implement logical "and" and
 logical "or", respectively) may require more than a single test as an
 argument.  The test-list syntax element provides a way of grouping
 tests as a comma-separated list in parentheses.
 Example:  if anyof (not exists ["From", "Date"],
                 header :contains "from" "fool@example.com") {
              discard;
           }

2.6. Arguments

 In order to specify what to do, most commands take arguments.  There
 are three types of arguments: positional, tagged, and optional.
 It is an error for a script, on a single command, to use conflicting
 arguments or to use a tagged or optional argument more than once.

2.6.1. Positional Arguments

 Positional arguments are given to a command that discerns their
 meaning based on their order.  When a command takes positional
 arguments, all positional arguments must be supplied and must be in
 the order prescribed.

2.6.2. Tagged Arguments

 This document provides for tagged arguments in the style of
 CommonLISP.  These are also similar to flags given to commands in
 most command-line systems.
 A tagged argument is an argument for a command that begins with ":"
 followed by a tag naming the argument, such as ":contains".  This
 argument means that zero or more of the next tokens have some
 particular meaning depending on the argument.  These next tokens may
 be literal data, but they are never blocks.
 Tagged arguments are similar to positional arguments, except that
 instead of the meaning being derived from the command, it is derived
 from the tag.
 Tagged arguments must appear before positional arguments, but they
 may appear in any order with other tagged arguments.  For simplicity
 of the specification, this is not expressed in the syntax definitions

Guenther & Showalter Standards Track [Page 12] RFC 5228 Sieve: An Email Filtering Language January 2008

 with commands, but they still may be reordered arbitrarily provided
 they appear before positional arguments.  Tagged arguments may be
 mixed with optional arguments.
 Tagged arguments SHOULD NOT take tagged arguments as arguments.

2.6.3. Optional Arguments

 Optional arguments are exactly like tagged arguments except that they
 may be left out, in which case a default value is implied.  Because
 optional arguments tend to result in shorter scripts, they have been
 used far more than tagged arguments.
 One particularly noteworthy case is the ":comparator" argument, which
 allows the user to specify which comparator [COLLATION] will be used
 to compare two strings, since different languages may impose
 different orderings on UTF-8 [UTF-8] strings.

2.6.4. Types of Arguments

 Abstractly, arguments may be literal data, tests, or blocks of
 commands.  In this way, an "if" control structure is merely a command
 that happens to take a test and a block as arguments and may execute
 the block of code.
 However, this abstraction is ambiguous from a parsing standpoint.
 The grammar in section 8.2 presents a parsable version of this:
 Arguments are string lists (string-lists), numbers, and tags, which
 may be followed by a test or a test list (test-list), which may be
 followed by a block of commands.  No more than one test or test list,
 or more than one block of commands, may be used, and commands that
 end with a block of commands do not end with semicolons.

2.7. String Comparison

 When matching one string against another, there are a number of ways
 of performing the match operation.  These are accomplished with three
 types of matches: an exact match, a substring match, and a wildcard
 glob-style match.  These are described below.
 In order to provide for matches between character sets and case
 insensitivity, Sieve uses the comparators defined in the Internet
 Application Protocol Collation Registry [COLLATION].

Guenther & Showalter Standards Track [Page 13] RFC 5228 Sieve: An Email Filtering Language January 2008

 However, when a string represents the name of a header, the
 comparator is never user-specified.  Header comparisons are always
 done with the "i;ascii-casemap" operator, i.e., case-insensitive
 comparisons, because this is the way things are defined in the
 message specification [IMAIL].

2.7.1. Match Type

 Commands that perform string comparisons may have an optional match
 type argument.  The three match types in this specification are
 ":contains", ":is", and ":matches".
 The ":contains" match type describes a substring match.  If the value
 argument contains the key argument as a substring, the match is true.
 For instance, the string "frobnitzm" contains "frob" and "nit", but
 not "fbm".  The empty key ("") is contained in all values.
 The ":is" match type describes an absolute match; if the contents of
 the first string are absolutely the same as the contents of the
 second string, they match.  Only the string "frobnitzm" is the string
 "frobnitzm".  The empty key ("") only ":is" matches with the empty
 value.
 The ":matches" match type specifies a wildcard match using the
 characters "*" and "?"; the entire value must be matched.  "*"
 matches zero or more characters in the value and "?" matches a single
 character in the value, where the comparator that is used (see
 section 2.7.3) defines what a character is.  For example, the
 comparators "i;octet" and "i;ascii-casemap" define a character to be
 a single octet, so "?"  will always match exactly one octet when one
 of those comparators is in use.  In contrast, a Unicode-based
 comparator would define a character to be any UTF-8 octet sequence
 encoding one Unicode character and thus "?" may match more than one
 octet.  "?" and "*" may be escaped as "\\?" and "\\*" in strings to
 match against themselves.  The first backslash escapes the second
 backslash; together, they escape the "*".  This is awkward, but it is
 commonplace in several programming languages that use globs and
 regular expressions.
 In order to specify what type of match is supposed to happen,
 commands that support matching take optional arguments ":matches",
 ":is", and ":contains".  Commands default to using ":is" matching if
 no match type argument is supplied.  Note that these modifiers
 interact with comparators; in particular, only comparators that
 support the "substring match" operation are suitable for matching
 with ":contains" or ":matches".  It is an error to use a comparator
 with ":contains" or ":matches" that is not compatible with it.

Guenther & Showalter Standards Track [Page 14] RFC 5228 Sieve: An Email Filtering Language January 2008

 It is an error to give more than one of these arguments to a given
 command.
 For convenience, the "MATCH-TYPE" syntax element is defined here as
 follows:
 Syntax:   ":is" / ":contains" / ":matches"

2.7.2. Comparisons across Character Sets

 Messages may involve a number of character sets.  In order for
 comparisons to work across character sets, implementations SHOULD
 implement the following behavior:
    Comparisons are performed on octets.  Implementations convert text
    from header fields in all charsets [MIME3] to Unicode, encoded as
    UTF-8, as input to the comparator (see section 2.7.3).
    Implementations MUST be capable of converting US-ASCII, ISO-8859-
    1, the US-ASCII subset of ISO-8859-* character sets, and UTF-8.
    Text that the implementation cannot convert to Unicode for any
    reason MAY be treated as plain US-ASCII (including any [MIME3]
    syntax) or processed according to local conventions.  An encoded
    NUL octet (character zero) SHOULD NOT cause early termination of
    the header content being compared against.
 If implementations fail to support the above behavior, they MUST
 conform to the following:
    No two strings can be considered equal if one contains octets
    greater than 127.

2.7.3. Comparators

 In order to allow for language-independent, case-independent matches,
 the match type may be coupled with a comparator name.  The Internet
 Application Protocol Collation Registry [COLLATION] provides the
 framework for describing and naming comparators.
 All implementations MUST support the "i;octet" comparator (simply
 compares octets) and the "i;ascii-casemap" comparator (which treats
 uppercase and lowercase characters in the US-ASCII subset of UTF-8 as
 the same).  If left unspecified, the default is "i;ascii-casemap".
 Some comparators may not be usable with substring matches; that is,
 they may only work with ":is".  It is an error to try to use a
 comparator with ":matches" or ":contains" that is not compatible with
 it.

Guenther & Showalter Standards Track [Page 15] RFC 5228 Sieve: An Email Filtering Language January 2008

 Sieve treats a comparator result of "undefined" the same as a result
 of "no-match".  That is, this base specification does not provide any
 means to directly detect invalid comparator input.
 A comparator is specified by the ":comparator" option with commands
 that support matching.  This option is followed by a string providing
 the name of the comparator to be used.  For convenience, the syntax
 of a comparator is abbreviated to "COMPARATOR", and (repeated in
 several tests) is as follows:
 Syntax:   ":comparator" <comparator-name: string>
 So in this example,
 Example:  if header :contains :comparator "i;octet" "Subject"
                 "MAKE MONEY FAST" {
              discard;
           }
 would discard any message with subjects like "You can MAKE MONEY
 FAST", but not "You can Make Money Fast", since the comparator used
 is case-sensitive.
 Comparators other than "i;octet" and "i;ascii-casemap" must be
 declared with require, as they are extensions.  If a comparator
 declared with require is not known, it is an error, and execution
 fails.  If the comparator is not declared with require, it is also an
 error, even if the comparator is supported.  (See section 2.10.5.)
 Both ":matches" and ":contains" match types are compatible with the
 "i;octet" and "i;ascii-casemap" comparators and may be used with
 them.
 It is an error to give more than one of these arguments to a given
 command.

2.7.4. Comparisons against Addresses

 Addresses are one of the most frequent things represented as strings.
 These are structured, and being able to compare against the local-
 part or the domain of an address is useful, so some tests that act
 exclusively on addresses take an additional optional argument that
 specifies what the test acts on.
 These optional arguments are ":localpart", ":domain", and ":all",
 which act on the local-part (left side), the domain-part (right
 side), and the whole address.

Guenther & Showalter Standards Track [Page 16] RFC 5228 Sieve: An Email Filtering Language January 2008

 If an address is not syntactically valid, then it will not be matched
 by tests specifying ":localpart" or ":domain".
 The kind of comparison done, such as whether or not the test done is
 case-insensitive, is specified as a comparator argument to the test.
 If an optional address-part is omitted, the default is ":all".
 It is an error to give more than one of these arguments to a given
 command.
 For convenience, the "ADDRESS-PART" syntax element is defined here as
 follows:
 Syntax:   ":localpart" / ":domain" / ":all"

2.8. Blocks

 Blocks are sets of commands enclosed within curly braces and supplied
 as the final argument to a command.  Such a command is a control
 structure: when executed it has control over the number of times the
 commands in the block are executed.
 With the commands supplied in this memo, there are no loops.  The
 control structures supplied--if, elsif, and else--run a block either
 once or not at all.

2.9. Commands

 Sieve scripts are sequences of commands.  Commands can take any of
 the tokens above as arguments, and arguments may be either tagged or
 positional arguments.  Not all commands take all arguments.
 There are three kinds of commands: test commands, action commands,
 and control commands.
 The simplest is an action command.  An action command is an
 identifier followed by zero or more arguments, terminated by a
 semicolon.  Action commands do not take tests or blocks as arguments.
 The actions referenced in this document are:
  1. keep, to save the message in the default location
  2. fileinto, to save the message in a specific mailbox
  3. redirect, to forward the message to another address
  4. discard, to silently throw away the message

Guenther & Showalter Standards Track [Page 17] RFC 5228 Sieve: An Email Filtering Language January 2008

 A control command is a command that affects the parsing or the flow
 of execution of the Sieve script in some way.  A control structure is
 a control command that ends with a block instead of a semicolon.
 A test command is used as part of a control command.  It is used to
 specify whether or not the block of code given to the control command
 is executed.

2.10. Evaluation

2.10.1. Action Interaction

 Some actions cannot be used with other actions because the result
 would be absurd.  These restrictions are noted throughout this memo.
 Extension actions MUST state how they interact with actions defined
 in this specification.

2.10.2. Implicit Keep

 Previous experience with filtering systems suggests that cases tend
 to be missed in scripts.  To prevent errors, Sieve has an "implicit
 keep".
 An implicit keep is a keep action (see section 4.3) performed in
 absence of any action that cancels the implicit keep.
 An implicit keep is performed if a message is not written to a
 mailbox, redirected to a new address, or explicitly thrown out.  That
 is, if a fileinto, a keep, a redirect, or a discard is performed, an
 implicit keep is not.
 Some actions may be defined to not cancel the implicit keep.  These
 actions may not directly affect the delivery of a message, and are
 used for their side effects.  None of the actions specified in this
 document meet that criteria, but extension actions may.
 For instance, with any of the short messages offered above, the
 following script produces no actions.
 Example:  if size :over 500K { discard; }
 As a result, the implicit keep is taken.

Guenther & Showalter Standards Track [Page 18] RFC 5228 Sieve: An Email Filtering Language January 2008

2.10.3. Message Uniqueness in a Mailbox

 Implementations SHOULD NOT deliver a message to the same mailbox more
 than once, even if a script explicitly asks for a message to be
 written to a mailbox twice.
 The test for equality of two messages is implementation-defined.
 If a script asks for a message to be written to a mailbox twice, it
 MUST NOT be treated as an error.

2.10.4. Limits on Numbers of Actions

 Site policy MAY limit the number of actions taken and MAY impose
 restrictions on which actions can be used together.  In the event
 that a script hits a policy limit on the number of actions taken for
 a particular message, an error occurs.
 Implementations MUST allow at least one keep or one fileinto.  If
 fileinto is not implemented, implementations MUST allow at least one
 keep.

2.10.5. Extensions and Optional Features

 Because of the differing capabilities of many mail systems, several
 features of this specification are optional.  Before any of these
 extensions can be executed, they must be declared with the "require"
 action.
 If an extension is not enabled with "require", implementations MUST
 treat it as if they did not support it at all.  This protects scripts
 from having their behavior altered by extensions that the script
 author might not have even been aware of.
 Implementations MUST NOT execute any Sieve script test or command
 subsequent to "require" if one of the required extensions is
 unavailable.
    Note: The reason for this restriction is that prior experiences
    with languages such as LISP and Tcl suggest that this is a
    workable way of noting that a given script uses an extension.
 Extensions that define actions MUST state how they interact with
 actions discussed in the base specification.

Guenther & Showalter Standards Track [Page 19] RFC 5228 Sieve: An Email Filtering Language January 2008

2.10.6. Errors

 In any programming language, there are compile-time and run-time
 errors.
 Compile-time errors are ones in syntax that are detectable if a
 syntax check is done.
 Run-time errors are not detectable until the script is run.  This
 includes transient failures like disk full conditions, but also
 includes issues like invalid combinations of actions.
 When an error occurs in a Sieve script, all processing stops.
 Implementations MAY choose to do a full parse, then evaluate the
 script, then do all actions.  Implementations might even go so far as
 to ensure that execution is atomic (either all actions are executed
 or none are executed).
 Other implementations may choose to parse and run at the same time.
 Such implementations are simpler, but have issues with partial
 failure (some actions happen, others don't).
 Implementations MUST perform syntactic, semantic, and run-time checks
 on code that is actually executed.  Implementations MAY perform those
 checks or any part of them on code that is not reached during
 execution.
 When an error happens, implementations MUST notify the user that an
 error occurred and which actions (if any) were taken, and do an
 implicit keep.

2.10.7. Limits on Execution

 Implementations may limit certain constructs.  However, this
 specification places a lower bound on some of these limits.
 Implementations MUST support fifteen levels of nested blocks.
 Implementations MUST support fifteen levels of nested test lists.

Guenther & Showalter Standards Track [Page 20] RFC 5228 Sieve: An Email Filtering Language January 2008

3. Control Commands

 Control structures are needed to allow for multiple and conditional
 actions.

3.1. Control if

 There are three pieces to if: "if", "elsif", and "else".  Each is
 actually a separate command in terms of the grammar.  However, an
 elsif or else MUST only follow an if or elsif.  An error occurs if
 these conditions are not met.
 Usage:   if <test1: test> <block1: block>
 Usage:   elsif <test2: test> <block2: block>
 Usage:   else <block3: block>
 The semantics are similar to those of any of the many other
 programming languages these control structures appear in.  When the
 interpreter sees an "if", it evaluates the test associated with it.
 If the test is true, it executes the block associated with it.
 If the test of the "if" is false, it evaluates the test of the first
 "elsif" (if any).  If the test of "elsif" is true, it runs the
 elsif's block.  An elsif may be followed by an elsif, in which case,
 the interpreter repeats this process until it runs out of elsifs.
 When the interpreter runs out of elsifs, there may be an "else" case.
 If there is, and none of the if or elsif tests were true, the
 interpreter runs the else's block.
 This provides a way of performing exactly one of the blocks in the
 chain.
 In the following example, both messages A and B are dropped.
 Example:  require "fileinto";
           if header :contains "from" "coyote" {
              discard;
           } elsif header :contains ["subject"] ["$$$"] {
              discard;
           } else {
              fileinto "INBOX";
           }

Guenther & Showalter Standards Track [Page 21] RFC 5228 Sieve: An Email Filtering Language January 2008

 When the script below is run over message A, it redirects the message
 to acm@example.com; message B, to postmaster@example.com; any other
 message is redirected to field@example.com.
 Example:  if header :contains ["From"] ["coyote"] {
              redirect "acm@example.com";
           } elsif header :contains "Subject" "$$$" {
              redirect "postmaster@example.com";
           } else {
              redirect "field@example.com";
           }
 Note that this definition prohibits the "... else if ..." sequence
 used by C.  This is intentional, because this construct produces a
 shift-reduce conflict.

3.2. Control require

 Usage:   require <capabilities: string-list>
 The require action notes that a script makes use of a certain
 extension.  Such a declaration is required to use the extension, as
 discussed in section 2.10.5.  Multiple capabilities can be declared
 with a single require.
 The require command, if present, MUST be used before anything other
 than a require can be used.  An error occurs if a require appears
 after a command other than require.
 Example:  require ["fileinto", "reject"];
 Example:  require "fileinto";
           require "vacation";

3.3. Control stop

 Usage:   stop
 The "stop" action ends all processing.  If the implicit keep has not
 been cancelled, then it is taken.

Guenther & Showalter Standards Track [Page 22] RFC 5228 Sieve: An Email Filtering Language January 2008

4. Action Commands

 This document supplies four actions that may be taken on a message:
 keep, fileinto, redirect, and discard.
 Implementations MUST support the "keep", "discard", and "redirect"
 actions.
 Implementations SHOULD support "fileinto".
 Implementations MAY limit the number of certain actions taken (see
 section 2.10.4).

4.1. Action fileinto

 Usage:   fileinto <mailbox: string>
 The "fileinto" action delivers the message into the specified
 mailbox.  Implementations SHOULD support fileinto, but in some
 environments this may be impossible.  Implementations MAY place
 restrictions on mailbox names; use of an invalid mailbox name MAY be
 treated as an error or result in delivery to an implementation-
 defined mailbox.  If the specified mailbox doesn't exist, the
 implementation MAY treat it as an error, create the mailbox, or
 deliver the message to an implementation-defined mailbox.  If the
 implementation uses a different encoding scheme than UTF-8 for
 mailbox names, it SHOULD reencode the mailbox name from UTF-8 to its
 encoding scheme.  For example, the Internet Message Access Protocol
 [IMAP] uses modified UTF-7, such that a mailbox argument of "odds &
 ends" would appear in IMAP as "odds &- ends".
 The capability string for use with the require command is "fileinto".
 In the following script, message A is filed into mailbox
 "INBOX.harassment".
 Example:  require "fileinto";
           if header :contains ["from"] "coyote" {
              fileinto "INBOX.harassment";
           }

4.2. Action redirect

 Usage:   redirect <address: string>
 The "redirect" action is used to send the message to another user at
 a supplied address, as a mail forwarding feature does.  The
 "redirect" action makes no changes to the message body or existing

Guenther & Showalter Standards Track [Page 23] RFC 5228 Sieve: An Email Filtering Language January 2008

 headers, but it may add new headers.  In particular, existing
 Received headers MUST be preserved and the count of Received headers
 in the outgoing message MUST be larger than the same count on the
 message as received by the implementation.  (An implementation that
 adds a Received header before processing the message does not need to
 add another when redirecting.)
 The message is sent back out with the address from the redirect
 command as an envelope recipient.  Implementations MAY combine
 separate redirects for a given message into a single submission with
 multiple envelope recipients.  (This is not a Mail User Agent (MUA)-
 style forward, which creates a new message with a different sender
 and message ID, wrapping the old message in a new one.)
 The envelope sender address on the outgoing message is chosen by the
 sieve implementation.  It MAY be copied from the message being
 processed.  However, if the message being processed has an empty
 envelope sender address the outgoing message MUST also have an empty
 envelope sender address.  This last requirement is imposed to prevent
 loops in the case where a message is redirected to an invalid address
 when then returns a delivery status notification that also ends up
 being redirected to the same invalid address.
 A simple script can be used for redirecting all mail:
 Example:  redirect "bart@example.com";
 Implementations MUST take measures to implement loop control,
 possibly including adding headers to the message or counting Received
 headers as specified in section 6.2 of [SMTP].  If an implementation
 detects a loop, it causes an error.
 Implementations MUST provide means of limiting the number of
 redirects a Sieve script can perform.  See section 10 for more
 details.
 Implementations MAY ignore a redirect action silently due to policy
 reasons.  For example, an implementation MAY choose not to redirect
 to an address that is known to be undeliverable.  Any ignored
 redirect MUST NOT cancel the implicit keep.

4.3. Action keep

 Usage:   keep
 The "keep" action is whatever action is taken in lieu of all other
 actions, if no filtering happens at all; generally, this simply means
 to file the message into the user's main mailbox.  This command

Guenther & Showalter Standards Track [Page 24] RFC 5228 Sieve: An Email Filtering Language January 2008

 provides a way to execute this action without needing to know the
 name of the user's main mailbox, providing a way to call it without
 needing to understand the user's setup or the underlying mail system.
 For instance, in an implementation where the IMAP server is running
 scripts on behalf of the user at time of delivery, a keep command is
 equivalent to a fileinto "INBOX".
 Example:  if size :under 1M { keep; } else { discard; }
 Note that the above script is identical to the one below.
 Example:  if not size :under 1M { discard; }

4.4. Action discard

 Usage:   discard
 Discard is used to silently throw away the message.  It does so by
 simply canceling the implicit keep.  If discard is used with other
 actions, the other actions still happen.  Discard is compatible with
 all other actions.  (For instance, fileinto+discard is equivalent to
 fileinto.)
 Discard MUST be silent; that is, it MUST NOT return a non-delivery
 notification of any kind ([DSN], [MDN], or otherwise).
 In the following script, any mail from "idiot@example.com" is thrown
 out.
 Example:  if header :contains ["from"] ["idiot@example.com"] {
              discard;
           }
 While an important part of this language, "discard" has the potential
 to create serious problems for users: Students who leave themselves
 logged in to an unattended machine in a public computer lab may find
 their script changed to just "discard".  In order to protect users in
 this situation (along with similar situations), implementations MAY
 keep messages destroyed by a script for an indefinite period, and MAY
 disallow scripts that throw out all mail.

Guenther & Showalter Standards Track [Page 25] RFC 5228 Sieve: An Email Filtering Language January 2008

5. Test Commands

 Tests are used in conditionals to decide which part(s) of the
 conditional to execute.
 Implementations MUST support these tests: "address", "allof",
 "anyof", "exists", "false", "header", "not", "size", and "true".
 Implementations SHOULD support the "envelope" test.

5.1. Test address

 Usage:   address [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE]
          <header-list: string-list> <key-list: string-list>
 The "address" test matches Internet addresses in structured headers
 that contain addresses.  It returns true if any header contains any
 key in the specified part of the address, as modified by the
 comparator and the match keyword.  Whether there are other addresses
 present in the header doesn't affect this test; this test does not
 provide any way to determine whether an address is the only address
 in a header.
 Like envelope and header, this test returns true if any combination
 of the header-list and key-list arguments match and returns false
 otherwise.
 Internet email addresses [IMAIL] have the somewhat awkward
 characteristic that the local-part to the left of the at-sign is
 considered case sensitive, and the domain-part to the right of the
 at-sign is case insensitive.  The "address" command does not deal
 with this itself, but provides the ADDRESS-PART argument for allowing
 users to deal with it.
 The address primitive never acts on the phrase part of an email
 address or on comments within that address.  It also never acts on
 group names, although it does act on the addresses within the group
 construct.
 Implementations MUST restrict the address test to headers that
 contain addresses, but MUST include at least From, To, Cc, Bcc,
 Sender, Resent-From, and Resent-To, and it SHOULD include any other
 header that utilizes an "address-list" structured header body.
 Example:  if address :is :all "from" "tim@example.com" {
              discard;
           }

Guenther & Showalter Standards Track [Page 26] RFC 5228 Sieve: An Email Filtering Language January 2008

5.2. Test allof

 Usage:   allof <tests: test-list>
 The "allof" test performs a logical AND on the tests supplied to it.
 Example:  allof (false, false)  =>   false
           allof (false, true)   =>   false
           allof (true,  true)   =>   true
 The allof test takes as its argument a test-list.

5.3. Test anyof

 Usage:   anyof <tests: test-list>
 The "anyof" test performs a logical OR on the tests supplied to it.
 Example:  anyof (false, false)  =>   false
           anyof (false, true)   =>   true
           anyof (true,  true)   =>   true

5.4. Test envelope

 Usage:   envelope [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE]
          <envelope-part: string-list> <key-list: string-list>
 The "envelope" test is true if the specified part of the [SMTP] (or
 equivalent) envelope matches the specified key.  This specification
 defines the interpretation of the (case insensitive) "from" and "to"
 envelope-parts.  Additional envelope-parts may be defined by other
 extensions; implementations SHOULD consider unknown envelope parts an
 error.
 If one of the envelope-part strings is (case insensitive) "from",
 then matching occurs against the FROM address used in the SMTP MAIL
 command.  The null reverse-path is matched against as the empty
 string, regardless of the ADDRESS-PART argument specified.
 If one of the envelope-part strings is (case insensitive) "to", then
 matching occurs against the TO address used in the SMTP RCPT command
 that resulted in this message getting delivered to this user.  Note
 that only the most recent TO is available, and only the one relevant
 to this user.
 The envelope-part is a string list and may contain more than one
 parameter, in which case all of the strings specified in the key-list
 are matched against all parts given in the envelope-part list.

Guenther & Showalter Standards Track [Page 27] RFC 5228 Sieve: An Email Filtering Language January 2008

 Like address and header, this test returns true if any combination of
 the envelope-part list and key-list arguments match and returns false
 otherwise.
 All tests against envelopes MUST drop source routes.
 If the SMTP transaction involved several RCPT commands, only the data
 from the RCPT command that caused delivery to this user is available
 in the "to" part of the envelope.
 If a protocol other than SMTP is used for message transport,
 implementations are expected to adapt this command appropriately.
 The envelope command is optional.  Implementations SHOULD support it,
 but the necessary information may not be available in all cases.  The
 capability string for use with the require command is "envelope".
 Example:  require "envelope";
           if envelope :all :is "from" "tim@example.com" {
              discard;
           }

5.5. Test exists

 Usage:   exists <header-names: string-list>
 The "exists" test is true if the headers listed in the header-names
 argument exist within the message.  All of the headers must exist or
 the test is false.
 The following example throws out mail that doesn't have a From header
 and a Date header.
 Example:  if not exists ["From","Date"] {
              discard;
           }

5.6. Test false

 Usage:   false
 The "false" test always evaluates to false.

Guenther & Showalter Standards Track [Page 28] RFC 5228 Sieve: An Email Filtering Language January 2008

5.7. Test header

 Usage:   header [COMPARATOR] [MATCH-TYPE]
          <header-names: string-list> <key-list: string-list>
 The "header" test evaluates to true if the value of any of the named
 headers, ignoring leading and trailing whitespace, matches any key.
 The type of match is specified by the optional match argument, which
 defaults to ":is" if not specified, as specified in section 2.6.
 Like address and envelope, this test returns true if any combination
 of the header-names list and key-list arguments match and returns
 false otherwise.
 If a header listed in the header-names argument exists, it contains
 the empty key ("").  However, if the named header is not present, it
 does not match any key, including the empty key.  So if a message
 contained the header
         X-Caffeine: C8H10N4O2
 these tests on that header evaluate as follows:
         header :is ["X-Caffeine"] [""]         => false
         header :contains ["X-Caffeine"] [""]   => true
 Testing whether a given header is either absent or doesn't contain
 any non-whitespace characters can be done using a negated "header"
 test:
         not header :matches "Cc" "?*"

5.8. Test not

 Usage:   not <test1: test>
 The "not" test takes some other test as an argument, and yields the
 opposite result.  "not false" evaluates to "true" and "not true"
 evaluates to "false".

5.9. Test size

 Usage:   size <":over" / ":under"> <limit: number>
 The "size" test deals with the size of a message.  It takes either a
 tagged argument of ":over" or ":under", followed by a number
 representing the size of the message.

Guenther & Showalter Standards Track [Page 29] RFC 5228 Sieve: An Email Filtering Language January 2008

 If the argument is ":over", and the size of the message is greater
 than the number provided, the test is true; otherwise, it is false.
 If the argument is ":under", and the size of the message is less than
 the number provided, the test is true; otherwise, it is false.
 Exactly one of ":over" or ":under" must be specified, and anything
 else is an error.
 The size of a message is defined to be the number of octets in the
 [IMAIL] representation of the message.
 Note that for a message that is exactly 4,000 octets, the message is
 neither ":over" nor ":under" 4000 octets.

5.10. Test true

 Usage:   true
 The "true" test always evaluates to true.

6. Extensibility

 New control commands, actions, and tests can be added to the
 language.  Sites must make these features known to their users; this
 document does not define a way to discover the list of extensions
 supported by the server.
 Any extensions to this language MUST define a capability string that
 uniquely identifies that extension.  Capability string are case-
 sensitive; for example, "foo" and "FOO" are different capabilities.
 If a new version of an extension changes the functionality of a
 previously defined extension, it MUST use a different name.
 Extensions may register a set of related capabilities by registering
 just a unique prefix for them.  The "comparator-" prefix is an
 example of this.  The prefix MUST end with a "-" and MUST NOT overlap
 any existing registrations.
 In a situation where there is a script submission protocol and an
 extension advertisement mechanism aware of the details of this
 language, scripts submitted can be checked against the mail server to
 prevent use of an extension that the server does not support.
 Extensions MUST state how they interact with constraints defined in
 section 2.10, e.g., whether they cancel the implicit keep, and which
 actions they are compatible and incompatible with.  Extensions MUST
 NOT change the behavior of the "require" control command or alter the
 interpretation of the argument to the "require" control.

Guenther & Showalter Standards Track [Page 30] RFC 5228 Sieve: An Email Filtering Language January 2008

 Extensions that can submit new email messages or otherwise generate
 new protocol requests MUST consider loop suppression, at least to
 document any security considerations.

6.1. Capability String

 Capability strings are typically short strings describing what
 capabilities are supported by the server.
 Capability strings beginning with "vnd." represent vendor-defined
 extensions.  Such extensions are not defined by Internet standards or
 RFCs, but are still registered with IANA in order to prevent
 conflicts.  Extensions starting with "vnd." SHOULD be followed by the
 name of the vendor and product, such as "vnd.acme.rocket-sled".
 The following capability strings are defined by this document:
 encoded-character The string "encoded-character" indicates that the
             implementation supports the interpretation of
             "${hex:...}" and "${unicode:...}" in strings.
 envelope    The string "envelope" indicates that the implementation
             supports the "envelope" command.
 fileinto    The string "fileinto" indicates that the implementation
             supports the "fileinto" command.
 comparator- The string "comparator-elbonia" is provided if the
             implementation supports the "elbonia" comparator.
             Therefore, all implementations have at least the
             "comparator-i;octet" and "comparator-i;ascii-casemap"
             capabilities.  However, these comparators may be used
             without being declared with require.

6.2. IANA Considerations

 In order to provide a standard set of extensions, a registry is
 maintained by IANA.  This registry contains both vendor-controlled
 capability names (beginning with "vnd.") and IETF-controlled
 capability names.  Vendor-controlled capability names may be
 registered on a first-come, first-served basis, by applying to IANA
 with the form in the following section.  Registration of capability
 prefixes that do not begin with "vnd." REQUIRES a standards track or
 IESG-approved experimental RFC.
 Extensions designed for interoperable use SHOULD use IETF-controlled
 capability names.

Guenther & Showalter Standards Track [Page 31] RFC 5228 Sieve: An Email Filtering Language January 2008

6.2.1. Template for Capability Registrations

 The following template is to be used for registering new Sieve
 extensions with IANA.
 To: iana@iana.org
 Subject: Registration of new Sieve extension
 Capability name: [the string for use in the 'require' statement]
 Description:     [a brief description of what the extension adds
                   or changes]
 RFC number:      [for extensions published as RFCs]
 Contact address: [email and/or physical address to contact for
                   additional information]

6.2.2. Handling of Existing Capability Registrations

 In order to bring the existing capability registrations in line with
 the new template, IANA has modified each as follows:
 1. The "capability name" and "capability arguments" fields have been
    eliminated
 2. The "capability keyword" field have been renamed to "Capability
    name"
 3. An empty "Description" field has been added
 4. The "Standards Track/IESG-approved experimental RFC number" field
    has been renamed to "RFC number"
 5. The "Person and email address to contact for further information"
    field should be renamed to "Contact address"

6.2.3. Initial Capability Registrations

 This RFC updates the following entries in the IANA registry for Sieve
 extensions.
 Capability name: encoded-character
 Description:     changes the interpretation of strings to allow
                  arbitrary octets and Unicode characters to be
                  represented using US-ASCII
 RFC number:      RFC 5228 (Sieve base spec)
 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
 Capability name: fileinto
 Description:     adds the 'fileinto' action for delivering to a
                  mailbox other than the default
 RFC number:      RFC 5228 (Sieve base spec)
 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>

Guenther & Showalter Standards Track [Page 32] RFC 5228 Sieve: An Email Filtering Language January 2008

 Capability name: envelope
 Description:     adds the 'envelope' test for testing the message
                  transport sender and recipient address
 RFC number:      RFC 5228 (Sieve base spec)
 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
 Capability name: comparator-* (anything starting with "comparator-")
 Description:     adds the indicated comparator for use with the
                  :comparator argument
 RFC number:      RFC 5228 (Sieve base spec) and [COLLATION]
 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>

6.3. Capability Transport

 A method of advertising which capabilities an implementation supports
 is difficult due to the wide range of possible implementations.  Such
 a mechanism, however, should have the property that the
 implementation can advertise the complete set of extensions that it
 supports.

7. Transmission

 The [MIME] type for a Sieve script is "application/sieve".
 The registration of this type for RFC 2048 requirements is updated as
 follows:
  Subject: Registration of MIME media type application/sieve
  MIME media type name: application
  MIME subtype name: sieve
  Required parameters: none
  Optional parameters: none
  Encoding considerations: Most Sieve scripts will be textual,
     written in UTF-8.  When non-7bit characters are used,
     quoted-printable is appropriate for transport systems
     that require 7bit encoding.
  Security considerations: Discussed in section 10 of this RFC.
  Interoperability considerations: Discussed in section 2.10.5
     of this RFC.
  Published specification: this RFC.
  Applications that use this media type: sieve-enabled mail
    servers and clients
  Additional information:
    Magic number(s):
    File extension(s): .siv .sieve
    Macintosh File Type Code(s):

Guenther & Showalter Standards Track [Page 33] RFC 5228 Sieve: An Email Filtering Language January 2008

  Person & email address to contact for further information:
     See the discussion list at ietf-mta-filters@imc.org.
  Intended usage:
     COMMON
  Author/Change controller:
     The SIEVE WG, delegated by the IESG.

8. Parsing

 The Sieve grammar is separated into tokens and a separate grammar as
 most programming languages are.  Additional rules are supplied here
 for common arguments to various language facilities.

8.1. Lexical Tokens

 Sieve scripts are encoded in UTF-8.  The following assumes a valid
 UTF-8 encoding; special characters in Sieve scripts are all US-ASCII.
 The following are tokens in Sieve:
  1. identifiers
  2. tags
  3. numbers
  4. quoted strings
  5. multi-line strings
  6. other separators
 Identifiers, tags, and numbers are case-insensitive, while quoted
 strings and multi-line strings are case-sensitive.
 Blanks, horizontal tabs, CRLFs, and comments ("whitespace") are
 ignored except as they separate tokens.  Some whitespace is required
 to separate otherwise adjacent tokens and in specific places in the
 multi-line strings.  CR and LF can only appear in CRLF pairs.
 The other separators are single individual characters and are
 mentioned explicitly in the grammar.
 The lexical structure of sieve is defined in the following grammar
 (as described in [ABNF]):
 bracket-comment    = "/*" *not-star 1*STAR
                      *(not-star-slash *not-star 1*STAR) "/"
                        ; No */ allowed inside a comment.
                        ; (No * is allowed unless it is the last
                        ; character, or unless it is followed by a
                        ; character that isn't a slash.)

Guenther & Showalter Standards Track [Page 34] RFC 5228 Sieve: An Email Filtering Language January 2008

 comment            = bracket-comment / hash-comment
 hash-comment       = "#" *octet-not-crlf CRLF
 identifier         = (ALPHA / "_") *(ALPHA / DIGIT / "_")
 multi-line         = "text:" *(SP / HTAB) (hash-comment / CRLF)
                      *(multiline-literal / multiline-dotstart)
                      "." CRLF
 multiline-literal  = [ octet-not-period *octet-not-crlf ] CRLF
 multiline-dotstart = "." 1*octet-not-crlf CRLF
                        ; A line containing only "." ends the
                        ; multi-line.  Remove a leading '.' if
                        ; followed by another '.'.
 not-star           = CRLF / %x01-09 / %x0B-0C / %x0E-29 / %x2B-FF
                        ; either a CRLF pair, OR a single octet
                        ; other than NUL, CR, LF, or star
 not-star-slash     = CRLF / %x01-09 / %x0B-0C / %x0E-29 / %x2B-2E /
                      %x30-FF
                        ; either a CRLF pair, OR a single octet
                        ; other than NUL, CR, LF, star, or slash
 number             = 1*DIGIT [ QUANTIFIER ]
 octet-not-crlf     = %x01-09 / %x0B-0C / %x0E-FF
                        ; a single octet other than NUL, CR, or LF
 octet-not-period   = %x01-09 / %x0B-0C / %x0E-2D / %x2F-FF
                        ; a single octet other than NUL,
                        ; CR, LF, or period
 octet-not-qspecial = %x01-09 / %x0B-0C / %x0E-21 / %x23-5B / %x5D-FF
                        ; a single octet other than NUL,
                        ; CR, LF, double-quote, or backslash
 QUANTIFIER         = "K" / "M" / "G"
 quoted-other       = "\" octet-not-qspecial
                        ; represents just the octet-no-qspecial
                        ; character.  SHOULD NOT be used
 quoted-safe        = CRLF / octet-not-qspecial
                        ; either a CRLF pair, OR a single octet other
                        ; than NUL, CR, LF, double-quote, or backslash

Guenther & Showalter Standards Track [Page 35] RFC 5228 Sieve: An Email Filtering Language January 2008

 quoted-special     = "\" (DQUOTE / "\")
                        ; represents just a double-quote or backslash
 quoted-string      = DQUOTE quoted-text DQUOTE
 quoted-text        = *(quoted-safe / quoted-special / quoted-other)
 STAR               = "*"
 tag                = ":" identifier
 white-space        = 1*(SP / CRLF / HTAB) / comment

8.2. Grammar

 The following is the grammar of Sieve after it has been lexically
 interpreted.  No whitespace or comments appear below.  The start
 symbol is "start".
 argument     = string-list / number / tag
 arguments    = *argument [ test / test-list ]
 block        = "{" commands "}"
 command      = identifier arguments (";" / block)
 commands     = *command
 start        = commands
 string       = quoted-string / multi-line
 string-list  = "[" string *("," string) "]" / string
                  ; if there is only a single string, the brackets
                  ; are optional
 test         = identifier arguments
 test-list    = "(" test *("," test) ")"

8.3. Statement Elements

 These elements are collected from the "Syntax" sections elsewhere in
 this document, and are provided here in [ABNF] syntax so that they
 can be modified by extensions.
 ADDRESS-PART = ":localpart" / ":domain" / ":all"

Guenther & Showalter Standards Track [Page 36] RFC 5228 Sieve: An Email Filtering Language January 2008

 COMPARATOR   = ":comparator" string
 MATCH-TYPE   = ":is" / ":contains" / ":matches"

9. Extended Example

 The following is an extended example of a Sieve script.  Note that it
 does not make use of the implicit keep.
  #
  # Example Sieve Filter
  # Declare any optional features or extension used by the script
  #
  require ["fileinto"];
  #
  # Handle messages from known mailing lists
  # Move messages from IETF filter discussion list to filter mailbox
  #
  if header :is "Sender" "owner-ietf-mta-filters@imc.org"
          {
          fileinto "filter";  # move to "filter" mailbox
          }
  #
  # Keep all messages to or from people in my company
  #
  elsif address :DOMAIN :is ["From", "To"] "example.com"
          {
          keep;               # keep in "In" mailbox
          }
  #
  # Try and 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", "Bcc"] "me@example.com",
               header :matches "subject"
                 ["*make*money*fast*", "*university*dipl*mas*"])
          {
          fileinto "spam";   # move to "spam" mailbox
          }
  else
          {
          # Move all other (non-company) mail to "personal"
          # mailbox.
          fileinto "personal";
          }

Guenther & Showalter Standards Track [Page 37] RFC 5228 Sieve: An Email Filtering Language January 2008

10. Security Considerations

 Users must get their mail.  It is imperative that whatever
 implementations use to store the user-defined filtering scripts
 protect them from unauthorized modification, to preserve the
 integrity of the mail system.  An attacker who can modify a script
 can cause mail to be discarded, rejected, or forwarded to an
 unauthorized recipient.  In addition, it's possible that Sieve
 scripts might expose private information, such as mailbox names, or
 email addresses of favored (or disfavored) correspondents.  Because
 of that, scripts SHOULD also be protected from unauthorized
 retrieval.
 Several commands, such as "discard", "redirect", and "fileinto",
 allow for actions to be taken that are potentially very dangerous.
 Use of the "redirect" command to generate notifications may easily
 overwhelm the target address, especially if it was not designed to
 handle large messages.
 Allowing a single script to redirect to multiple destinations can be
 used as a means of amplifying the number of messages in an attack.
 Moreover, if loop detection is not properly implemented, it may be
 possible to set up exponentially growing message loops.  Accordingly,
 Sieve implementations:
 (1) MUST implement facilities to detect and break message loops.  See
     section 6.2 of [SMTP] for additional information on basic loop
     detection strategies.
 (2) MUST provide the means for administrators to limit the ability of
     users to abuse redirect.  In particular, it MUST be possible to
     limit the number of redirects a script can perform.
     Additionally, if no use cases exist for using redirect to
     multiple destinations, this limit SHOULD be set to 1.  Additional
     limits, such as the ability to restrict redirect to local users,
     MAY also be implemented.
 (3) MUST provide facilities to log use of redirect in order to
     facilitate tracking down abuse.
 (4) MAY use script analysis to determine whether or not a given
     script can be executed safely.  While the Sieve language is
     sufficiently complex that full analysis of all possible scripts
     is computationally infeasible, the majority of real-world scripts
     are amenable to analysis.  For example, an implementation might

Guenther & Showalter Standards Track [Page 38] RFC 5228 Sieve: An Email Filtering Language January 2008

     allow scripts that it has determined are safe to run unhindered,
     block scripts that are potentially problematic, and subject
     unclassifiable scripts to additional auditing and logging.
 Allowing redirects at all may not be appropriate in situations where
 email accounts are freely available and/or not trackable to a human
 who can be held accountable for creating message bombs or other
 abuse.
 As with any filter on a message stream, if the Sieve implementation
 and the mail agents 'behind' Sieve in the message stream differ in
 their interpretation of the messages, it may be possible for an
 attacker to subvert the filter.  Of particular note are differences
 in the interpretation of malformed messages (e.g., missing or extra
 syntax characters) or those that exhibit corner cases (e.g., NUL
 octets encoded via [MIME3]).

11. Acknowledgments

 This document has been revised in part based on comments and
 discussions that took place on and off the SIEVE mailing list.
 Thanks to Sharon Chisholm, Cyrus Daboo, Ned Freed, Arnt Gulbrandsen,
 Michael Haardt, Kjetil Torgrim Homme, Barry Leiba, Mark E. Mallett,
 Alexey Melnikov, Eric Rescorla, Rob Siemborski, and Nigel Swinson for
 reviews and suggestions.

12. Normative References

 [ABNF]      Crocker, D., Ed., and P. Overell, "Augmented BNF for
             Syntax Specifications: ABNF", RFC 4234, October 2005.
 [COLLATION] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
             Application Protocol Collation Registry", RFC 4790, March
             2007.
 [IMAIL]     Resnick, P., Ed., "Internet Message Format", RFC 2822,
             April 2001.
 [KEYWORDS]  Bradner, S., "Key words for use in RFCs to Indicate
             Requirement Levels", BCP 14, RFC 2119, March 1997.
 [MIME]      Freed, N. and N. Borenstein, "Multipurpose Internet Mail
             Extensions (MIME) Part One: Format of Internet Message
             Bodies", RFC 2045, November 1996.
 [MIME3]     Moore, K., "MIME (Multipurpose Internet Mail Extensions)
             Part Three: Message Header Extensions for Non-ASCII
             Text", RFC 2047, November 1996.

Guenther & Showalter Standards Track [Page 39] RFC 5228 Sieve: An Email Filtering Language January 2008

 [SMTP]      Klensin, J., Ed., "Simple Mail Transfer Protocol", RFC
             2821, April 2001.
 [UTF-8]     Yergeau, F., "UTF-8, a transformation format of ISO
             10646", STD 63, RFC 3629, November 2003.

13. Informative References

 [BINARY-SI] "Standard IEC 60027-2: Letter symbols to be used in
             electrical technology - Part 2: Telecommunications and
             electronics", January 1999.
 [DSN]       Moore, K. and G. Vaudreuil, "An Extensible Message Format
             for Delivery Status Notifications", RFC 3464, January
             2003.
 [FLAMES]    Borenstein, N, and C. Thyberg, "Power, Ease of Use, and
             Cooperative Work in a Practical Multimedia Message
             System", Int. J.  of Man-Machine Studies, April, 1991.
             Reprinted in Computer-Supported Cooperative Work and
             Groupware, Saul Greenberg, editor, Harcourt Brace
             Jovanovich, 1991.  Reprinted in Readings in Groupware and
             Computer-Supported Cooperative Work, Ronald Baecker,
             editor, Morgan Kaufmann, 1993.
 [IMAP]      Crispin, M., "Internet Message Access Protocol - version
             4rev1", RFC 3501, March 2003.
 [MDN]       Hansen, T., Ed., and G. Vaudreuil, Ed., "Message
             Disposition Notification", RFC 3798, May 2004.
 [RFC3028]   Showalter, T., "Sieve: A Mail Filtering Language", RFC
             3028, January 2001.

Guenther & Showalter Standards Track [Page 40] RFC 5228 Sieve: An Email Filtering Language January 2008

14. Changes from RFC 3028

 This following list is a summary of the changes that have been made
 in the Sieve language base specification from [RFC3028].
  1. Removed ban on tests having side-effects
  2. Removed reject extension (will be specified in a separate RFC)
  3. Clarified description of comparators to match [COLLATION], the
     new base specification for them
  4. Require stripping of leading and trailing whitespace in "header"
     test
  5. Clarified or tightened handling of many minor items, including:
     - invalid [MIME3] encoding
     - invalid addresses in headers
     - invalid header field names in tests
     - 'undefined' comparator result
     - unknown envelope parts
     - null return-path in "envelope" test
  6. Capability strings are case-sensitive
  7. Clarified that fileinto should reencode non-ASCII mailbox
     names to match the mailstore's conventions
  8. Errors in the ABNF were corrected
  9. The references were updated and split into normative and
     informative
 10. Added encoded-character capability and deprecated (but did not
     remove) use of arbitrary binary octets in Sieve scripts.
 11. Updated IANA registration template, and added IANA
     considerations to permit capability prefix registrations.
 12. Added .sieve as a valid extension for Sieve scripts.

Editors' Addresses

 Philip Guenther
 Sendmail, Inc.
 6425 Christie St. Ste 400
 Emeryville, CA 94608
 EMail: guenther@sendmail.com
 Tim Showalter
 EMail: tjs@psaux.com

Guenther & Showalter Standards Track [Page 41] RFC 5228 Sieve: An Email Filtering Language January 2008

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.

Guenther & Showalter Standards Track [Page 42]

/data/webs/external/dokuwiki/data/pages/rfc/rfc5228.txt · Last modified: 2008/01/07 16:57 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki