How filters work

Module 6: Automatic: filters and out-of-office · Reading time: 10 minutes

Learning objective: After this lesson you can explain where and when filters run, read a filter script in Sieve and predict which folder an incoming message ends up in.

Key concepts: filter, Sieve, ManageSieve, filter set, rule, condition, action, implicit keep, stop, contains, is equal to, matches expression

Filters run on the server

A filter sorts your mail automatically: mail with "invoice" in the subject goes to the Invoices folder, newsletters go to a folder of their own. The most important thing to know: this sorting does not happen in the webmail but on the mail server, at the moment a message is delivered to your mailbox.

Three things follow from this:

Filters also work when the webmail is closed. Your laptop can be switched off. Your phone sees the mail in the right folder straight away.
Filters only work on new mail. Mail that is already in your mailbox stays where it is. If you create a filter today, you move the old messages yourself.
Filters apply to one mailbox. Each mailbox has its own filters. If you want to arrange something for all the mailboxes on your domain, such as blocking a sender, you do that in your hosting control panel.

Filters are written in Sieve, a simple language made especially for filtering mail (RFC 5228). The WebOké mail server uses Dovecot with Pigeonhole, Dovecot's implementation of Sieve. The webmail turns your choices in the form into a Sieve script and sends it to the server using the ManageSieve protocol (RFC 5804). You don't need to write Sieve, but if you can read it, you understand exactly what your filters do.

Filter set, rules, conditions and actions

A filter set is the complete script: all the filters of your mailbox in one file. You can have several filter sets, but only one is ever active.

The filter set contains the filters, also called rules in the webmail. Each filter has:

a name, just for you;
a scope: the message must match all rules, any of the rules, or the filter applies to all messages;
one or more conditions: where the filter looks (subject, sender, another header), how it compares, and with which text;
one or more actions: what happens when the conditions are met.

There are three ways to compare:

In the webmail	In Sieve	Meaning
contains	`:contains`	the text appears somewhere in the header
is equal to	`:is`	the header is exactly this text
matches expression	`:matches`	pattern with `*` (zero or more characters) and `?` (exactly one character)

Upper and lower case make no difference with any of the three. By default Sieve compares using the i;ascii-casemap comparator, which treats upper-case and lower-case letters as equal. So "invoice" also finds "INVOICE" and "Invoice".

What a filter set looks like

In the webmail you can view the filter set as text with Filters > Actions > Edit filter set. An example as the webmail writes it:

require ["fileinto"];
# rule:[Newsletters]
if exists "List-Id"
{
	fileinto "Newsletters";
	stop;
}
# rule:[Invoices]
if allof (header :contains "subject" "invoice")
{
	fileinto "Invoices";
}
# rule:[Colleague Tom]
if false # header :contains "from" "tom@example.com"
{
	fileinto "INBOX.Team";
}

Line by line:

require ["fileinto"]; asks the server for the extension needed to move a message to a folder. The webmail adds this at the top itself, with every extension the script uses.
# rule:[Newsletters] is a comment. The webmail uses it to recognise the name of your filter. The server skips the line.
if exists "List-Id" is the condition: the message has a List-Id header. Newsletters and mailing lists have one (RFC 2919).
fileinto "Newsletters"; moves the message to the Newsletters folder. The folder name is the full name on the server, with the dot as separator (lesson 5.1). So a folder under Inbox is called INBOX.Team.
stop; stops the whole script. Later filters no longer look at this message. In the webmail this action is called Stop evaluating rules.
if false # ... is a disabled filter. If you switch off Filter enabled, the webmail turns the condition into false: never true. The old condition stays as a comment, so you can switch it back on later.

The Sieve script of the filter set in Edit filter set — Your filters as the server reads them: a Sieve script

From top to bottom

The server reads the script from top to bottom and checks each filter. Three rules apply.

1. Without an action, the message stays in the Inbox. Sieve has implicit keep (RFC 5228, section 2.10.2): if no filter does anything, the message simply lands in the Inbox.

2. After a move, the message is not also in the Inbox. A fileinto cancels the implicit keep. The message goes to the chosen folder and not to the Inbox as well. If you do want both, use Copy message to.

3. Without stop, the next filters look too. If stop is missing, the server carries on with the next filter. If that filter also matches, the server carries out that action too. Two moves to two folders means the message ends up in both folders. With stop, the first matching filter decides.

That is why the order matters. In the example above, Newsletters is above Invoices, with a stop. So a newsletter with "Your invoice" in the subject goes to Newsletters and not to Invoices. If you reverse the order, that same newsletter lands in Invoices, because that filter has no stop and now comes first. The newsletter would even end up in both folders. So put the most specific filters at the top and give them a stop.

Creating a filter in webmail 1:08

Walking through a message: how to predict it

Take a message and walk through the script the way the server does:

Start at the first filter. Is it disabled (if false)? Skip it.
Is the condition met? Look closely at the header: subject is the subject, from the sender with name and address, to the recipient.
If so: carry out the actions. If there is a stop, you are done.
If not, or there is no stop: go to the next filter.
At the end: if no filter has moved or deleted the message, it is in the Inbox (INBOX).

With these five steps you can read any script, even a long one.

In practice: how it works in the webmail

You find filters under Settings > Filters. The list shows your filters in the order in which the server runs them; drag them to change the order. Under Actions you find Edit filter set: there you can view and change the script as text. The steps for a new filter are in the Roundcube manual under Creating a filter. Other webmail works in a similar way: Gmail has filters, Outlook.com has rules. They don't use Sieve, but order and stopping matter there too.

Summary

Filters run on the mail server on delivery, so also when the webmail is closed, and only on new mail.
The webmail writes your filters as a Sieve script (RFC 5228) and puts it on the server using ManageSieve.
Contains, is equal to and matches expression are not case-sensitive by default.
If no filter does anything, the message stays in the Inbox; after a move, it is not also in the Inbox.
Filters run from top to bottom; stop ends the script, so the order determines the result.

Quiz

Exercise

Exercise A6.1: Where does this email end up? Open the material filters-1.txt, a filter set as the webmail writes it, and berichten-1.txt, with the headers of four incoming messages, numbered 1 to 4. Walk through each message using the five steps from this lesson: from top to bottom, skip disabled filters, watch out for stop. For each message, enter the name of the folder where it ends up, exactly as it appears in the script; if the message lands in the Inbox, enter INBOX. The program compares your four answers with the answer key and shows for each message which filter decided the outcome.

Cookies at WebOké

Cookie settings

Necessary

Marketing