This page describes Claranet's server-side mail filters. This document was written by the author of the software, not by somebody who knows anything about writing documentation.
Server-side mail filters are a way of handling your email before it ever gets to your mail client. You can instruct the filters to forward mail, redirect it, bounce it, drop it and so on, based on criteria you set. It's quite useful for killing spam for example. As well as this page, which describes the filters in detail there is also a web insterface which is slightly more user-friendly but which does not offer all the features (link at the bottom).
You can use this page to create your .filter file. This file, if it exists, is read by the mail delivery agent and depending on it's contents, and the contents of the headers of the email, can either deliver, bounce, drop, forward or redirect the mail.
The file consists of a series of zero or more filter rules, one per line of the file. Blank lines or lines starting with # are ignored. Each line has four columns. The first two columns ('header' and 'pattern') are read by the delivery agent to determine whether the email is matched by this rule. The second two columns ('action' and 'arguments') are used to determine what action should be taken if a match is found.
The four columns are seperated by whitespace and the fourth column continues to the end of the line regardless of whitespace. If you want to include whitespace in the 'pattern' column you can do so by putting it into double quote marks (""). If you want to include quote marks in the pattern they should be preceded by a backslash (\).
The header column specifies the email header the delivery agent should examine, and the pattern columns specifies the contents to look for. The action column specifies the action to take on a match and the argument column, which is only required for some values of action, specifies extra information, for example the email address to forward the mail to.
For example:To foobar@steve\.clara\.co\.uk forward foobar@somewhereelse.com
This would instruct the filter engine to forward the all emails with 'foobar@steve.clara.co.uk' in the 'To' header to the address 'foobar@somewhereelse.com'.
The pattern column is a unix-style regular expresssion. In brief, each character matches itself except '.' which matches any character and * which means 'match any number of the preceding character (including zero)'. This explanation of regex's is simplified to an almost absurd degree but is probably enough information to make quite useful patterns. Here is a full description of the regex implementation in use.
For example:To foobar@ forward foobar@somewhereelse.com
This would match any email with a 'To' header with 'foobar@' in it. If you want a '.' to match only a '.' or a * to match only a '*' you should precede them with a backslash (\) as per the first example. In addition, you can tell the filter to match an email if the regex does not match by preceding the pattern with a bang (!). If the pattern is in quotes, the bang must be before the open quote.
The possible values for the action columns are:
deliver: normal deliveryIt is also possible to get logs of the mails which have been filtered. To do this you must include a line like this:
log [frequency] [address]The word 'log' tells the filter engine you want logs. The frequency is the number of days you want to elapse between getting the logs emailed to you. The address is the email address you want the logs sent to you. If you only want to log those mails which match a filter (as opposed to every mail that goes through the filter engine) you can use 'logmatches' instead of 'log'. You can also silence individual lines in the log by preceding the header with a '@'.
Here is an example .filter file with an explanation of each line:
# I want logs sent every week to steve@clara.net log 7 steve@clara.net # header pattern action arguments ... Subject "make money" drop From levine@clara\.net deliver @From levine@ bounce no likey levines X-RBL-Warning . drop To mobile@steve\.clara\.net forward steve@sms-service.co.uk To !steve\@clara\.net drop
Line one silently drops any mail with 'make money' anywhere in the subject line. Line two delivers normally any email from levine@clara.net which is the default action anyway, but it means I can safely do line 3 which bounces all mail from any other levines with the message 'no likey levines', without losing mail from levine@clara.net. The '@' sign in front of the header name means matches on that line dont go into the log. Line 4 drops any mail where the header 'X-RBL-Warning' appears (which is added if the sending site is listed in the MAPS Realtime Blacklist). Line 5 forwards a copy of all mail to mobile@steve.clara.net to steve@sms-service.co.uk. Line six drops any mail that does not have my email address in the To header.
If you dont understand this at all you might be better off using the nice pointy clicky interface which lets you specify filters without needing to get so involved in regular expressions and other such unpleasant things.