rfc3028.txt

RFC3028:Sieve: A Mail Filtering Language

   quote within the string, respectively.

   No other characters should be escaped with a single 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").

   Non-printing characters such as tabs, CR and LF, and control
   characters are permitted in quoted strings.  Quoted strings MAY span
   multiple lines.  NUL (ASCII 0) is not allowed in strings.

   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.  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
   which 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 dot-stuffed;
   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.
   Implementations are encouraged to use short-circuit evaluation in
   these cases.



Showalter                   Standards Track                     [Page 7]

RFC 3028            Sieve: A Mail Filtering Language        January 2001


   For instance, the test `header :contains ["To", "Cc"]
   ["[e-mail]", "[e-mail]"]' is true if either the
   To header or Cc header of the input message contains either of the
   e-mail addresses "[e-mail]" or "[e-mail]".

   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] [RFC1123], 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.

   Folding of long header lines (as described in [IMAIL] 3.4.8) is
   removed prior to interpretation of the data.  The folding syntax (the
   CRLF that ends a line plus any leading whitespace at the beginning of
   the next line that indicates folding) are interpreted as if they were
   a single space.

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.  Using the symbols defined in [IMAIL], section 6.1, 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 used
   here.

   Implementations MUST ensure that the addresses are syntactically
   valid, but need not ensure that they actually identify an email
   recipient.





Showalter                   Standards Track                     [Page 8]

RFC 3028            Sieve: A Mail Filtering Language        January 2001


2.4.2.4. MIME Parts

   In a few places, [MIME] body parts are represented as strings.  These
   parts include MIME headers and the body.  This provides a way of
   embedding typed data within a Sieve script so that, among other
   things, character sets other than UTF-8 can be used for output
   messages.

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/else to
   decide which block of code is run.

   Tests MUST NOT have side effects.  That is, a test cannot affect the
   state of the filter or message.  No tests in this specification have
   side effects, and side effects are forbidden in extension tests as
   well.

   The rationale for this is that tests with side effects impair
   readability and maintainability and are difficult to represent in a
   graphic interface for generating scripts.  Side effects are confined
   to actions where they are clearer.

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.

   Example:  if anyof (not exists ["From", "Date"],
                   header :contains "from" "[e-mail]") {
                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.

2.6.1.   Positional Arguments

   Positional arguments are given to a command which 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.




Showalter                   Standards Track                     [Page 9]

RFC 3028            Sieve: A Mail Filtering Language        January 2001


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 numbers or strings 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
   with commands, but they still may be reordered arbitrarily provided
   they appear before positional arguments.  Tagged arguments may be
   mixed with optional arguments.

   To simplify this specification, 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 [ACAP] comparator will be used to
   compare two strings, since different languages may impose different
   orderings on UTF-8 [UTF-8] characters.

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 9.2 presents a parsable version of this:
   Arguments are string-lists, numbers, and tags, which may be followed



Showalter                   Standards Track                    [Page 10]

RFC 3028            Sieve: A Mail Filtering Language        January 2001


   by a test or a test-list, which may be followed by a block of
   commands.  No more than one test or test list, nor more than one
   block of commands, may be used, and commands that end with blocks 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 borrows ACAP's comparator registry.

   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

   There are three match types describing the matching used in this
   specification:  ":is", ":contains", and ":matches".  Match type
   arguments are supplied to those commands which allow them to specify
   what kind of match is to be performed.

   These are used as tagged arguments to tests that perform string
   comparison.

   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 null 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 null key ":is" and only ":is" the null value.

   The ":matches" version specifies a wildcard match using the
   characters "*" and "?".  "*" matches zero or more characters, and "?"
   matches a single character.  "?" 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.



Showalter                   Standards Track                    [Page 11]

RFC 3028            Sieve: A Mail Filtering Language        January 2001


   In order to specify what type of match is supposed to happen,
   commands that support matching take optional tagged arguments
   ":matches", ":is", and ":contains".  Commands default to using ":is"
   matching if no match type argument is supplied.  Note that these
   modifiers may interact with comparators; in particular, some
   comparators are not 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.

   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

   All Sieve scripts are represented in UTF-8, but messages may involve
   a number of character sets.  In order for comparisons to work across
   character sets, implementations SHOULD implement the following
   behavior:

      Implementations decode header charsets to UTF-8.  Two strings are
      considered equal if their UTF-8 representations are identical.
      Implementations should decode charsets represented in the forms
      specified by [MIME] for both message headers and bodies.
      Implementations must be capable of decoding US-ASCII, ISO-8859-1,
      the ASCII subset of ISO-8859-* character sets, and UTF-8.

   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.  Comparators
   are described for [ACAP]; a registry is defined for ACAP, and this
   specification uses that registry.

   ACAP defines multiple comparator types.  Only equality types are used
   in this specification.





Showalter                   Standards Track                    [Page 12]

RFC 3028            Sieve: A Mail Filtering Language        January 2001


   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 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 and use a
   comparator with ":matches" or ":contains" that is not compatible with
   it.

   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.