AntiSpamFilter agent by Kent Kurchak

Level: Intermediate Works with: Designer 5.0 Updated: 01-Nov-99

This article is third in our series this month on Notes spam mail filtering. In this article, we learn about an anti-spam filter agent that you can download from the Iris Sandbox and add to your mail database.

The AntiSpamFilter agent, like Notes mail rules and Domino mail router restrictions, filters messages based on the sender's address. This article explains how to add the agent to your mail database, set up the agent, and use it to filter spam mail.

Please note the following requirements:

• The download database and all the anti-spam design elements require the Notes R5 client.
• The anti-spam design elements do not work in the Web browser version of mail.
• You need (and should be familiar with) Domino Designer R5 to add the agent to your mail database.
• Your home/mail server must be Domino R5 (unless you are using Notes to retrieve ISP mail).

Setting up the agent
To get started, open the sample database in Domino Designer R5 and copy the following design elements to your mail database. The agent does not impact any of the existing mail design elements and no other design modifications are necessary for the AntiSpamFilter agent to run.

Agents
Stop Spam
AntiSpamFilter
(RevertToNonSpam)

If your mail database resides on a Domino server, be sure to change the "When should this agent run?" option on the AntiSpamFilter agent to "Before New Mail Arrives." You can also run the agent locally in the Notes client by changing the agent trigger to "If Documents Have Been Created or Modified."

Forms
SpamCFG
AntiSpamProfile

Views
SPAM\Configuration
SPAM

There are three security settings that allow the AntiSpamFilter agent to run. The first two settings are required to run the Out of Office agent, so if you have configured and used that agent correctly, you can run the AntiSpamFilter agent.

1. You must have at least Designer access to your mail database to enable the agent to run on your home/mail Servers.
2. You must be allowed to run agents that use LotusScript on your home/mail servers. Administrators can set this on the Security tab in the Server document.
3. The pre-delivery agent timeout value on the Router/SMTP - Restrictions and Controls - Delivery Controls tab in the Server Configuration document must allow enough time for the agent to run. The default setting is 30 seconds, which should be more than enough time depending on how many addresses you have configured to filter. Check with your administrator on this setting.

Once you are satisfied that the AntiSpamFilter agent is a good fit for your company (and you have thoroughly tested it), you or your system administrator can add the design elements listed above to the MAIL50.NTF design template. The Design server task will update the design of users' mail databases.

How the AntiSpamFilter agent works
Let's take a look at how to configure and use the AntiSpamFilter agent.

First, open your Inbox folder or All Documents view and select one or more unwanted messages. Next, choose Actions - Stop Spam to create a separate SpamCFG document for each message you selected. The AntiSpamFilter agent will know which senders to block, and then you can delete the original message(s).

SpamCFG documents appear in the SPAM\Configuration view, for example:



The Stop Spam action can:

• Ignore messages where you are listed as the sender.
• Create a NotesName object for the sender's name and attempt to extract the Internet address from it using the Addr821 property. If the Addr821 property returns an empty string, this means that the address is probably a Notes mail address, in which case the abbreviated version of the sender's hierarchical name is returned.
• Recognize the domain (either Notes or Internet) name in an address, so you can opt to filter all senders from an entire domain.
• Ensure that the SpamCFG documents only appear in the SPAM\Configuration view.

Now, in the SPAM\Configuration view, open one of the SpamCFG documents and double-click on it to open in Edit mode.



By default, the individual sender name is blocked. Select the Domain option to block all senders from the domain.



Note: While you can block individuals from your own domain, you cannot block your everyone from your own domain. Save and close the document.

In the SPAM\Configuration view, click the Configure AntiSpamFilter Agent action button to open the AntiSpam Agent Configuration document.



The default setting for the AntiSpamFilter agent places the spam mail in the SPAM view. You can choose to delete spam mail instead -- the agent deletes any message for which the From field equals the individual sender's address or includes the domain name (depending on the SpamCFG setting for the particular address).

Select the "Reply with message" checkbox to automatically reply to the spammer. The reply will be sent before the message is deleted or placed in the SPAM view. You can set the Subject and Body fields on the message. For the Body, you can choose one of the sample messages (choose A, B, C, or D), or you can write a custom message.

Before selecting "Reply with message," be aware that most spam does not have a valid From address, so it's likely your message will never be received by the spammer. In some cases, your reply actually validates your e-mail account for the spammer, which in turn may generate even more spam.

If the agent is currently disabled (OFF), click the Enable AntiSpamFilter Agent action button to enable the agent. Remember that you can have only one of these agent types running at a time in your mail database. In other words, when you enable the AntiSpamFilter agent, any other agent using the "Before New Mail Arrives" trigger will be disabled.

The AntiSpamFilter agent itself is designed to be as efficient as possible. Agents using the "Before New Mail Arrives" trigger process each incoming message one at a time by using the NotesSession object DocumentContext property to get a handle to each message document. The agent takes the value of the From field in the message and loops through the rows in the SPAM\Configuration view using the ViewEntry object, which is faster than the NotesDocument object, to find a match. If it finds a match, the agent uses the AntiSpamProfile settings to determine what to do with the message. Once it performs the action, the agent immediately stops looking in the SPAM\Configuration view for more address matches and terminates.

If you chose to display messages in the SPAM view rather than to delete them, you can trace the source of the message or send a copy to your system administrator to block the sender for all users at the server. If you decide that the message isn't unwanted after all, click the Revert to Non-Spam action button to remove the flags that hide the document from the other views.

R5-specific code
The AntiSpamFilter agent is specific to R5 for several reasons:

• It uses the "Before New Mail Arrives" trigger.
• The NotesSession object DocumentContext property instantiates a document object for the incoming message before the router delivers it to the mail database.
• The NotesViewNavigator and NotesViewEntry classes navigate a view row-by-row to read document data without the overhead of opening the document.
• The NotesName object Addr821 property extracts the Internet address (without comments) from the sender's From address.
• The NotesDocument object Save method has a third parameter that, if set to True, marks the saved document as "read."
• The images for the action buttons are drawn from shared Image Resources already found in the R5 mail database design.

Limitations
The AntiSpamFilter agent has a few limitations. For instance, to prevent two AntiSpamFilter agents from causing a mail storm by responding to each other, the agent checks for the $AssistMail field before responding. This means that you cannot block agent-generated mailings.

During testing, the AntiSpamFilter agent blocked all Internet and Notes addresses from the same and other domains, however, if the agent cannot interpret the From address the message is delivered normally. Some From fields (such as if you receive mail via POP3) are set to the data type RFC822 Text. Although it looks like text, Evaluate("@Text(From)", doc) converts this data type to text in order to be read by LotusScript. The NotesItem object Text property does not perform the conversion.

Although you can manually enter known spammers' addresses in the SPAM\Configuration view, you must receive at least one message from a spammer to automatically add it to your list of known spammers by choosing Actions - Stop Spam. Then, the assumption is that the spammer will use the same return address for subsequent messages, but that assumption is not always correct. Address filtering in general has this shortcoming.

If there is no Connection document to a spamming Notes domain, automatic responses will fail. The agent writes an error message to the server console, specifying the failure to connect.

Filtered messages saved to the SPAM view are not marked "read", and therefore, add to the database unread counter. The third argument in the Save method does not work in this context.

Of course the larger "limitation" is if you elect to filter entire domains and to delete messages rather than display them in the SPAM view. You may unwittingly miss some important e-mail messages.

Final thoughts
Although the AntiSpamFilter agent is as efficient as possible, remember that it runs against every incoming message and that the cumulative effect of the agent running in many users' mail files could add up to cause significant delays.

Keep in mind that this client-side message filtering feature does not replace mail rules or router restrictions in the fight against spam. It does, however, offer an easy-to-use tool that can effectively filter unwanted e-mail. And if not the perfect anti-spam device, the AntiSpamFilter agent at least provides you with a starting point to develop even more powerful Notes-based anti-spam tools.

ABOUT THE AUTHOR
Kent Kurchak is the owner of wareSource, a Lotus Business Partner that provides robust, customizable, and economical training materials for Lotus Notes and Domino users, developers, and administrators. Its products are used worldwide by other Lotus Business Partners, training companies, independent instructors and consultants, corporate training departments, and individuals.