How to use Sieve

This tutorial will cover the very basics of the powerful Sieve Filtering Language. Sieve is an email filtering language. A Sieve script has a set of rules, each one forming a test, and a set of instructions.

Each incoming email is checked against each rule: if the test matches, the instructions are performed on that message.

Most filtering can be done by our built-in Rules, but Sieve script is available for more complex situations.


Definitions

Getting started

The syntax of the Sieve language is quite simple:

if <condition> {
    action1;
    action2;
    ...
 }
  1. The <condition> has:

    • The part of the email you want to test (body, header, envelope) AND
    • The test you want to do against that part to perform the required actions.
  2. The actions: what you want to do to the email (discard, reject, redirect, fileinto, stop, keep).

In order to learn how to write your own Sieve scripts, it's a good idea to first learn how to read a Sieve script. We automatically generate Sieve for your account already, for things like Rules and Spam Protection. To view this Sieve code yourself, go to Settings → Rules and click on Edit custom Sieve code. Look through the automatically generated code and see if you recognize items from your Rules.

Let's take a size filter as an example:

if size :over 1024K {
  reject "Message not delivered; size over limit accepted by recipient";
  stop;
}

Examining this step by step:

if size :over 1024K {

Here is where you set the test condition for this rule. If this condition is met, the action is performed; if not, the script continues until it hits a rule that does match. In this case, it tests if the size of the email being received is larger than 1024 kilobytes (1 megabyte, or about 13,000 lines of unformatted text).

reject "Message ... recipient";

This is the action of the rule. The command 'reject' rejects a message, with the text given between the quotes. Notice the ';' at the end: it's necessary on any line that performs an action. Important: your script won't work if you forget it.

stop;

This action tells the Sieve engine to stop here, without checking for more rules. No further action is needed here, since the message has already been rejected, and we don't want to keep a copy of it. In some cases, it's important to use a 'stop' explicitly, otherwise it will continue, find another action and perform that as well. This is one of the first things to check when emails are delivered to two of your folders.

}

This closing cury-bracket ends the rule.

Writing your own script

There's a good Sieve reference online which describes the components which make up a script. Additional information is given below.

Tests

Comparators

A comparator is something you use to compare a field with a certain value. Keep in mind that a comparator always starts with a colon, the ':' character.

Language Constructs

A script has a certain structure. You need a way to indicate such a structure, so there are some building blocks for that too. These are called "Language Constructs".

Actions

Comments

Comments are recommended for keeping track of why a specific rule was written, as it may be hard to remember after some time has passed. Comments can't be started in the middle of strings.

Example Script

Here is a basic example of what a Sieve script might look like. Fastmail's automatically generated Sieve might look slightly different. This script demonstrates the use of actions, if, elsif, and else tools.

/*
   Example last updated:
   2019-06-13
*/
require ["fileinto", "reject", "vacation", "regex", "relational", "comparator-i;ascii-numeric"];

if a :matches b {
  Do W; #an action
  stop;
}
elsif a :matches c {
  Do X;
  stop;
}
elsif a :matches d {
  Do Y;
  stop;
}
else {       # Nothing matches, put it into the Undecided folder and stop
  fileinto "INBOX.Undecided";
  stop;
}

Testing

There's two ways to test:

  1. Save your Sieve script changes and send yourself emails to test the various clauses. Inefficient particularly if you want to test matches against external senders, or against generated headers.
  2. Use the Sieve testing tool. Paste your full Sieve script and a raw message (this allows you to modify the headers to suit) to test the matches and actions in your script.