GNU Mailutils Manual (split by section):   Section:   Chapter:FastBack: Sieve Language   Up: Sieve Language   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.2 Syntax

Being designed for the sole purpose of filtering mail, Sieve has a very simple syntax.

5.2.1 Commands

The basic syntax element is a command. It is defined as follows:

command-name [tags] args

where command-name is an identifier representing the name of the command, tags is an optional list of optional or tagged arguments and args is a list of required or positional arguments.

Positional arguments are literals delimited with whitespace. They provide the command with the information necessary to its proper functioning. Each command has a fixed number of positional arguments. It is an error to supply more arguments to the command or to give it fewer arguments than it accepts.

Optional arguments allow to modify the behaviour of the command, like command line options in UNIX do. They are a list of tags (see Lexical Structure) separated by whitespace. An optional argument may have at most one parameter.

Each command understands a set of optional arguments. Supplying it tags that it does not understand results in an error.

For example, consider the following command

header :mime :comparator "i;octet" ["to", "from"] "bug-mailutils@gnu.org"

Here, given that header takes two positional arguments: header is command name, the list ["to", "from"] is first positional argument and the string "bug-mailutils@gnu.org" is second positional argument. There are two optional arguments: :mime and :comparator. The latter has a string "i;octet" as its parameter.

5.2.2 Actions Described

An action is a Sieve command that performs some operation over a message. Actions do the main job in any Sieve program. Syntactically, an action is a command terminated with semicolon, e.g.:

keep;

fileinto "mbox";

GNU Sieve provides the full set of actions described in RFC 3028. It also allows to extend this set using loadable actions. See Actions, for detailed discussion of actions.

5.2.3 Control Flow

The only control flow statement Sieve has is if statement. In its simplest form it is:

if condition { … }

The effect of this statement is that the sequence of actions between the curly braces is executed only if the condition evaluates to true.

A more elaborate form of this statement allows to execute two different sets of actions depending on whether the condition is true or not:

if condition { … } else { … }

The most advanced form of the “if” statement allows to select an action depending on what condition from the set of conditions is met.

if cond1 { … } elsif cond2 { … } else { … }

There may be any number of “elsif” branches in an “if” statement. However it may have at most one “else” branch. Notes for C programmers:

  1. The braces surrounding each branch of an “if” statement are required.
  2. The “else if” construct is disallowed. Use “elsif” keyword instead.

Here’s an example of “if” statement:

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

The following section describes in detail conditions used in “if” statements.

5.2.4 Tests and Conditions

Tests are Sieve commands that return boolean value. E.g. the test

header :contains "from" "coyote"

returns true only if the header “From” of the current message contains substring “coyote”.

The tests shipped with the GNU Sieve are described in Tests.

Condition is a Sieve expression that evaluates to true or false. In its simplest form, condition is just a Sieve test.

To reverse the sense of a condition use keyword not, e.g.:

not header :contains "from" "coyote"

The results of several conditions may be joined together by logical and and or operations. The special form allof takes several tests as its arguments and computes the logical and of their results. Similarly, the form anyof performs logical or over the results of its arguments. E.g.:

if anyof (not exists ["From", "Date"],
          header :contains "from" "fool@example.edu")
  {
    discard;
  }

GNU Mailutils Manual (split by section):   Section:   Chapter:FastBack: Sieve Language   Up: Syntax   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index