Filtering
Filters
Scribe has 2 filtering systems at the moment, one a user specified filter list and the other is
a bayesian spam filter. They mostly work separately, (if enabled) the bayesian filter
runs first and checks incoming mail for spam. If it passes that stage then it's run through
the normal user specified filters. Which may sort, delete and mark or label email.
To create a new user filter, use the Filters ▶ New Filter menu. This opens a filter edit window
to allow you to set the conditions and actions of the filter. The first tab of the filter
window has a name, to describe what the filter does, and a couple of buttons to change the
order that the filters run in. If you select the filters folder in the main window and set
the sorting to "Index - Descending" then the buttons allow you to move the filter up and down.
Filters are executed in ascending order, from 1 through to the last number unless some filter
asks for furthur processing to stop. This means that multiple filters may match on the same
email and run their actions on it.
i.Scribe: Only the first 5 filters run when you receive mail. This is just
to demonstrate the feature that is in InScribe, enough so that you can
see how it works. If you define more than that then they appear greyed out
in i.Scribe. However if you purchase InScribe and install it they will become
active.
The user filtering system is based around the Scribe DOM
which is a system for specifying fields within Scribe objects via text labels. It's quite
simple once you get the hang of it and the menus in the filter's user interface help you
with some shortcuts to get you started. For example you might want to write a filter that
checks against the value of an incoming email's "from" header. Well, you'd use a DOM field
like this:
mail.FromWhere "mail" is an object (of type Object::Mail), i.e. the incoming email, and "From" the field within the object. However, if you study the DOM, you'll see that the From field of a mail object is of type Object::Address. Which itself has separate sub fields. So you could then specify a more precise DOM field to achieve something like querying just the name of the person sending the email like this:
mail.From.Name
This way of doing things is surprisingly powerful if you want to write some complicated filters. Ok, so are a few examples of what can be done with DOM fields; firstly, you can select a single header out of the incoming mail's headers using:
mail.InternetHeader[which is useful if some upstream mail processor has added a header that you want to filter on. Then there is the From field of the mail, which has a Contact sub field that links to the local Contact database if the address's email matches a local Contact. If someone in your Contacts emails you, then you can access all their Contact record data from the filtering system like this:{header-name} ]
mail.From.Contact.FolderWould return the path of the folder that the contact is stored in. So if you wanted, you could put your contacts in different sub folders and then filter incoming mail based on which folder the contact was in. I'm sure you can think of applications for that ;) The contact record even has a bunch of custom fields that you can name yourself and assign whatever value to. These can then be used to filter with as well. This could be used to track customer numbers or group contacts in ways specific to your own needs. There are several things that you can do with filters beyond just filtering the incoming mail. Different things may be accomplished by using different sets of filters. In this case it's useful to know that only the filters in /Filters are used in the filtering process, and filters in sub-directories are not. This means that you can "switch off" filters by putting them into a sub-directory of /Filters. If you have a folder of mail that you want to process using filters, you can do so by selecting the folder in the tree view and then clicking the Filters ▶ Filter the Current Folder menu. This runs the filters over all the email in the current folder as if you had just received it. Usually known as "filtering after the fact" in some other mail apps. This is handy if something you just received ended up in your inbox instead of being filtered, then you can go and adjust the filter, and re-run the filters over the inbox. If you need to debug a problem you're having with filters you can switch on logging using the Filters ▶ Log Filter Activity menu option. The output is written to a file called 'FilterLog.txt' in the same folder as the Scribe executable. On a related note, there is another feature that may prove useful when filtering folders. If you right click on a folder, there is an option to "Collect all mail from Sub-Folders". This moves all email in the current folder's sub-folders into the currently selected folder. Before the actions of a filter can run the conditions of the filter must be met. The filter has a list of conditions, that are either OR'd together or AND'd together to return TRUE or FALSE. The option to use AND or OR is at the bottom of the conditions tab in the filter window. The conditions list is setup as a set of records, where you create and delete conditions with the buttons "New" and "Delete". You can seek along the set of records with the scrollbar. To configure a condition, choose the field. This is any valid DOM field, and isn't limited to the list in the drop down box. Then choose the operator. Most are self explanatory, but a few bear talking about. 'Like' does a wildcard match, where the wildcard '*' matches any characters and '?' matches any single character. 'Contains' does a sub string search for the value. You can invert the logic of the condition by using the NOT operator. The drop down for the value field is entirely optional, it's just to help select values of certain types. Most of the time you can just enter in values directly. Once all the conditions are met then the actions are executed, in order from first to last. If you would like this filter to be the last filter processed on this email, set the "Stop further processing of filters" option. The available actions are:
- Move to folderMoves the email to the specified folder. Select the destination folder with "...".
- DeleteDeletes the email. Use the "..." button to configure where to delete from, either local folders, the server or both.
- PrintPrints the email using the current Printer setup (File ▶ Print Setup).
- Play SoundPlays the specified sound. Select a sound with "...".
- Open EmailOpens the email in it's own window.
- Execute ProcessExecutes a program, optionally with parts of the email as arguments. The program executed is given by the argument field. The format of the argument field is the same as an email template, in that fields are enclosed by <? field_name ?>. Available fields are specified in the Scribe DOM, and the objects in the root namespace are "filter", "mail", "now" and "scribe". e.g.
"c:\Program Files\App\my_application.exe" -subject <? mail.Subject ?> -body <? mail.Body ?>
Alternatively if you want the content of a DOM field as a file instead of a literal value, which is useful in the case of large amounts of mail body data you can wrap the DOM field name in 'file[...]' e.g."c:\Program Files\App\my_application.exe" -bodyfile <? file["mail.Body"] ?>
You have to quote the argument to 'file' or the DOM name parsing will turn into a literal before it gets passed to the code that handles wrapping the value as a 'file'. Which is normally not what you want. The file will remain at that location until Scribe is exited, at which point it will be deleted. - Set ColourSets the mark colour of the message.
- Set ReadSet the message read. This will mean it doesn't show up in the new mail list.
- Set LabelSets the label of the message.
- Empty FolderEmpties the folder given in the argument.
- Mark As SpamDeletes the email as spam. Which is the same as hitting the spam button on the main window's toolbar.
- ReplyReplies to the email with a given template. To setup a template, create a new mail in the /Templates folder by right clicking on the folder in the tree view and selecting "New Mail". Then fill out the body of the message you want to use as a reply and save the template. Then in the filter action click the "..." to set the template to use. You can use DOM fields in the template to reference the source email, e.g.:
Dear <? mail.from.name ?>, I received your email on <? mail.datereceived ?>, thanks.
- ForwardForwards the email on to a new recipient. Click the "..." button to set optional parameters. Otherwise just enter the email address to forward to. The forward action can also use a template and DOM fields like the reply action described above.
- BounceBounces the email to the address specified in the argument box as if the message had orginally come from the first sender instead of yourself. Which means that any reply your recipient sends will go to the original sender, not you.
- Save Attachment(s)Saves some or all of the attachments to a folder outside the mail storage. Click the "..." button to specify the folder to save to and the types of files to save. Use "*" to match all files, or use something like "*.gif *.jpg *.png" to match a subset of files.
- Delete Attachment(s)This action deletes attachments from an email. The argument specifies the types of files to delete. This can be "*" to match all files, or something like "*.gif *.jpg *.png" to match a subset of files.
| The main application object. |
| The filter being evaluated. |
| The mail being filtered. |