Filtering email with Sieve

Sieve allows you to filter your mail on the server. This means that your rules will be applied to your mail regardless of where you view it (e.g. if you use webmail at home, the filtering will still be applied to your account).

• Introduction
• Installing a Sieve script
• Developing Sieve scripts
• Examples
  • Example 1 - Deleting Spam
  • Example 2 - Filtering Spam
  • Example 3 - Vacation messages
  • Example 4 - Locally scoped vacation messages
  • Example 5 - General filtering example
• The Interactive Sieve Program
• Appendix 1 - Brief technical overview
• Links

1. Introduction

Sieve is a proposed internet-standard language for filtering mail at the time of final delivery. It is a server-side filtering mechanism. It is officially documented at RFC3028.

Sieve is a language that can be used to create filters for electronic mail. Based on a series of matching rules that work from the message headers, Sieve scripts can discard mail, redirect the message to another address or file mail into a specific folder. The Cyrus IMAP server used at the University of Bath enables server-side mail filtering.

To get an understanding of this it has to be contrasted with client-side filtering. Most modern email reading, or client, software facilitates the creation of filtering rules. These are triggered when the user launches the mail reading program and logs onto the email server. The client program has to be running and the user has to be logged into the server for the rules to be obeyed. Client-side filtering has its uses but is severely constrained. For example, the concept of vacation mail is infeasible with client-side filtering. With server-side filtering, vacation mail is possible and your filtering rules take effect regardless of which machine or mail reader you use or whether you are logged into the server.

Users can write one or more scripts and install them on the IMAP server using the command sieve which is available on User Service Machines. The Mulberry email client can also be used to write and upload Sieve scripts. See Developing Sieve scripts with Mulberry for more information.

2. Installing a Sieve Script

Write your Sieve script, or scripts, using any tools you like. You can use the example templates below or write from scratch using your favorite text editor. If using the Mulberry Graphical User Interface (GUI) to develop Sieve scripts please refer to Developing Sieve scripts with Mulberry for instructions.

If writing from scratch the working directory is the .sieve (dot sieve) directory directly off your home directory. Store your sieve scripts in this .sieve directory. Give them names like normal or vacation.

Log on to a User Service Machine. Change to your .sieve directory where your scripts are kept. If you don't already have a .sieve directory or folder create one. Upload your script to the IMAP server using the interactive sieve command:

amos [~] $ sieve connecting to imaphost.bath.ac.uk

help - this screen list - list scripts on server put <filename> - upload script to server get <name> [<filename>] - get script. If no filename display to screen delete <name> - delete script. activate <name> - set a script as the active script deactivate - deactivate all scripts quit - quit >>>

From the prompt you can put your script onto the server, put xxx, activate your script, activate xxx, or list your scripts, list. xxx being the actual name of your script. Note that although you may have up to five scripts installed on the IMAP server only one may be active at any one time. Using the list command will display your uploaded scripts and their status - eg:

>>> list forwardmail newrbl <- active script nospam spam vacation 

In this case the script called 'newrbl' is the active script.

3. Developing Sieve scripts

Sieve scripts are just a series of instructions written in plain text which tell the Sieve engine what to do with your incoming email. Although designed to be simple to use Sieve scripting is a programming language so to gain effective use of it familiarity with basic programming code and concepts is required. Those who attempt to develop and use a Sieve script from scratch, should be familiar with basic scripting and with Sieve specifically. See Appendix 1 for more information.

For those wishing to implement specific filters there are commands available for installing spam scripts and vacation scripts.

4. Examples

Some examples will offer a brief overview of the Sieve scripting language:

Example 1: This sieve script will silently discard most spam. This is the script that is installed by running the nospam command.

if exists "X-RBL-Warning" { discard; stop; } if exists "X-Spam-Flag" { discard; stop; }
 

Example 2: This script will filter most spam to a mail folder called spam. This is the script that is installed by running the filterspam command. Note the mandatory declaration require "fileinto" required for all local mailbox filtering operations.

require "fileinto"; if exists "X-RBL-Warning" { fileinto "INBOX.spam"; stop; }

if exists "X-Spam-Flag" { fileinto "INBOX.spam"; stop; }
 

Example 3: This script will send automatic replies to anyone who emails you. It is a vacation script. This is the script installed when you run the startvacn script. The mandatory declaration require "vacation" is required for vacation scripts as this is an extension to the standard language specification.

require "vacation";

vacation :addresses [ "[email protected]", "[email protected]"] text: Sorry, I am away. I will attend to your request upon my return. . ;

Example 4: This script will install a vacation script which only replies to email send from local bath addresses. It is installed when you run the startvacn -b command.

require "vacation"

if address :contains :domain "from" "bath.ac.uk"{ vacation :addresses [ "[email protected]", "[email protected]"] text: Hi, I'm away until next week. I'll answer mail on my return . ; }

Example 5: This script will filter email into various local mail folders. The folders MUST exist. In this example comments are on lines starting with a #. The sieve engine ignores all comments.

require "fileinto";
 # # Circle MUD mailing list list # All mail from the list has "[CIRCLE]" in the subject
# Place all these in the "Circle List" folder
# 
if header :contains "Subject" "[CIRCLE]" { fileinto "INBOX.Circle List"; }
 #
# "shockwave" e-mail virus - just reject it
#
if header :contains "Subject" "A great Shockwave flash movie" { discard; }
 #
# Get a lot of junk from dial-up uu.net accounts
# move to spam folder for review pending deletion if header :contains "Received" ".da.uu.net" { fileinto "INBOX.spam"; }
 #
# If the mail is listed as TO someone at bigfoot.com
# Then just discard it because it's spam (my experience anyway)
#
if header :contains "To" "@bigfoot.com" {
 discard;
}
 #
# If the mail has a blank to or from line move to the spam folder
# #
if header :is ["To", "From"] [""] {
 fileinto "INBOX.spam";
 # # Everything that makes it to here ends up in the INBOX # End of the script

The Interactive Sieve Program

The interactive sieve command

The commands for uploading and manipulating the status of sieve scripts are available by using the sieve program on one of the User Service Machines. The program can be executed in two modes - interactive and execute mode.

Note - the working directory for the sieve program is .sieve located off your home directory

Interactive

You start by the typing:

sieve

If you are prompted for a password enter your usual password.

The following menu will be presented:

(h)elp - this screen (l)ist - list scripts on server (p)ut <filename> - upload script to server (g)et <name> [<filename>] - get script. If no filename display to screen (d)elete <name> - delete script (a)ctivate <name> - set a script as the active script deactivate - deactivate all scripts (q)uit - quit >>>

Parenthesized initial letters indicate shortcut commands so that single letter will issue the command.

At the prompt, >>>, you can do the following:

In all cases replace script with the name of your script.

Execute

Execute mode allows you to execute the command of your choice by providing it as an argument to the sieve program. You tell sieve to operate in execute mode by using the -e switch. If you are prompted for a password enter your usual password. For example to list your sieve scripts on the server you can run:

sieve -e list

or

sieve -e l

If the command you want to run includes a space as the put, get, delete and activate commands do enclose in quotes. Single or double quotes will both work. For example:

sieve -e "put script"

or

sieve -e "p script"

where script is the name of your script will upload your script to the IMAP server. The other commands work in exactly the same way. Running sieve -e without an argument will take you to interactive mode.

Appendix 1

What Sieve is

Sieve is a language that can be used to create filters for electronic mail. Sieve is officially documented in RFC3028. It is not tied to any particular operating system or mail architecture. It requires the use of RFC822-compliant messages, but otherwise should generalize to other systems that meet these criteria.

The language is powerful enough to be useful, but limited in power in order to allow for a safe server-side filtering system. The intention is to make it impossible for users to do anything more complex (and dangerous) than write simple mail filters, along with facilitating GUI-based editors. The language is not Turing-complete, and provides no way to write a loop or a function. Variables are not provided.

Sieve is designed as a proposed Internet Standard, and design and development to date has followed Internet Engineering Task Force (IETF) procedures as described in RFC2026. The Sieve RFC is RFC3028

Because of the expectation that users will make use of filtering if it is offered and easy to use, this language has been made simple enough to allow many users to make use of it, but rich enough that it can be used productively. However, it is expected that GUI-based editors will be the preferred way of editing filters for most users.

Sieve is a proposed internet-standard language for filtering mail at the time of final delivery.

What Sieve is not

• Sieve is simply a specialised standard filtering language.
• Sieve is not intended to be the latest and greatest instance of a complete programming language.
• Sieve is not particularly intended to be useful with filtering or processing anything other than RFC822 messages.
• Sieve is not intended as a replacement for any particular existing tools although its design is taken from the experience of use of many existing tools.
• While Sieve certainly doesn't provide the most sophisticated filtering syntax possible it does provide fundamental basics common to all RFC822 messages to establish a basic standard syntax for inter operation. It also provides for an extension mechanism to allow individual implementations to provide extended functionality within an open standards framework. As such Sieve is intended as a first stage building block for mail filters which can provide significant functionality for a large number of possible uses.
• Sieve purposely makes no comment on, or discussion of, the transport mechanism used by end users over which Sieve scripts might be moved. Possibilities are many and include file transfer, direct editing on a file system, HTTP, ACAP, LDAP and a number of other application-level transport methods. Sieve scripts are simply data for Sieve engines to execute.
• Sieve is not a once and for all solution for current problems addressed by filtering, such as anti-spam measures, although it is certainly intended to facilitate the construction of such solutions.

Links

• RFC 3028 Sieve: A Mail Filtering Language
• The Sieve home page at CyrusSoft.
• The Sieve Vacation extension draft RFC