Creating an 'After new mail is delivered' agent

Rules should work for what you are describing. However, rule processing has to be enabled on the server, and sometimes you need to disable and re-enable your rules.

The biggest problem with rules (from my perspective as a developer) is that, since they are executed by the mail router, we are dependent on the administrators to figure out why they don't work. That's OK, but it's always easier to debug something you can actually step through in the debugger. Indeed, that's one of several reasons that our group has always promoted using LotusScript instead of Formula Language in most situations.

At any rate, you certainly can create an "After new mail is delivered" agent to do the same thing and at least you can debug that agent yourself. I should point out, however, that such an agent will still run on the server, which means you need to keep a few things in mind. First, you may or may not have access to run agents on the server. Second, such an agent cannot access the user interface -- no references to NotesUi objects of any kind.

When you create an "After new mail is delivered" agent, all newly delivered mail will be presented to the agent in the NotesDatabases's "UnprocessedDocuments" collection. Therefore, the following code (pasted into the agent's "initialize" event) will do the job:

Dim session As New NotesSession
Dim db As notesdatabase
Set db =session.CurrentDatabase
Dim failures As NotesDocumentCollection
Set failures=db.UnprocessedSearch({Form="NonDelivery Report"},Nothing,0) 
Call failures.PutAllInFolder("Delivery failures")

Whenever the agent runs, it will search the collection of any mail received since the last time it ran. Any matching documents will be placed in the "Delivery failures" folder, which will be created from the default view unless you have created it ahead of time (You may also choose to call failures.RemoveAllFromFolder to remove these documents from the $Inbox folder where the mail router places all new mail).

The selection formula in the "UnprocessedSearch" call is a Formula Language search -- the same language used when composing a view. I have selected delivery failure messages by the form name that the Lotus Notes mail router gives them, but you can select any set of documents for which you can write a selection formula.

Indeed, I used this simple concept to write an entire enterprise mail-scan tool that enforced our corporate retention policy, deleted large attachments, removed slam and could be used to quickly retract e-mails sent by mistake.

There is one thing I'd like to point out about such an agent. Just as Lotus Notes offers multiple ways to code an action (LotusScript, Formula Language and "Simple Actions"), it also offers multiple ways to select documents. In the case of an agent, you can use one of the database search or FTsearch methods, or you can use the little built in selection wizard on the agent design page. When you use the latter, you are actually creating a full-text search, the results of which will be returned to the agent through the UnprocessedDocuments collection.

My advice is NEVER to use this feature. If you want to perform a full-text search, then code it explicitly by using the FT search syntax in conjunction with the NotesDatabase FTSearch or UnprocessedFTSearch methods.

If you use the wizard, it's hard for someone later reviewing your code to clearly see exactly what documents you are selecting, and they may not realize a FT search is being performed. Indeed, many developers and administrators are not aware of this, so let me reiterate -- if you use the document selection wizard of an agent, you are creating a full-text search.

If the Lotus Notes database does not, in fact, have a full-text index, then every single time the agent runs, a message will be written to the server log indicating that "Warning: Agent is performing full- text operations on database 'Mailscan.nsf' which is not full text indexed. This is extremely inefficient."

To understand how inefficient this is, consider that running a db.search is equivalent to the first time you open a view with a single column. Performing a FT search does the same amount of work as building the full text index for the database (and uses the same amount of disk space).

In both cases, the work is done each time the agent runs. So while you might well elect to perform a db.search in order to provide flexibility or avoid having another view for the indexer to maintain, in general, if you need to perform a FT search, you need to build a FT index for the database and allow the FT Indexer to keep it current for you.

That's my little digression on document selection. For details on writing this sort of agent, read Julie Kadashevich's classic "Managing the agent manager" and other related articles available under "technical articles" (formerly LDD Today) in IBM's developer Works site.