Applies to: Exchange Server 2007 SP3, Exchange Server 2007 SP2, Exchange Server 2007 SP1, Exchange Server 2007
Topic Last Modified: 2007-07-17

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 2007. 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 2007, 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 2007. However, there may be instances where organizations want to develop their own transport agents to manage mail that flows through their Exchange 2007 organization.

Caution:
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.

For information about how to write a new transport agent, see Transport Agents in the "Microsoft Exchange Server 2007 SDK Documentation."

For more information about the transport pipeline in Exchange 2007, see Transport Architecture.

Transport Agents and SMTP Events

Transport agents that are written for Exchange 2007 use Simple Mail Transfer Protocol (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. Table 1 lists the SMTP events that provide access to messages in the transport pipeline:

Table 1   SMTP events

Sequence SMTP event Description

1

OnConnectEvent

This event is triggered upon initial connection from a remote SMTP host.

2

OnHeloCommand

This event is triggered when the HELO SMTP verb is issued by the remote SMTP host.

3

OnEhloCommand

This event is triggered when the EHLO 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

OnRcptCommand

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>.<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 OnConnectEvent SMTP event and before the OnDisconnectEvent 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 OnConnectEvent SMTP event and before the OnDisconnectEvent 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 OnConnectEvent SMTP event and before the OnDisconnectEvent 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 OnConnectEvent SMTP event and before the OnDisconnectEvent SMTP event.

11

OnDisconnectEvent

This event is triggered upon disconnection of the SMTP conversation by either a receiving or sending SMTP host.

12

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.

13

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.

Note:
The OnResolvedMessage routing event is available only in Exchange 2007 Service Pack 1 (SP1).

14

OnRoutedMessage

This event is triggered after messages have been categorized, distribution lists have been expanded, and recipients have been resolved.

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

For anti-spam 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 are not 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.

Prioritization of Transport Agents

Exchange 2007 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 Table 1 earlier in this topic, SMTP events have a specific sequence in which they are applied to messages that flow through the transport pipeline. For example, the OnConnectEvent SMTP event always occurs before the OnHeloCommand or OnEhloCommand SMTP events. Because transport agents are registered to specific SMTP events, this means that regardless of the priority that is assigned to a transport agent on the OnEhloCommand SMTP event, transport agents registered on the OnConnectEvent SMTP event will always be applied to messages first.

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 your 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.

The priority that you assign a transport agent becomes relevant when two or more transport agents are registered on the same SMTP event. If transport agent AgentA and transport agent AgentB are both registered on the OnEndofHeaders SMTP event, when a message encounters that event, transport agent AgentA is applied to the message before transport agent AgentB. If transport agent AgentB is registered on both the OnEndOfHeaders and OnMailCommand SMTP events, it will be applied to the message two times. Transport agent AgentB will be applied first, because it is registered to the OnMailCommand SMTP event. Then, when the message encounters the OnEndOfHeaders SMTP event where both transport agent AgentA and transport agent AgentB are registered, transport agent AgentA will be applied because it has a higher priority than transport agent AgentB. Finally, transport agent AgentB will be applied for the second time.

Built-In Transport Agents

Exchange 2007 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 to topics that contain more information about each agent.

Table 2   Hub Transport server transport agents

Agent Name Priority SMTP events Description

Transport Rule agent

1

OnRoutedMessage

Overview of Transport Rules

Journaling agent

2

OnSubmittedMessage, OnRoutedMessage

Overview of Journaling

Active Directory Rights Management Services (AD RMS) Prelicensing agent

Note:
The AD RMS Prelicensing agent is available only in Exchange 2007 SP1. It is disabled by default.

3

OnRoutedMessage

Understanding the AD RMS Prelicensing Agent

Table 3   Edge Transport server transport agents

Agent name Priority SMTP events Related Topic

Connection Filtering agent

1

OnConnectEvent, OnMailCommand, OnRcptComand, OnEndOfHeaders

Connection Filtering

Address Rewriting Inbound agent

2

OnRcptCommand, OnEndOfHeaders

Planning for Address Rewriting

Edge Rule agent

3

OnEndOfData

Overview of Transport Rules

Content Filter agent

4

OnEndOfData

Content Filtering

Sender ID agent

5

OnEndOfHeaders

Sender ID

Sender Filter agent

6

OnMailCommand, OnEndOfHeaders

Sender Filtering

Recipient Filter agent

7

OnRcptCommand

Recipient Filtering

Protocol Analysis agent

8

OnEndOfHeaders, OnEndOfData, OnReject, OnRsetCommand, OnDisconnectEvent

Managing Protocol Logging

Attachment Filtering agent

9

OnEndOfData

Attachment Filtering

Address Rewriting Outbound agent

10

OnRcptCommand, OnEndOfHeaders

Planning for Address Rewriting

Troubleshooting Transport Agents

With transport agents, Exchange helps you control the flow of e-mail messages through your organization. This 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 gives you the following features:

  • Get-TransportPipeline cmdlet   The Get-TransportPipeline cmdlet shows all the enabled transport agents, and those 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 How to 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. For more information, see Using Pipeline Tracing to Diagnose Transport Agent Problems.

For More Information

For more information about transport agents, see the following topics: