rev 02 Elm Filter Help Filter ------ This document provides basic instructions for NCF users to set up Elm's filter to filter incoming e-mail messages, such as mailing lists and junk e-mail (spam). The filter program is part of the Elm mailreader's package of tools. Note that you can use it to filter your incoming e-mail even if you are not using Elm to read your mail. Setting up Filter ----------------- 1] ">go elm" and choose menu item to: Test Elm mail filtering 2] Choose menu item to: Edit your mail filtering rules Enter a modified version of the following two lines in your filter-rules file. if (subject = "blah") then save "test" if (always) leave 3] Choose menu item to: Activate mail filtering 4] Send yourself two test messages: one with `blah' in the subject and one without `blah' in the subject. 5] Start your mailer (mail or Elm) and check that the messages were delivered correctly. The one with `blah' in the subject should be in the folder `test' in your work directory and the one without `blah' in the subject should be in your FreePort mailbox. 6] Choose menu item to: View log of your recent filter deliveries You should also check your filterlog file to see how the delivery of both messages was recorded. If both messages were delivered correctly your filter is now fully functional and you can proceed to add additional rules depending on how you wish to sort your incoming e-mail. Note that if you wish to de-activate the filter, ">go forward" and cancel e-mail forwarding. This will not affect the contents of your filter-rules file. It can be re-activated as in step 3] above. 7] TROUBLESHOOTING * Make sure that you have activated the filter If you ">go forward" and check where your mail is going now, you should see something like following in your .forward file. |"/freenet/rootdir/bin/BBfilter.shell" * Check your filter-rules file for typos And repeat steps 4] to 6]. Writing the Rules ----------------- The language for writing filter rules is pretty simple, actually. The fundamental structure is: if (condition) then action Where condition is constructed by an arbitrary number of individual conditions of the form "field relation value" (an optional further type of rule is of the form "(always) action" but should only be used as the last rule in the ruleset, for obvious reasons). The field value can be: subject sender (Sender:) from to (To: or Cc:) lines For the field lines, the relation can be any of the standard relationships ('>', '<', '>=', '<=', '!=' and '='). 'contains' is equivalent to the relation '=' or you can skip the relationship entirely (e.g. subject = "joe", subject contains "joe", and subject "joe", are all equivalent). The value is any quoted string that is to be matched against or a number if lines is the field being considered. Individual conditions are joined together by using the word 'and', and the logic of a condition can be flipped by using 'not' as the first word (e.g. "subject "fun" and not subject "games""). Note that the 'or' logical conjunction is not a valid part of the filter conditional statement. Finally, action can be any of: Action Description delete Deletes the message save foldername Saves a copy of the message in the specified foldername, where foldername is a folder (file) in your work directory. savecopy foldername Does the same as save, but also puts a copy in your mailbox. forward address Sends the message to the specified address. forwardc address Sends the message to the specified address and leaves a copy in your mailbox. leave Leaves the message in your mailbox. The rules file can also contain comments (any line starting with a '#') and blank lines. Metacharacters may be escaped by a preceding '\' to remove any special meaning. If you need a '%' character as part of an argument (such as an address), use "\%". If you need a double quote in a double quoted string, use "\"". If you need a single quote in a single quoted string, use "\'". If you need a backslash in any kind of string, use "\\". Example rules ------------- # filter-rules # # Filter rules for the Elm Filter program. Don't change without # some serious thought. (remember - order counts) # # rule 1 if (from = "pest@yahoo.com") then delete # rule 2 if (to = "ag221") then leave # rule 3 if (to = "trn-users" and lines > 20) then save "trn" # rule 4 subject = "filter test" then forward "me@example.com" # rule 5 if ( subject = "elm" ) savecopy "elm-incoming" To translate these into English: 1. All messages from "pest@yahoo.com" should be deleted. 2. All mail addressed to "ag221" should be left in my mailbox. 3. All mail addressed to "trn-users" with at least 20 lines should be saved in a folder `trn' in my work directory. 4. All messages that contain the subject "filter test" should be forwarded to me at me@example.com 5. All messages with a subject that contains the word "elm" should be saved in the folder `elm-incoming' and also a copy left in my mailbox. Notice that the order of the rules is very important. If we, for example, were to get a message from "pest@yahoo.com" that had the subject "filter test", the filter program would match rule 1 and delete the message. It would never be forwarded to me@example.com. It is for this reason that great care should be taken with the ordering of the rules. Resources --------- This document is based in part on The Elm Filter System Guide and the Filtering Mail FAQ . For more information on the Elm filter program see . =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-= hce 10 July 2003