[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Sieve Language

The input language understood by the GNU Sieve Library is a superset of the Sieve language as described in RFC 3028.

5.1 Lexical Structure  
5.2 Syntax  
5.3 Preprocessor  
5.4 Require Statement  
5.5 Comparators  
5.6 Tests  
5.7 Actions  
5.8 GNU Extensions  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.1 Lexical Structure

Whitespace and Comments

Comments are semantically equivalent to whitespace and can be used anyplace that whitespace is (with one exception in multi-line strings, as described below).

There are two kinds of comments: hash comments, that begin with a `#' character that is not contained within a string and continue until the next newline, and C-style or bracketed comments, that are delimited by `/*' and `*/' tokens. The bracketed comments may span multiple lines. E.g.:

 
if size :over 100K
  { # this is a comment
    discard;
  }
  
if size :over 100K
  { /* this is a comment
       this is still a comment */ discard /* this is a comment again
     */ ;
  }

Like in C, bracketed comments do not nest.

Lexical Tokens

The basic lexical entities are identifiers and literals.

An identifier is a sequence of letters, digits and underscores, started with a letter or underscore. For example, header and check_822_again are valid identifiers, whereas 1st is not. A special form of identifier is tag: it is an identifier prefixed with a colon (`:'), e.g.: :comparator.

A literal is a data that is not executed, merely evaluated "as is", to be used as arguments to commands. There are four kinds of literals:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.2 Syntax

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

5.2.1 Commands  
5.2.2 Actions Described  
5.2.3 Control Flow  
5.2.4 Tests and Conditions  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 section 5.1 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.2.2 Actions Described

An action is a Sieve command that performs some operation over the 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 section 5.7 Actions, for detailed discussion of actions.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 5.6 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;
  }

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3 Preprocessor

The preprocessor statements are a GNU extension to the Sieve language. The syntax for a preprocessor statement is similar to that used in C programming language, i.e.: a pound character (`#') followed by a preprocessor directive and its arguments. Any amount of whitespace can be inserted between the `#' and the directive. Currently implemented directives are include and searchpath.

Sieve #include directive  Include the contents of a file.
Sieve #searchpath directive  Modify the current search path.

Sieve #include directive

The #include directive reads in the contents of the given file. The contents is "inserted" into the text being parsed starting at the line where the directive appears. The directive takes two forms:

#include "filename"
The filename is taken relative to the current directory.

#include <filename>"
The filename is searched in the list of include directories as specified by the `-I' command line options.

If filename starts with a directory separator character (`/') both forms have the same effect.

Sieve #searchpath directive

The #searchpath directive adds its argument to the list of directories searched for loadable modules. It has the same effect as `-L' command line switch used by GNU sieve utility (see section 3.1.9 Sieve Specific Options).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4 Require Statement

 
Syntax:   require string;
          require string-list;

The require statement informs the parser that a script makes use of a certain extension. Multiple capabilities can be declared using the second form of the statement. The actual handling of a capability name depends on its suffix.

If the name starts with `comparator-', it is understood as a request to use the specified comparator. The comparator name consists of the characters following the suffix.

If the name starts with `test-', it means a request to use the given test. The test name consists of the characters following the suffix.

Otherwise, the capability is understood as a name of an action to be used.

The require statement, if present, must be used before any other statement that is using the required capability. As an extension, the GNU sieve allows the require and any other statements to be interspersed.

By default the following actions and comparators are always required:

Example:

 
require ["fileinto", "reject"];

require "fileinto";

require "comparator-i;ascii-numeric";

When processing arguments for require statement, GNU libsieve uses the following algorithm:

  1. Look up the name in a symbol table. If the name begins with `comparator-' it is looked up in the comparator table. If it begins with `test-', the test table is used instead. Otherwise the name is looked up in the action table.

  2. If the name is found, the search is terminated.

  3. Otherwise, transform the name. First, any `comparator-' or `test-' prefix is stripped. Then, any character other than alphanumeric characters, `.' and `,' is replaced with dash (`-'). The name thus obtained is used as a file name of an external loadable module.

  4. Try to load the module. The module is searched in the following search paths (in the order given):

    1. Mailutils module directory. By default it is `$prefix/lib/mailutils'.

    2. Sieve library path as given with the `-L' options in the command line

    3. Additional search directories specified with the #searchpath directive.

    4. The value of the environment variable LTDL_LIBRARY_PATH.

    5. System library search path: The system dependent library search path (e.g. on Linux it is set by the contents of the file `/etc/ld.so.conf' and the value of the environment variable LD_LIBRARY_PATH).

    The value of LTDL_LIBRARY_PATH and LD_LIBRARY_PATH must be a colon-separated list of absolute directories, for example, `"/usr/lib/mypkg:/lib/foo"'.

    In any of these directories, libsieve first attempts to find and load the given filename. If this fails, it tries to append the following suffixes to the file name:

    1. the libtool archive extension `.la'

    2. the extension used for native dynamic libraries on the host platform, e.g., `.so', `.sl', etc.

  5. If the module is found, libsieve executes its initialization function (see below) and again looks up the name in the symbol table. If found, search terminates successfully.

  6. If either the module is not found, or the symbol wasn't found after execution of the module initialization function, search is terminated with an error status. libsieve then issues the following diagnostic message:

     
    source for the required action NAME is not available
    


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.5 Comparators

GNU libsieve supports the following built-in comparators:

i;octet
This comparator simply compares the two arguments octet by octet

i;ascii-casemap
It treats uppercase and lowercase characters in the ASCII subset of UTF-8 as the same. This is the default comparator.

i;ascii-numeric
Treats the two arguments as ASCII representation of decimal numbers and compares their numeric values. This comparator must be explicitly required prior to use.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.6 Tests

This section describes the built-in tests supported by GNU libsieve. In the discussion below the following macro-notations are used:

match-type
This tag specifies the matching type to be used with the test. It can be one of the following:

:is
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. This is the default match-type.

:contains
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.

:matches
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 `*'.

:regex
The :regex version specifies a match using POSIX Extended Regular Expressions.

:value relation
The :value match type does a relational comparison between strings. Valid values for relation are:

"eq"
Equal

"ne"
Not Equal

"gt"
Greater Than

"ge"
Greater than or Equal

"lt"
Less Than

"le"
Less than or Equal

:count relation
This match type first determines the number of the specified entities (headers, addresses, etc.) in the message and does a relational comparison of the number of entities to the values specified in the test expression. The test expression must be a list of one element.

comparator
A comparator syntax item is defined as follows:

 
:comparator "comparator-name"
It instructs sieve to use the given comparator with the test. If comparator-name is not one of `i;octet', `i;ascii-casemap' it must be required prior to using it. For example:

 
require "comparator-i;ascii-numeric";

if header :comparator "i;ascii-numeric" :is "X-Num" "10"
  {
    ...

address-part
This syntax item is used when testing structured Internet addresses. It specifies which part of an address must be used in comparisons. Exactly one of the following tags may be used:

:all
Use the whole address. This is the default.

:localpart
Use local part of the address.

:domain
Use domain part of the address.

Notice, that match-type modifiers interact with comparators. Some comparators are not suitable for matching with :contains or :matches. If this occurs, sieve issues an appropriate error message. For example, the statement:

 
if header :matches :comparator "i;ascii-numeric"
would result in the following error message:

 
comparator `i;ascii-numeric' is incompatible with match type `:matches'
in call to `header'

Test: false

This test always evaluates to "false".

Test: true

This test always evaluates to "true".

Test: address [address-part][comparator][match-type] header-names key-list

Tagged arguments:

address-part
Selects the address part to compare. Default is the whole email address (:all).

comparator
Specifies the comparator to be used instead of the default i;ascii-casemap.

match-type
Specifies the match type to be used instead of the default :is.
Required arguments:

header-names
A list of header names.

key-list
A list of address values.

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 comparator and match-type optional arguments.

This test returns true if any combination of the header-names and key-list arguments match.

The address primitive never acts on the phrase part of an email address, nor on comments within that address. Use the header test instead. It also never acts on group names, although it does act on the addresses within the group construct.

Example:

 
if address :is :all "from" "tim@example.com"
  {
     discard;
  } 

Test: size [:over|:under] number

The size test deals with the size of a message. The required argument number represents the size of the message in bytes. It may be suffixed with the following quantifiers:

`k'
`K'
The number is expressed in kilobytes.
`m'
`M'
The number is expressed in megabytes.
`g'
`G'
The number is expressed in gigabytes.

If the tagged argument is `:over', and the size of the message is greater than number, the test is true; otherwise, it is false.

If the argument is `:under', and the size of the message is less than the number, the test is true; otherwise, it is false.

Otherwise, the test is true only if the size of the message equals exactly number. This is a GNU extension.

The size of a message is defined to be the number of octets from the initial header until the last character in the message body.

Test: envelope [address-part][comparator][match-type] envelope-part key-list

Tagged arguments:

address-part
Selects the address part to compare. Default is the whole email address (:all).

comparator
Specifies the comparator to be used instead of the default i;ascii-casemap.

match-type
Specifies the match type to be used instead of the default :is.
Required arguments:

envelope-parts
A list of envelope parts to operate upon.

key-list
A list of address values.

The envelope test is true if the specified part of the SMTP envelope matches the specified key.

If the envelope-part strings is (case insensitive) `from', then matching occurs against the FROM address used in the SMTP MAIL command.

Notice, that due to the limitations imposed by SMTP envelope structure the use of any other values in envelope-parts header is meaningless.

Test: exists header-names

Required arguments:

header-names
List of message header names.

The exists test is true if the headers listed in 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:

 
if not exists ["From","Date"]
  {
     discard;
  }

Test: header [comparator] [match-type] [:mime] header-names key-list
Tagged arguments:

comparator
Specifies the comparator to be used instead of the default i;ascii-casemap.

match-type
Specifies the match type to be used instead of the default :is.

:mime
This tag instructs header to search through the mime headers in multipart messages as well.

Required arguments:

header-names
A list of header names.

key-list
A list of header values.
The header test evaluates to true if any header name matches any key. The type of match is specified by the optional match argument, which defaults to ":is" if not explicitly given.

The test returns true if any combination of the header-names and key-list arguments match.

If a header listed in header-names exists, it contains the null key (`""'). However, if the named header is not present, it does not contain the null 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

Test: numaddr [:over|:under] header-names number
This test is provided as an example of loadable extension tests. You must use `require "test-numaddr"' statement before actually using it.

The numaddr test counts Internet addresses in structured headers that contain addresses. It returns true if the total number of addresses satisfies the requested relation.

If the tagged argument is `:over' and the number of addresses is greater than number, the test is true; otherwise, it is false.

If the tagged argument is `:under' and the number of addresses is less than number, the test is true; otherwise, it is false.

If the tagged argument is not given, `:over' is assumed.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.7 Actions

The GNU libsieve supports the following default actions:

Among them the first three actions do not need to be explicitly required by a require statement, while the others do.

These actions are described in detail below.

Action: stop

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

Action: keep

The effect of this action is to preserve the current message in the mailbox. This action is executed if no other action has been executed.

Action: discard

Discard silently throws away the current message. No notification is returned to the sender, the message is deleted from the mailbox.

Example:

 
if header :contains ["from"] ["idiot@example.edu"]
  {
    discard;
  }

Action: fileinto folder

Required arguments:

folder
A string representing the folder name

The fileinto action delivers the message into the specified folder.

Action: reject reason

The optional reject action refuses delivery of a message by sending back a message delivery notification to the sender. It resends the message to the sender, wrapping it in a "reject" form, noting that it was rejected by the recipient. The required argument reason is a string specifying the reason for rejecting the message.

Example:

If the message contained

 
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

I've got some great birdseed over here at my place.
Want to buy it?
and the user's script contained:

 
if header :contains "from" "coyote@desert.example.org"
  {
    reject "I am not taking mail from you, and I don't want
            your birdseed, either!";
  }
then the original sender <coyote@desert.example.org> would receive the following notification:

 
To: <coyote@desert.example.org>
X-Authentication-Warning: roadrunner set sender using -f flag
Content-Type: multipart/mixed; boundary=----- =_aaaaaaaaaa0
MIME-Version: 1.0
----- =_aaaaaaaaaa0
The original message was received at
Tue, 1 Apr 1997 09:07:15 -0800 from
coyote@desert.example.org.
Message was refused by recipient's mail filtering program.
Reason given was as follows:

I am not taking mail from you, and I don't want your birdseed, either!

----- =_aaaaaaaaaa0
Content-Type: message/delivery-status

Reporting-UA: sieve; GNU Mailutils 0.1.3
Arrival-Date: Tue, 1 Apr 1997 09:07:15 -0800
Final-Recipient: RFC822; roadrunner@acme.example.com
Action: deleted
Disposition: automatic-action/MDN-sent-automatically;deleted
Last-Attempt-Date: Tue, 1 Apr 1997 09:07:15 -0800

----- =_aaaaaaaaaa0
Content-Type: message/rfc822

From: coyote@desert.example.org
To: roadrunner@acme.example.com
Subject: I have a present for you

I've got some great birdseed over here at my place.
Want to buy it?
----- =_aaaaaaaaaa0

If the reason argument is rather long, the common approach is to use the combination of the text: and #include keywords, e.g.:

 
if header :mime :matches "Content-Type"
          [ "*application/msword;*", "*audio/x-midi*" ]
  {
    reject text:
#include "nomsword.txt"
    .
    ;
  }

Action: redirect address

The redirect action is used to send the message to another user at a supplied address, as a mail forwarding feature does. This action makes no changes to the message body or existing headers, but it may add new headers. It also modifies the envelope recipient.

The redirect command performs an MTA-style "forward" -- that is, what you get from a `.forward' file using sendmail under UNIX. The address on the SMTP envelope is replaced with the one on the redirect command and the message is sent back out. Notice, that it differs from the MUA-style forward, which creates a new message with a different sender and message ID, wrapping the old message in a new one.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.8 GNU Extensions

This section summarizes the GNU extensions to the sieve language

  1. Multiline strings syntax

    GNU libsieve understands the following multiline string syntax:

     
    text:[-][delimiter]
    ....
    delimiter
    

    The meaning of optional flags is the same as in shell "here document" construct: the dash strips all leading tab characters from the string body, thus allowing it to be indented in a natural fashion; delimiter introduces the new end-of-text delimiter instead of the default dot. If delimiter starts with a backslash, no preprocessing will be performed within a string.

  2. Handling of the require statement.

  3. header test

    The header takes an optional argument :mime, meaning to scan the headers from each part of a multipart message.

  4. size test

    The size test allows to omit the optional argument (:over|:under). In this case exact equality is assumed.

  5. envelope test

    The only value that can be meaningfully used as the first required argument of an envelope test is `from'. This limitation may disappear from the subsequent releases.

  6. Match type optional argument.

    Along with the usual :is, :matches and contains matching type, GNU sieve library understands :regex type. This matching type toggles POSIX Extended Regular Expression matching.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Jordi Mallach on April, 16 2004 using texi2html