Table of Contents | Previous | Next | Index


Appendix A
Mail Filters

This appendix tells you how you can use JavaScript to filter your incoming mail and news when you use Netscape Messenger.

There are two steps to this process:

  1. Write a JavaScript function to serve as a filter and put it in your filters file. This function takes one argument, a message object, and can make changes to that message.
  2. Add an entry for the JavaScript function to your mail rules file. Your rules file can have multiple filters. Messenger applies each filter in turn to a message until one of the filters acts on it.
This appendix contains the following sections:


Creating the Filter and Adding to Your Rules File

The first step is to write a filters.js file. This file contains the JavaScript functions that perform the mail filtering. These functions can use all features of client-side JavaScript. The location of this file depends on your platform, as shown in the following table.

Platform File location

Unix

$(HOME)/.netscape/filters.js

where $(HOME) is the directory in which Navigator is installed.

Windows

\Program Files\Communicator\Users\<username>\Mail\filters.js

Macintosh

filters.js, at the root of your profile folder

The following is an example of a simple mail filter file. It files all messages from my_mom into the "FromMom" folder, and marks them as high priority. It also sends all messages from my_sister to the trash folder.

// filters.js file.
function MomFilter(message) {
   if (message.from.indexOf("my_mom@mothers.net") != -1) {
      message.priority = "High";
      message.folder = "mailbox:FromMom";
   }
   else if (message.subject.indexOf("my_sister@sisters.net") != -1) {
      message.trash();
   }
}
NOTE: There is no way to specify an IMAP folder using the mailbox: syntax. So, if you refile things using IMAP, they all end up on your local machine.
Once you've written the JavaScript filter function, you add a reference to the filter in your mail rules file. The location of your rules file is also platform dependent, as shown in the following table.

Platform File location

Unix

$(HOME)/.netscape/mailrule 

Where $(HOME) is the directory in which Navigator is installed.

Windows

\Program Files\Communicator\Users\<username>\Mail\rules.dat

Macintosh

Filter Rules, at the root of your profile folder

This file is normally only written by the filter system in Netscape Messenger. If you've got a rules file already, add the following lines to it:

name="filterName"
enabled="yes"
type="2"
scriptName="scriptName"
Where:

name="filterName"

Gives a descriptive name to the filer.

enabled="yes"

Says to use this filter. To turn off the filter, change this line to enabled="no".

type="2"

Marks this filter as being JavaScript.

scriptName="scriptName"

Is the JavaScript function to execute.

The appropriate entry for the example above would be:

name="Filter for Mom"
enabled="yes"
type="2"
scriptName="MomFilter"
You can add multiple groups of the above lines to your rules file to add multiple filters. They are executed in the order listed in the file until one of them performs an action on the message (sets a property or calls a method).

If you don't already have a mail rule file, you'll need to add the following two lines at the top (before any filter references):

version="6"
logging="no"

News Filters

The above discussion about adding filters to your mail rule file applies to news filters as well. The only difference between news filters and mail filters is the type line. With mail filters, you use type="2". For news filters, you use type="8".


Message Object Reference

Filter functions take one argument, a message object. For news filters it is a News Message object and for mail filters it is a Mail Message object.

Mail Messages

A Mail Message object has the following methods:

Method Description
killThread()

Mark a thread as ignored.

watchThread()

Mark a thread as watched.

trash()

Mark the message read and move it to the trash folder.

A Mail Message object has the following properties:

Property Description
folder

Reflects the folder containing the message.

read

Reflects whether or not the message has been read.

priority

Reflects the priority of the message.

To refile a mail message, you set the folder property of the message object. You can use either a full path or the mailbox: URL syntax to specify the destination.

The priority property can be set using either an integer or a string. The possible values are:

Message Headers

In addition to the properties listed above, Mail Message objects offer all of the message headers as read-only properties. So, the subject of the message can be retrieved as message.subject and the CC list as message.cc. Headers with hyphens in their names (such as Resent-from) cannot be retrieved with the dot syntax. Instead, retrieve them using the array syntax for a property value (such as message["Resent-from"]).

News Messages

A News Message object has the following methods:

Method Description
killThread()

Mark a thread as ignored.

watchThread()

Mark a thread as watched.

A News Message object has the following properties:

Property Description
group

(Read-only) Reflects the news group containing the message.

read

Reflects whether or not the message has been read.

sender

(Read-only) Reflects the sender of the message.

subject

(Read-only) Reflects the subject of the message.


Debugging Your Filters

If there is a problem with your JavaScript filters, you'll get the standard JavaScript alert telling you the nature of the error. Any filters affected by the problems are not used to filter your messages. Consequently, if you've got problems, all the mail remains unchanged in your Inbox.


A More Complex Example

This filter file lets you easily perform one of several changes to a message. First, it uses object initializers to create an array of objects. Each of those objects represents a set of messages and what the function will do with messages in that set. The objects can have the following properties:

field

Which message field to use to match against (such as From or Resent-From).

probe

The value of the field that matches.

folder

The mail folder into which to put the message

trash

True if the message should be put in the Trash folder

priority

A new priority for the message.

Once it has the array of filters, the code creates regular expressions from those filters to use in matching individual messages. When Messenger calls ApplyFilters for a message, it searches for a match in the MyFilters array. If it finds one, the function either puts the message in the trash, moves it to a new folder, or changes its priority.

var MyFilters = [
   {field:"From",        probe:"cltbld@netscape.com",      folder:"mailbox:Client Build"},
   {field:"From",        probe:"scopus@netscape.com",      folder:"mailbox:Scopus"},
   {field:"Resent-From", probe:"bonsai-hook@warp.mcom.com", trash:true"},
   {field:"Resent-From", probe:"xheads@netscape.com",       folder:"mailbox:X Heads"},
   {field:"Resent-From", probe:"layers@netscape.com",       priority:"High"}
];
// Initialize by compiling a regular expression for each filter
for (var i = 0; i < MyFilters.length; i++) {
   var f = MyFilters[i];
   f.regexp = new RegExp("^" + f.field + " *:.*" + f.probe, "i");
}
function ApplyFilters(message)
{
   trace("Applying mail filters");
   for (var i = 0; i < MyFilters.length; i++) {
      var f = MyFilters[i];
      if (f.regexp.test()) {
         if (f.trash) {
            message.trash();
         } else if (f.folder) {
            message.folder = f.folder;
         } else {
            message.priority = f.priority;
            continue;
         }
         break;
      }
   }
}

Table of Contents | Previous | Next | Index

Last Updated: 05/27/99 21:21:48

Copyright (c) 1999 Netscape Communications Corporation

Any sample code included above is provided for your use on an "AS IS" basis, under the Netscape License Agreement - Terms of Use