Filters, part 2: Email Filters

As you may know, Webcrossing users can subscribe to individual discussions or entire folders. They can read their subscriptions either through the web interface or via email. As an admin you can configure the system to send individual email notifications for each new posting or to accumulate and send digest emails at intervals. Individual notifications can contain the full text of the posting or only a link back to the conference. Whatever options you enable, you can also allow your users to choose their preferred method.

That's a lot of flexibility, but there is a class of filters that can give you complete control over the email notification system (and indeed over all email processing). These filters are SSJS only; unlike many other filters they cannot be written in WCTL. (Although even that is not an absolute prohibition; see Sue's post about mixed-mode coding.)

The filters are:

emailFilterNotify fires whenever an individual email notification is ready for delivery. Inside this filter you have access to three global variables:

• filterMessagePath (read-only) is the storedUniqueId of the item which the notification is for
• filterMessageFull (read/write) is the complete text of the full-message notification
• filterMessageUrl (r/w) is the complete text of the linkback notification

By altering the two writeable globals you can change the appearance and content of the notification. However, there are several things you can't do with this filter. For example, you cannot condition your changes on which user is receiving the notification, nor can you alter the recipient list, which form of the notification the user is receiving, and so on. For that, you want to use the more powerful emailFilterIndividual.

emailFilterIndividual has a more extensive set of globals:

• filterMessageFrom (r/w) is the bounce address for the message. By default it is set to bounce.userId.msgCounter@firstDomain where firstDomain is the first entry in the list of email domains available for the message location.
• filterMessagePath (r-o) is, as above, the id of the item
• filterMessageFull (r-o) is the normal full-message notification
• filterMessageUrl (r-o) is the normal linkback notification
• filterMessageFullPlain (r-o) is the normal full-message notification converted to a plaintext format
• filterMessageUser (r-o) is the userId of the recipient
• filterMessageRcpt (r/w) is the recipient email address
• filterMessageIndividual (r/w) is the content that will ultimately be sent. It is empty when the filter is called; if it is nonempty when the filter exits then it is what will be sent instead of the default format
• filterMessageSuppress (r/w) is a flag to prevent the message from being sent. It is empty when the filter is called; if it is nonempty when the filter exits then no notification will be sent

Note that rather than editing the filterMessageFull or filterMessageUrl globals directly, as in emailFilterNotify, in emailFilterIndividual you can read from them but you put your desired alterations into filterMessageIndividual. Here is a simple example to illustrate:

%% function emailFilterIndividual() {

       filterMessageIndividual.append( filterMessageFull ).crlf().crlf();

       filterMessageIndividual.append( 'This is an extra line.' ).crlf();

} %%

This trivial example takes the default full-text notification and adds some text to the end of it. That is what the user will receive, overriding whatever preferences they have set for email format.

Some other noteworthy points:

All the writeable globals are ByteBuffers. A ByteBuffer is a stringlike object but it comes with a suite of helper methods that make it easy to compare, parse, and convert text.

The filterMessageFull, filterMessageUrl, and filterMessageFullPlain globals are actually in MIME format. That is, they contain all the message headers followed by two crlf pairs, followed by the message content. You can use the built-in Mime object to parse and manipulate this, and even create multipart messages containing inline attachments or other non-text content.


Thirdly, there is also emailFilterDigest. As its name suggests, it fires whenever a digest-style email notification is ready for delivery. I won't discuss it in detail now, just to keep this post a manageable length. But like emailFilterIndividual it gives you complete control over the content of the outgoing email, its recipients, or even whether to send it at all.