Filters

The Polarbar Mailer filters are accessed via the option on the Tools menu of the program's main window. The Inbound Mail Filters dialog lets you create, modify, delete, and rearrange filters. Filters are executed during each mail retrieval in the order in which they appear in this dialog. If you want to move a filter's position in the execution order,  select it and press the Up or Down button until it is located where you want it.

The Enable Bayesian Filtering checkbox enables automatic Bayesian probability checking on all incoming messages. If the message has a probability of 0.6 or greater, then the message is flagged as potential spam (the default icon is a red minus sign), otherwise it is flagged as unlikely to be spam (the default icon is a green plus sign). The accuracy of the probability check will depend upon the number of messages that are marked as belonging to the good message corpus (the default icon is a solid green circle) or the bad message corpus (the default icon is a solid red circle). You will probably not get consistent results until you have 200 or more messages marked for each corpus. Note: You do not need to keep bad messages around, unless you think you might have a need or desire to rebuild your bad message corpus from scratch, because the corpus is stored in a separate file in your account directory. The name of this file is BAYESIAN.DAT.

The On/Off button turns a filter off or on. You can turn a filter off any time you want to prevent it from executing without deleting it permanently. You can also turn a filter on or off,  make any other change to it, or just view its settings, by selecting it and pressing the Details button.

Always use the Save button to leave this dialog if you want any changes you've made to be kept. Cancel will close the dialog without saving your changes.

To create a filter, press the New button. This brings up the Create New Filter dialog where you specify the new filter's name and the type of filter you want it to be: Regular, List, or Java (see below). Then press the Next> button to continue with the following dialog which is appropriate to the type you've specified. The next dialog shows the filter's name at the top and an ON or OFF button which shows you the filter's current state. This button toggles it to the opposite state if you press it. At the bottom are the fields where you can specify what you want the filter to do if it finds a match between the message and what it's looking for.

Regular filters

Specify what part of the message you want the filter to search (for example, the Bayesian status (unknown, probably spam, probably not spam, bad message corpus, or good message corpus), the From line, the To line, the Subject line, the entire set of message Headers, the message Body, All Text (both headers and body), and various other choices.) Then  specify whether you want that message part to contain the search string, to not contain it, to start with it, end with it, etc. You can even select exists which means you don't specify a search string, but the filter action is activated if the specified message part is present at all. Then (if you haven't specified exists there) you type the search string which can be a word, a part of a word, or multiple words. You can make the search case sensitive by turning off the Ignore case checkbox. On the second line,  you may choose AND, OR, or XOR from the leftmost dropdown and, if you do, you can also specify the same four types of information for a second search string in a second portion of the message.

For example, you might build a filter which performs some action if the Body of the message contains the string hello or HELLO, AND the Subject ends with on Sale.

List filters

Specify where you want the message to search. If you select Message body contains any combination of the strings or Any header contains any combination of the strings, then the entry field to the right will be enabled to let you specify how many matches should be required in order to activate the filter. For example, if you say 3 and the message contains only 1 or 2 of your specified search strings, the filter will not be activated; if the message contains 3 or more, then it will. Or you can specify Received header contains any of the domains, From or Reply-To contains any of the domains, Any header contains any of the domains, From or Reply-To contains any of the user names, To, Cc, or Bcc contains any of the user names, or Any header contains any of the user names. These search criteria really do not differentiate between domains, user names, or any other type of string in any particular location. These options are named this way not because they do differentiate such things, but only to make it more obvious what the options might be used for. The search string will be found in the specified header line regardless of whether it's a domain name, a user name, etc.

Then you specify the list of strings for which you want the filter to search. The list can be one entry long or hundreds. If you have hundreds of entries, you probably have them in an ASCII text file, one entry per line, which you can import into the list box without typing them manually by selecting the Import list from a file button on the right.

Java filters

You can write a Java class which will perform the work you want the filter to do or you can write a Java class which will only return true or false and let the filter perform one or more of its own actions when the return is true. A Sample.java file is provided along with the Polarbar Mailer package. This class takes a string as an argument, searches the Subject: header of the message for that string, and returns true if the string is found.

To create a Java filter, select your class file and optionally specify any arguments with which it should be called. Of course, the class file must reside in a directory which is on your class path in order for the program to be able to execute it. Examples of how to compile Sample.java to create Sample.class are provided towards the bottom of this page.

Filter actions

For each filter, you can specify up to four actions. Each of the possible actions requires different additional information in order to do what it's supposed to do.  The middle and right hand fields are activated or not depending on which action you select on the left.

Delete Message
This option deletes the message and also prevents any further filters from trying to do anything to it.
Copy to Folder
You must specify the folder to which you want to copy the message.
Move to Folder
Like Copy to Folder except that the message will be moved instead of being copied. This option also prevents any further filters from trying to do anything to the message, except for the Route action.
Copy to Directory
You must specify the directory to which you want to copy the message.
Move to Directory
Like Copy to Directory except that the message will be moved instead of being copied. This option also prevents any further filters from trying to do anything to the message, except for the Route action.
Reply Now
You must specify a reply file which contains (nothing but) the message body text you would like to have sent as your reply. Your reply will be sent immediately, as if you pressed the Send Now button on the compose window.
Reply Later
Like Reply Now except  the reply will go into the OUTBOX folder, as if you pressed the Send Later button on the compose window.
Forward Now
Like Reply Now except that along with the contents of the reply file (if you specify one), the text of the incoming message will also be sent and you must also specify the address(es) and/or nickname(s) of the person(s) and/or group(s) to whom you want to forward the message. To forward to multiple recipients, separate the addresses and/or nicknames with a comma.
Forward Later
Like Forward Now except  the forwarded message will go into the OUTBOX folder, as if you pressed the Send Later button on the compose window.
Bounce Now
You must specify the address(es) and/or nickname(s) of the person(s) and/or group(s) to whom you want to bounce the message. The bounced message will be sent immediately, as if you pressed the Send Now button on the compose window.
Bounce Later
Like Bounce Now except  the bounced message will go into the OUTBOX folder, as if you pressed the Send Later button on the compose window.
Route Now
You may specify an optional file which contains (nothing but) the message body text you would like to have sent as a note along with the routed message. You must specify the address(es) and/or nickname(s) of the person(s) and/or group(s) to whom you want to route the message. The routed message will be sent immediately as an attachment, as if you pressed the Send Now button in the route a message window. Note:You must use a Move or Copy action to put the message into a folder before selecting the Route action.
Route Later
Like Route Now except  the routed message will go into the OUTBOX folder, as if you pressed the Send Later button in the route a messagewindow.Note:You must use a Move or Copy action to put the message into a folder before selecting the Route action.
Copy to Account
You must specify the Polarbar Mailer account to whose INBOX you want the message to be copied.
Move to Account
Like Copy to Account except the message is moved instead of  copied. This option also prevents any further filters from trying to do anything to the message.
Set Color Code
This option applies a color code to the message  like the option on the Message menu.
Play Sound
If you don't specify an audio (.AU) file here, the program will just beep when a message matches the filter's search criteria. If you do specify a valid audio file, the program will play it instead.
Show Message
This option displays the message in a window like the "unformatted" Preview Mail window.
Print Message
This option copies the message to the Print Queue folder.
Notify by Email Now
You must specify the file that contains (nothing but) the text you want to have sent as the notification and the address(es) and/or nickname(s) of the person(s) and/or group(s) that you want the filter to notify. Your notification message will be sent immediately, as if you pressed the Send Now button on the compose window.
Stop Filtering
This option causes the program to neglect to execute any further filters (lower than this one in the list on the Inbound Mail Filters dialog) against this message file after this filter has finished with it. If you don't select this action, then all filters will be executed against the message, regardless of whether the message matched this filter's search criteria or not. (Except, as noted above, the options which move or delete messages also prevent further filters from trying to act upon those messages, as if this Stop Filtering option had been selected even if it wasn't.)
Using Nicknames with Email Filter Actions

When you use nicknames (which can be for persons or groups) with a filter action that involves sending an email message, then when you press the OK button, the nicknames are validated. If any of the nicknames cannot be resolved, then you have the option of either using the bad nickname anyway or returning to the email address field to correct the nickname. Nicknames used in filters are always saved as nicknames. When the email filter action is executed, any nicknames will be resolved when the message is set up to be sent. If a nickname fails to resolve at that point, the email filter action will not be executed and an error message with the subject 'Error in filter "{filter name}"' will be placed in your INBOX, with the following contents:

An error occurred in mail filter "{filter name}" when attempting to {filter action}
message "{message subject}". The specified nickname ({address(es)}) was not found
in your address book.
A sample Java filter

The contents of the Sample.java file that is included in the Polarbar ZIP file are listed below. You should extract the Sample.java file into your base Polarbar directory (i.e., the directory that is the parent to the Mailer directory). You'll either need a JDK (or Java Developer Kit) or Jikes (if all you have is a JRE, or Java Runtime Environment) to compile the source into a Sample.class file. (Feel free the use another name for your filter's source file.)

import innoval.mailer.FilterMessage;
/*
This is a sample Polarbar mail filter class. In creating your own filter
classes it is only necessary to add logic to the getResult method. This method
must exist as a public boolean method and must return either true or false. If
you wish to pass the method string argument(s) from Polarbar's filter
procedure, you may do so by entering comma-delimited strings on the filter
definition screen.  These parameters will automatically be loaded into a
string array called parameterValues and will be available to this class.
Passing parameters in this way allows you to build multiple
filtering scenarios into a single class file.

The following variables are available to you.  You do not need to read the
message file (it has been read by the time this class is instantiated and
values are loaded into these variables).  The variables must be prefaced by
the name give the FilterMessage parameter to getResult (in this sample the
name is "msg"). So to reference the SUBJECT variable, use msg.SUBJECT in your
java statement.

parameterValues[] an array of strings containing the parameters defined for
   the given java filter
FROM              From header (reformed and unfolded)
REPLY_TO          Reply-to header (reformed and unfolded)
TO                To header (reformed and unfolded)
CC                Cc header (reformed and unfolded)
BCC               Bcc header (reformed and unfolded)
DATE              Date header
SUBJECT           Subject header
RECEIVED          Received header
PRIORITY          Priority header
BODY              Text portion of message
ALLHEADERS        Single string containing all header lines
ENTIREMSG         Single string containing complete original message
MSG_FULLPATH      Full path and file name of message file
ATTACHMENTS       Blank delimited string of attachments

*/

public class Sample {

  public boolean getResult(FilterMessage msg) {
    if (msg.SUBJECT.indexOf(msg.parameterValues[0]) >= 0)
      return(true);
    else
      return(false);
  }

  public Sample() {
  }
/*
Within the context of a java filter, you may read the message file, revise its
content and rewrite it. You should not, however, rename it or delete it. If
you rewrite the file or make copies of the file in other JStreet folders, it
is important that it conform to applicable RFC's for POP files.
*/

}
Compiling the sample Java filter

Here's how you might compile the sample Java filter using the Javac that comes with IBM's JDK 1.1.8:

javac -classpath .;\jdk1.1.8\jre\lib\rt.jar Sample.java
Here's how you might compile it using the Javac that comes with Sun's JDK 1.4.0:
\j2sdk1.4.0\bin\javac.exe -classpath .;\j2sdk1.4.0\jre\lib\rt.jar Sample.java
And here's how you might compile it using Jikes if you have IBM's JDK 1.3.0:
jikes -classpath .;"\Program Files\IBM\Java13\jre\lib\rt.jar" Sample.java
Jikes is a separate download from http://www-124.ibm.com/developerworks/oss/jikes/ (if you are using OS/2, a Google search on "jikes OS/2", without the quotes, will result in several pages where you can download an OS/2 version of Jikes).