News Stay informed about the latest enterprise technology news and product updates.

How do I use LotusScript to filter certain email?

LotusScript guru Cregg Hardwick explains to a reader how to use an agent and/or LotusScript to filter certain e-mails based on words in the Summary Line or in the body of the text.

Cregg Hardwick is Collaboration Solutions Technical Lead for CenterPoint Energy in Houston. He has an MBA, a PCLP and an MCAD and focuses on collaboration and business process support applications, and has been a Notes developer since 1998. He has graciously agreed to answer some of the many questions that come into's mailbox regarding LotusScript.

Question: How do I use an agent and/or LotusScript to filter certain e-mails based on words in the Summary Line or in the body of the text?

Cregg Hardwick: Depending on what you are trying to do, you might be able to use the built-in mail rules. But there are two problems: Your organization might not allow use of rules, and rules might not do what you want. For example, rules cannot forward mail to another address. The most flexible approach, as always, is to write a LotusScript agent to do your bidding. Here's how.

First, decide what type of agent to run. For example, in R6 you can choose to run a "before mail arrives" or "after new mail has arrived" agent. For details on the types of agents available, search for "troubleshooting agents in Notes."

Agent details aside, and not knowing exactly what you are trying to do, you most likely need to use the NotesDatabase.UnprocessedSearch method. Search and UnprocessedSearch are fabulously useful methods that let you select documents exactly the way you build a view: by using a selection formula. The formula uses exactly the same syntax as the selection formula in a view. (In fact, it's an excellent idea to use a view to develop the selection formula first.)

The only difference between these two methods is that one selects a subset of the database.unprocessedDocuments collection and the other selects a subset of all documents in the database. Both take the same parameters and return a NotesDocumentCollection. You should search unprocessed documents when you have the option to do so, since doing a search is essentially the same amount of work as building a view index the first time—so anything you can do to cull the herd will pay big dividends.

Here is an example that you might use in an agent to, say, find all messages containing the word "Viagra" in the subject line.

Dim session as new notessession
Dim db as notesdatabase
Set db=session.currentDatabase
Dim spam as notesDocumentCollection
Set spam=db.unprocessedSearch

Dim spamDoc as notesdocument
Set spamDoc=spam.getFirstDocument
Do while not spamDoc is nothing
 …call routine to report or handle spam…
 Set spamDoc=spam.getNextDoc(spamDoc)
Call spam.removeAll(true)

The three parameters are the selection formula, the cutoff date (maximum age of documents to select) and the maximum number of documents to select. Note that I have wrapped the selection formula in curly brackets, which in LotusScript can be used to delimit a string constant and save you from the tedious task of escaping quotes used in your formula (i.e., {"1"} if the same as "\"1"" but much clearer).

If you want to use the cutoff date, you need to create a data object with a line of code such as dim cutoff as new notesDateTime("01/01/1970"). If you don't use the cutoff date (and you probably won't), passing "nothing" makes the query run faster. Passing zero (0) selects all matching documents.

Dig Deeper on LotusScript

  • Favorite iSeries cheat sheets

    Here you'll find a collection of valuable cheat sheets gathered from across the iSeries/ community. These cheat ...