rfc3028.txt

RFC3028:Sieve: A Mail Filtering Language

   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 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




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


   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.

   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.  Blocks are
   supplied to commands so that the commands can implement control
   commands.

   A control structure is a command that happens to take a test and a
   block as one of its arguments; depending on the result of the test
   supplied as another argument, it runs the code in the block some
   number of times.

   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.  So there are two arguments, the test and the
   block.

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.



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


   A control command is similar, but it takes a test as an argument, and
   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 4.4) 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 will.

   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.

2.10.3.  Message Uniqueness in a Mailbox

   Implementations SHOULD NOT deliver a message to the same folder more
   than once, even if a script explicitly asks for a message to be
   written to a mailbox twice.



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


   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 numbers 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 prohibit more than one reject.

   Implementations MUST allow at least one keep or one fileinto.  If
   fileinto is not implemented, implementations MUST allow at least one
   keep.

   Implementations SHOULD prohibit reject when used with other actions.

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.

   If a script does not understand an extension declared with require,
   the script must not be used at all.  Implementations MUST NOT execute
   scripts which require unknown capability names.

   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.

         Experience with PostScript suggests that mechanisms that allow
         a script to work around missing extensions are not used in
         practice.

   Extensions which define actions MUST state how they interact with
   actions discussed in the base specification.







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


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 might even go so far as to ensure that scripts can
   never execute an invalid set of actions (e.g., reject + fileinto)
   before execution, although this could involve solving the Halting
   Problem.

   This specification allows any of these approaches.  Solving the
   Halting Problem is considered extra credit.

   When an error happens, implementations MUST notify the user that an
   error occurred, 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.

3.      Control Commands

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



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


3.1.     Control Structure 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 MUST only follow an if, and an else MUST follow only either an
   if or an elsif.  An error occurs if these conditions are not met.

   Syntax:   if <test1: test> <block1: block>

   Syntax:   elsif <test2: test> <block2: block>

   Syntax:   else <block>

   The semantics are similar to those of any of the many other
   programming languages these control commands 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 case.

   This provides a way of performing exactly one of the blocks in the
   chain.

   In the following example, both Message A and B are dropped.

   Example:  require "fileinto";
             if header :contains "from" "coyote" {
                discard;
             } elsif header :contains ["subject"] ["$$$"] {
                discard;
             } else {
                fileinto "INBOX";
             }


   When the script below is run over message A, it redirects the message
   to  [e-mail];  message B, to [e-mail]; any other
   message is redirected to [e-mail].






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


   Example:  if header :contains ["From"] ["coyote"] {
                redirect "[e-mail]";
             } elsif header :contains "Subject" "$$$" {
                redirect "[e-mail]";
             } else {
                redirect "[e-mail]";
             }

   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 Structure Require

   Syntax:   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 Structure Stop

   Syntax:   stop

   The "stop" action ends all processing.  If no actions have been
   executed, then the keep action is taken.

4.      Action Commands

   This document supplies five actions that may be taken on a message:
   keep, fileinto, redirect, reject, and discard.

   Implementations MUST support the "keep", "discard", and "redirect"
   actions.