Site People (by surname)

• ITS home
• Help
• Services
• My IT account
• About

Setting up simple email filtering with My Accounts

Server-side filtering is a means of processing incoming email before delivery. It can be set up on the central mail server, using the My Accounts web page. On the Sussex system, this is done under the control of the Exim mail system which handles all the University's email traffic.

• Why use server-side filtering?
• GETTING STARTED
• The Expert Mode page
• How to enter filtering commands
• Some examples:
  • Discarding Messages From A Specific Address
  • Discarding Messages From A Specific Domain
  • Discarding Messages With Specific Key Words In The Subject
  • Combining Test Conditions
• Table of 'if' test conditions
• Filtering spam
• Filtering using other message headers
• Diverting email to named mail folders
• Forwarding email together with filtering
• Sending autoreplies together with filtering
• Keeping your filter commands up to date
• What to do if it doesn't work
• Switching off filtering
• Where to find out more

Why use server-side filtering?

Although most email clients (programs such as Mulberry, Outlook, Thunderbird and so on that you might use to work with email) are capable of doing their own filtering, there are at least three advantages of using the server instead:

• You only have to set it up once, even if you read your email from different computers in different places.
• Your incoming messages will be filtered without you needing to log in to your email account.
• The email doesn't have to be downloaded to your computer before filtering.

Limitations of server-side filtering at Sussex

The server-side filtering facilities offered at Sussex are limited in their scope. The filtering takes place before email reaches your mailstore, and because of this, you will not be able to use any filtering commands that refer to your mail folders, except perhaps by means of plus-addressing, which is described below in the section Diverting email to named mail folders.

Otherwise, server-side filtering is restricted to diverting (forwarding) email elsewhere, or discarding email altogether. We therefore recommend you only use server-side filtering for handling spam or for discarding other unwanted email. To use a filter to file email into mail folders you should first try your mail client's filtering facilities, such as Mulberry's Local Rules facility, which is documented elsewhere.

GETTING STARTED

First you need to log-on to the My Accounts facility:

1. Double-click the My Accounts icon on the IT Services desktop, or point your web browser at www.sussex.ac.uk/myaccounts/).
2. Enter your username and password in the boxes provided.
3. Click on Set Mail Options.
   You should see two options on view: Mail Forwarding, and further down, Vacation Messages.
4. Now scroll to the bottom of the page and click the Expert Mode button.

PLEASE NOTE that after clicking the Expert Mode button, any changes you make will be lost if you subsequently switch back to Easy Mode.

The Expert Mode page

When you click the Expert Mode button, you'll be shown a page with a text box into which you'll enter your filtering commands. The box has a title above it, reading

# Exim filter <-- expert mode -->

The text box may already contain the following lines. Never remove them:

# The following line was automatically added so that you always get error messages
# which might be caused by faults in the filter
if error_message then finish endif

Any filtering commands you enter must be typed below those lines in the text box.

Below the text box are two buttons, Submit and Reset.

The Submit button is used when you have finished entering your filtering commands and want them to start working. When you click the button, the page will refresh, but you won't otherwise see any acknowledgement of your labours. You will however see an error message if there was any kind of mistake detected in the commands you entered in the box. This is described below.

The Reset button can be used if you make a mistake and want to return the contents of the text box to their original state before you made any changes in this session. However, this will only work if you haven't already clicked the Submit button to save your changes. If you change your mind and do not wish to use filtering, just click the Easy Mode button, which you'll find if you scroll to the bottom of the page.

How to enter filtering commands

Conditional filtering commands generally take the following basic form:

if condition
then
commands
endif

where condition is a test, or series of tests, to be applied to each new email message as it arrives, and commands instruct what to do with the message if it satisfies the condition.

Normally, the conditions examine the headers of email messages. The headers are that part of the message before the actual message text, for example the 'From', 'Subject' , and 'Date' lines and so on. In the condition tests, the message headers are signified with $h_ followed immediately by the header name and a colon. $h_subject: is an example.

Some examples

DISCARDING MESSAGES FROM A SPECIFIC ADDRESS

For this, your filter commands need to examine the sender's address, which is represented by a special variable called $sender_address. Note that the From: header ($h_from:) is not considered reliable enough to contain the sender's mail address, which is why we don't recommend you use it for filtering purposes.

Let's suppose you want to ignore and discard all messages coming from sales.team@example.com. The command would look like this:

The text expression we are testing (an email address in this example) must be enclosed in "double quotes" ('single quotes' will not work).

The word 'seen' in this filter command tells the delivery system to treat the messaage as having been delivered, even though it hasn't at this stage. The next word, 'finish' tells the system to stop doing anything more with the message. The effect of both is to discard the message, and it never reaches your INBOX.

DISCARDING MESSAGES FROM A SPECIFIC DOMAIN

The domain is that part of an email address which appears to the right of the '@' symbol. For example, hotmail.com (as in another@hotmail.com) and sussex.ac.uk (as in a.n.other@sussex.ac.uk) are both domains. If you receive a lot of unwanted email from a particular domain then you can use a filter command to discard it. Suppose, for example, you want to discard email from any address @example.com. The command to filter it would look like this:

DISCARDING MESSAGES WITH SPECIFIC KEY WORDS IN THE SUBJECT

Much junk email is readily identifiable from certain key words in the subject line. Suppose you wanted to discard any messages that have the word 'money' in the subject line. An appropriate filtering command could look like this:

COMBINING TEST CONDITIONS

You can do more than one test on any one message. For example, you might want to combine tests for both a mail domain (in the From line) and a keyword (in the Subject line), or you might want to test for several different keywords. For each extra test, you should use the word 'or' instead of 'if'. Here are two possible examples:

The first example tests not only the mail domain but also for a specified subject keyword:

The following example shows how you can test for three separate key words:

Table of 'if' test conditions

The table below shows a range of condition tests you can use with the if...then..endif expert mode command.

Condition test	What it tests	Example
begins	The start of a text string	if $h_subject: begins "Hello" then...
ends	The end of a text string	if $sender_address: ends "example.com" then...
contains	Any part of a text string	if $sender_address: contains "sales" then...
is	An entire text string	if $h_subject: is "I am lonely" then...

Filtering spam

Spam is difficult to identify reliably through automatic means. The Sussex mail system currently runs a pre-filtering system called SpamAssassin which applies complex rules to incoming messages in an attempt to identify spam. This happens before the message is handled by any filtering commands you have set up in 'Expert Mode'. Although SpamAssassin traps and blocks a vast quanity of spam, it will never be able to block it all.

Filtering using other message headers and variables

You can apply filtering tests to any message header or Exim variable. The name with which you refer to a header in a filter test is simply the name of the header itself as given in a message, prefixed with $h_ and followed by a colon (:). Exim variable are referenced by name but without a $h_ prefix, but should still have a colon added. Some commonly-used headers and variables are:

Header/Variable	What it's for	How referenced
Subject:	The Subject of the message	$h_subject:
To:	The address(es) to whom the message was sent	$h_to:
Sender_address:	Who sent the message	$sender_address:
Date:	The date and time the message was sent	$h_date:
Reply_To:	The address where replies will be sent	$h_reply_to:
X-Spam-Score:	SpamAssassin's measure of the 'spamicity' of a message	$h_x-spam-score:

Diverting email to named mail folders

It is possible to use the Exim filter to deliver email directly to a named mail folder in your mailstore. However, before you can do this, the folder must first be enabled for what is called "plus-addressing". The method (for Mulberry users) is described in FAQ number 1650. If you do not do this, any attempt to deliver directly to a folder will only deliver email to your INBOX.

Once you have set up a mail folder for plus-addressing, you can use the deliver filter command like this:

deliver username+foldername@sussex.ac.uk

where username is the name you use to login to your email, and foldername is the exact name of the mail folder to receive the email.

• Note the presence of the plus sign ('+') between your username and the folder name (this is why it's called plus-addressing).
• Do not use your 'friendly' email address (e.g. A.N.Other@sussex.ac.uk) if you have one; this will not work with plus-addressing.
• If the folder name contains spaces, you must enclose your username and the folder name within double quotes (for example, "ano23+junk mail"@sussex.ac.uk)

This example uses a hypothetical username ano23:

Or, if the mail folder name contains spaces:

If the receiving mail folder is a sub-folder within another one, you must specify the path to that folder using strokes ('/' characters) between the main folder and the subfolder. For example, if you wanted to set up plus-addressing to deliver to a folder called GPS which is inside another folder called Projects, you would specify the deliver command like this (here shown again with a hypothetical username, ano23):

deliver ano23+Projects/GPS@sussex.ac.uk

Note that if after setting this up, you subsequently delete the named mail folder, the plus-addressing will stop working. If you re-create the mail folder you will need to re-enable it for plus-addressing using the method given in FAQ number 1650.

Forwarding email together with filtering

You may want to forward your mail to another address, but only after filtering out any unwanted mail first. You might instead want to forward your mail without doing any filtering on it at all. Normally forwarding would be set up using Easy Mode in My Accounts (Mail Options), but if you switched to Easy Mode you would lose all your filtering instructions (but see the Switching Off Filtering section below).

In fact, forwarding is itself done by means of an Exim filtering command. There are two ways of using it. Either you can forward mail without leaving a copy in your Sussex account, or you can forward it and leave a copy at Sussex.

Where you put the appropriate forwarding command will determine whether the forwarding is done before or after any actual 'filtering' is carried out. You can also forward mail selectively; for example by using the forwarding command in place of, say, a 'save' command, you could decide that you only want to forward mail sent from a particular address or mail that concerns a particular subject. The basic forwarding commands are shown below.

To forward your mail without copying to your Sussex account, use the following filter command (replace the example address with your own forwarding address):

To forward your mail but keep a copy in your Sussex account, use the following filter command (again, replace the example address with your own forwarding address):

The 'unseen' directive causes a copy of the message to be delivered to your INBOX.

Sending autoreplies together with filtering

When away from the University you may wish to set your email account to send automatic replies. Installing an automatic reply together with filtering can be done, but because the appropriate commands have a fairly complex syntax, and are therefore rather error-prone, we recommend that you contact us at IT Services Online Support to discuss your requirements.

Keeping your filter commands up to date

Some circumstances requiring filtering may change. For example, junk mail from a particular domain, which you have been filtering, may stop coming if that domain ceases to exist or stops sending junk. In such cases you should consider removing the filter commands that handle this, in order to save resources on the mail server (the less work the mail server has to do, the more efficiently it will work for everyone).

Do not be tempted to add a filter instruction to discard mail from an address or domain from which you have received only a few junk mails. 'Spammers' tend to use false addresses and change addresses frequently, so it's only worth filtering junk email from persistent sources. It's better just to "Ignore, Delete and Forget" occasional junk mail rather than set up a filter against it.

What to do if it doesn't work

When you click the Submit button, the Exim filter tester checks your filtering commands. If it finds any obvious syntax errors, it will display the following warning:

It will also show the apparent error. If this happens, then you must either correct the mistake and try again, or abandon the filtering and switch back to Easy Mode (see below).

Although the filter tester checks for syntax errors, it cannot test for problems with the logic of your filter commands, so if any are present this may prevent them from doing what you intended. You must never leave incorrect filter instructions in place, otherwise you run the risk of losing email. Check everything thoroughly. NEVER try to guess filtering commands. Get help from IT Services if you are in any doubt.

As a precaution against syntax errors, the following command is automatically inserted as the very first line in the Exim filter text box:

This will cause any messages to be delivered (unfiltered) to your account in the event that there is a syntax error in any of your filtering commands (it won't protect against logic errors, however). You will not be able to delete this command; if you do then it will only be re-inserted when you Submit your changes.

Switching off filtering

You may decide to switch off your filtering, either because you need to see all incoming mail or because you no longer have a need to filter your mail. You can quickly do this by clicking the 'Easy Mode' button at the bottom of the Expert Mode page. However, remember that this will discard all your filtering commands and you will not be able to get them back. Because of this, we strongly recommend that you save your filter commands in a text file before you discard them by switching to Easy Mode. You can save them by selecting and copying the entire contents of the Exim filter text box, and then pasting this copied text into a file of your choice (perhaps using Word or Notepad). When you've done this, and saved the file, you can then click the Easy Mode button to switch off filtering.

Where to find out more

If you are a University of Sussex student or staff member and you have any queries about Exim filtering, please contact IT Services Online Support.

A full discussion of the facility can be found at the Exim website at

• http://www.exim.org/

then click the link to 'Documentation and FAQs', and you'll see another link to 'The Exim Filter Specification'. Section 7 of the Filter Specification, 'Some useful general variables', may be of particular interest because it discusses the use of other means of testing messages other than by message headers alone.