Understanding Transport Agents

Applies to: Exchange Server 2010

Transport agents let you install custom software, created by Microsoft, by third-party vendors, or by your organization, on a computer that is running Microsoft Exchange Server 2010. This software can then process e-mail messages that pass through the transport pipeline on a Hub Transport server or Edge Transport server. Custom transport agents provide additional functionality to Exchange 2010, such as anti-spam or antivirus programs or any transport function that your organization may require.

Transport agents are typically installed automatically as part of applications that are designed to function together with Exchange 2010. However, there may be instances where organizations want to develop their own transport agents to manage mail that flows through their Exchange 2010 organization.

Warning

Transport agents have full access to all e-mail messages that they encounter. Exchange puts no restrictions on a transport agent's behavior. Transport agents that are unstable or contain security flaws may affect the stability and security of Exchange. Therefore, you must only install transport agents that you fully trust and that have been fully tested in a test environment.

Looking for management tasks related to managing transport agents? See Managing Transport Agents.

Contents

Transport Agents and SMTP Events

Prioritization of Transport Agents

Built-In Transport Agents

Troubleshooting Transport Agents

Transport Agents and SMTP Events

Transport agents that are written for Exchange 2010 use SMTP events. These events are triggered as messages move through the transport pipeline. SMTP events give transport agents access to messages at specific points during the SMTP conversation and during routing of messages through the organization. The following tables list the SMTP events that provide access to messages in the transport pipeline.

SMTP Receive events

Sequence	SMTP event	Description
1	OnConnect	This event is triggered upon initial connection from a remote SMTP host.
2	OnEhloCommand	This event is triggered when the EHLO SMTP verb is issued by the remote SMTP host.
3	OnHeloCommand	This event is triggered when the HELO SMTP verb is issued by the remote SMTP host.
4	OnAuthCommand	This event is triggered when the AUTH SMTP verb is issued by the remote SMTP host.
5	OnEndOfAuthentication	This event is triggered when the remote SMTP host has completed authentication.
6	OnMailCommand	This event is triggered when the MAIL FROM SMTP verb is issued by the remote SMTP host.
7	OnRcptToCommand	This event is triggered when the RCPT TO SMTP verb is issued by the remote SMTP host.
8	OnDataCommand	This event is triggered when the DATA SMTP verb is issued by the remote SMTP host.
9	OnEndOfHeaders	This event is triggered when the remote SMTP host as completed submitting the e-mail message headers.
10	OnEndOfData	This event is triggered when the remote SMTP host issues <CRLF>, which indicates the end of data.
**	OnHelpCommand	This event is triggered when the HELP SMTP verb is issued by the remote SMTP host. This event can occur at any time after the OnConnect SMTP event and before the OnDisconnect SMTP event.
**	OnNoopCommand	This event is triggered when the NOOP SMTP verb is issued by the remote SMTP host. This event can occur at any time after the OnConnect SMTP event and before the OnDisconnect SMTP event.
**	OnReject	This event is triggered when the receiving SMTP host issues a temporary or permanent delivery status notification (DSN) code to the sending SMTP host. This event can occur at any time after the OnConnect SMTP event and before the OnDisconnect SMTP event.
**	OnRsetCommand	This event is triggered when the RSET SMTP verb is issued by the sending SMTP host. This event can occur at any time after the OnConnect SMTP event and before the OnDisconnect SMTP event.
11	OnDisconnect	This event is triggered upon disconnection of the SMTP conversation by either a receiving or sending SMTP host.

Categorizer events

Sequence	Categorizer event	Description
1	OnSubmittedMessage	This event is triggered upon submission of a message into the Submission queues on the receiving SMTP host. All messages encounter this event whether they arrived via SMTP submission, MAPI submission, or the Pickup or Replay directories.
2	OnResolvedMessage	This event is triggered after all the recipients have been resolved, but before the next hop has been determined for each recipient. The OnResolvedMessage routing event enables subsequent events to override the default routing behavior by using the per-recipient SetRoutingOverride method.
3	OnRoutedMessage	This event is triggered after messages have been categorized, distribution lists have been expanded, and recipients have been resolved.
4	OnCategorizedMessage	This event is triggered when the Categorizer completes processing the message.

Transport agents can be registered on any of the SMTP events that are listed in the preceding tables. However, the intended action of the transport agent usually dictates which SMTP events it will run on.

Consider anti-spam agents as an example. For these agents, the most important consideration, other than the validity of the message contents, is the point at which a valid spam message is identified and rejected. The sooner a message that has been confirmed to be spam is rejected, the lower the cost to your organization. All the SMTP events that are triggered before the OnEndOfData SMTP event do not require that a non-delivery receipt (NDR) be generated by the receiving SMTP host. An NDR isn't generated because the full message contents aren't delivered before the OnEndOfData SMTP event is reached. Therefore, the sending SMTP host is still responsible for the final delivery of the message. If delivery to the receiving SMTP host fails before the OnEndOfData SMTP event, the sending SMTP host must generate the NDR to the message sender. After the OnEndOfData SMTP event is reached, the receiving SMTP host has accepted the full contents of the message. This means that the SMTP host now has the responsibility to successfully deliver the message and generate and send an NDR to the message sender. Therefore, it's critical that an anti-spam agent register itself on the SMTP events before the OnEndOfData SMTP event is reached to reduce the chance that the receiving SMTP host will store the message contents and have to generate an NDR to the message sender.

However, for antivirus agents, the most important consideration is to make sure that every message is scanned. Agents that must see every message must be configured on the OnSubmittedMessage SMTP event. Every message that flows through the transport pipeline encounters the OnSubmittedMessage SMTP event because it occurs after all the possible submission entry points, such as SMTP submission from remote hosts, MAPI submission from computers that are running the Mailbox server role, the Pickup directory that is used by custom applications, or the Replay directory used by third-party e-mail applications.

Return to top

Prioritization of Transport Agents

Exchange 2010 lets you specify the priority of transport agents that are included with Exchange and that are added by custom applications. If you specify the priority of a transport agent, you can control which agents act on a message first. Transport agents can be assigned a priority of 1 or higher. Transport agents with a priority closer to 1 are applied to messages first. However, the priority that you assign to a transport agent is only one factor that is used to determine the order in which transport agents are applied to messages. The second factor that is used to determine the priority of transport agents is where the SMTP event that has a registered transport agent fits within the sequence of SMTP events.

As shown in the tables earlier in this topic, SMTP events have a specific sequence in which they are applied to messages that flow through the transport pipeline. Because transport agents are registered to specific SMTP events, the priority only comes into play for agents that are registered to the same SMTP event.

For example, you may have transport agents configured as follows:

• Transport agent AgentA with a priority of 1 registered to the OnEndofHeaders SMTP event
• Transport agent AgentB with a priority of 4 registered to the OnMailCommand SMTP event

When you view the list of registered agents by using the Get-TransportAgent cmdlet, transport agent AgentA is listed with a higher priority than transport agent AgentB. However, when a message flows through the transport pipeline, transport agent AgentB will be applied to the message before transport agent AgentA because the OnMailCommand SMTP event encounters the message before the OnEndOfHeaders SMTP event.

Return to top

Built-In Transport Agents

Exchange 2010 includes several default transport agents that enable it to provide features such as transport rules and journaling. By default, the transport agents listed in the following tables are installed on Hub Transport servers and Edge Transport servers. The following tables also provide links to topics that contain more information about each agent.

Hub Transport server transport agents

Agent Name	Priority	SMTP events	Related topic
Transport Rule agent	1	OnRoutedMessage	Understanding Transport Rules
RMS Decryption agent	The priority of this agent isn't user-configurable.	OnSubmittedMessage	Understanding Information Rights Management
Journal Report Decryption agent	The priority of this agent isn't user-configurable.	OncCategorizedMessage	Understanding Journaling
RMS Encryption agent	The priority of this agent isn't user-configurable.	OnRoutedMessage	Understanding Information Rights Management
Prelicensing agent	The priority of this agent isn't user-configurable.	OnRoutedMessage	Understanding Information Rights Management
Journaling agent	The priority of this agent isn't user-configurable.	OnSubmittedMessage, OnRoutedMessage	Understanding Journaling

Edge Transport server transport agents

Agent name	Priority	SMTP events	Related topic
Connection Filtering agent	1	OnConnectEvent, OnMailCommand, OnRcptComand, OnEndOfHeaders	Understanding Connection Filtering
Address Rewriting Inbound agent	2	OnRcptCommand, OnEndOfHeaders	Understanding Address Rewriting
Edge Rule agent	3	OnEndOfData	Understanding Transport Rules
Content Filter agent	4	OnEndOfData	Understanding Content Filtering
Sender ID agent	5	OnEndOfHeaders	Understanding Sender ID
Sender Filter agent	6	OnMailCommand, OnEndOfHeaders	Understanding Sender Filtering
Recipient Filter agent	7	OnRcptCommand	Understanding Recipient Filtering
Protocol Analysis agent	8	OnEndOfHeaders, OnEndOfData, OnReject, OnRsetCommand, OnDisconnectEvent	Understanding Protocol Logging
Attachment Filtering agent	9	OnEndOfData	Understanding Attachment Filtering
Address Rewriting Outbound agent	10	OnRcptCommand, OnEndOfHeaders	Understanding Address Rewriting

Return to top

Troubleshooting Transport Agents

With transport agents, Exchange helps you control the flow of e-mail messages through your organization. This capability enables you to match your Exchange infrastructure to your organization's requirements instead of forcing your organization to match your e-mail infrastructure. As you customize your environment, the complexity of that environment increases. To help you troubleshoot issues that may occur and to help you verify that the changes that you make are applied to messages in the manner you expect, Exchange provides the following features:

• Get-TransportPipeline cmdlet   The Get-TransportPipeline cmdlet shows all the enabled transport agents, and the SMTP events on which they are registered, that have encountered messages in the transport pipeline between the time when the Microsoft Transport service was started and the time when the cmdlet was run. For more information, see View Transport Agents in the Transport Pipeline.

  Note

  The information that is displayed by the Get-TransportPipeline cmdlet is generated only after a message has been sent through the transport pipeline. Also, only the transport agents that encountered the message are displayed.

• **Pipeline Tracing **  Pipeline tracing enables you to create an exact snapshot of a whole message before and after it encounters each transport agent. Pipeline tracing enables you to determine which transport agent may have generated unexpected results or to verify that the transport agent behaves as expected.