IBM Support

Difference between 'Before new mail' and 'After new mail' agents



What is the difference between a "Before new mail arrives" agent and "After new mail has arrived" agent? What should you consider when using these agent types?


Task that runs the agent types

A "Before new mail arrives" agent is run by the Router server task, not by the Agent Manager (AMGR). When an agent is triggered before new mail, the Router task runs the agent prior to delivering the mail message to the recipient. The agent is run almost immediately when new mail is received.

An "After new mail has arrived" agent is run by the Agent Manager (AMGR) server task. This agent type does not run immediately after delivery of the mail message. Instead, the agent is moved from a "triggered" state to a "scheduled" state after delivery. From there, it moves into the eligible queue and runs. This process of moving from triggered to running could take a few minutes, up to quite some time, depending upon how many agents are already scheduled in the eligible queue to run ahead of it.

Number of agents allowed

A database can have only one "Before new mail arrives" agent enabled at a time. (Other "Before new mail arrives" agents can exist, but must be disabled.)

A database can have many "After new mail has arrived" agents. Note, however, that server performance can become affected if too many databases have multiple "After new mail has arrived" agents enabled at one time.

Document processing differences

The way you process documents can vary depending upon the agent trigger.

If the agent trigger is "Before new mail arrives," for each mail message delivered, the agent runs once. Therefore, you should use the DocumentContext property of the NotesSession class (for LotusScript) or the getDocumentContext property of the AgentContext class (for Java) to get a handle to the new mail and process it correctly.

If the agent trigger is "After new mail has arrives," then a few minutes can pass between the time the agent gets triggered to run and the time the agent actually runs. In this time, the database in question may have received multiple messages. Therefore, use the UnprocessedDocuments property of the NotesDatabase class (for LotusScript) or the getUnprocessedDocuments property of the AgentContext class (for Java) to process the collection of documents that have not been processed by the agent yet.

The key point is that "Before new mail arrives" agents process one document at a time, and "After new mail has arrived" agents can process multiple documents delivered between the time the agent is scheduled to when it runs.

Unless response time of the agent is critical, it is more efficient to use an "After new mail has arrived" agent to process documents in most cases because multiple documents can be processed in a single execution of the agent.

Details on "After new mail arrives" interval and delay defaults

Notes.ini file parameters provide the ability to control the number of minutes that correspond to how frequently the agent is executed. The value of any of these parameters can be reduced to a lower number (which increases the frequency at which the agent is executed); however, reducing the number might potentially affect server performance. If performance is affected then try a higher number, with the goal of finding a balance between performance and agent delay times.

Note: The detail provided below can be found in the Domino Administration Help in individual entries as well as in the topics "An agent isn't running at the expected times", "Improving Agent Manager performance" and "NOTES.INI Settings."
    This setting specifies the minimum elapsed time, in minutes, between execution of the same new mail-triggered agent. The default is 0 (no interval between executions). Similar to AMgr_DocUpdateAgentMinInterval, entering an interval can result in the agent running less frequently.


    This setting specifies the time (in minutes) that the Agent Manager delays before scheduling a new mail-triggered agent after new mail is delivered. The default is 1 minute. Similar to AMgr_DocUpdateEventDelay, the delay time ensures the agent runs no more often than the specified interval. When the agent executes, it will also process all additional events (if any) that occurred during the interval. A longer interval results in the agent running less often, thus reducing demand for server time. If document update events are infrequent, however, you can reduce the delay to ensure the agent runs soon after the event occurs.

Performance considerations, restrictions, and usage related to "Before new mail arrives"

Because the Router task executes a "Before new mail arrives" agent, it is recommended that you keep the agent as short and as efficient as possible so as not to slow down the router. Because efficiency is a paramount concern, certain restrictions exist for "Before new mail arrives" agents:

  • The agents are not allowed to call other agents.
  • The agents are not allowed to modify attachments. They are allowed to examine attachments and detach them.
  • Incoming mail can be copied into one additional folder besides the Inbox.
  • The agents have a stricter restriction on how long they are allowed to run. (The default is 30 seconds.) This restriction is different from the maximum duration of LotusScript and Java agents specified in the Agent Manager section of the Server record, which specifies the limit on all agents except the "Before new mail arrives" agents.
  • The maximum duration is set within the Configuration Settings document > Router/SMTP > Restrictions and Controls > Delivery Controls tab. The setting is labeled "Pre-delivery agent timeout" (which writes the value to a field named "NewMailAgentTimeout").
  • The incoming mail document object is handled by using the LotusScript DocumentContext property (of the NotesSession class). For example:

    • Dim session as New NotesSession
      Dim doc as NotesDocument
      Set doc = session.DocumentContext

Cross reference information
Product Component Platform Version Edition
IBM Domino Lotus Domino Server AIX, i5/OS, Linux, Solaris, Windows, z/OS 8.0, 7.0, 6.5, 6.0, 5.0 All Editions

Document information

More support for: IBM Domino Designer

Component: --, Lotus Domino Server, ">More...

Software version: 5.0, 6.0, 6.5, 7.0, 8.0

Operating system(s): AIX, Linux, Solaris, Windows, z/OS

Software edition: All Editions

Reference #: 1221064

Modified date: 29 June 2018

Translate this page: