About: Exchange Transport Agents

  • Article

API Interface: .NET and in process with Exchange transport.

Business Logic: Access and modify messages in Exchange transport.

Language Support: .NET

Direct Property Access:   Can access and change the content of messages in transport.

Product Versions: Exchange 2007+

Summary:

As mail flows through Exchange SMTP transport an Exchange transport agent can look at the stream and modify. Note that this only works with on premise Exchange servers and not Exchange Online.  The events it works off of fire on messages before a message arrives in a mailbox and after its submitted.  These agents are built with custom .NET code.

Points of Interest:

  • Agents need to be registered on the Exchange server and run in process.
  • Shared Exchange Online cannot have transport agents registered on them as you need special permissions and access to the server to do so. 
  • If you are running under a network service account and are wanting to log traffic to the application event log then be careful because permission to registry keys will be need to be added for that account otherwise you will get an error.
  • Avoid writing to the application vent log - especially upon events which fire on each message.  An example is having code fire on the agents object creation, which fires every time a message goes through the agent. The Application log is ill suited for such a large volume of entries and logging may have a significant impact on performance.  Its far better to write to a custom event log such a file or database.
  • Follow the rules of having code be as lean and fast and stable as possible. This is email transport code and it needs to be able to handle a lot of content.
  • Consider adding an application configuration file with a setting which turns on and off logging.
  • Use Procmon to determine where file/registry permission/access issues are if you run into them. Be sure to filter down to your application. 
  • Be sure to use the correct version of .NET. Remember that a transport agent DLL runs in process with Exchange.  Each version of Exchange is built and tested with a certain version of .NET and your application should match that version.
  • Knowing how to connect a debugger for debugging the agent.  A lot of developers spend a lot of time trying to debug without doing this and end up burning a lot of time. Also consider doing testing on a test server, such as an edge server which is used only for development and testing - it will be a big plus in writing, debugging and testing. 

Further Reading:

Transport agents in Exchange 2013
https://msdn.microsoft.com/en-us/library/office/dd877026(v=exchg.150).aspx

Reading and modifying messages in the Exchange 2013 transport pipeline
https://msdn.microsoft.com/en-us/library/office/aa579261(v=exchg.150).aspx

Creating transport agents for Exchange 2013
https://msdn.microsoft.com/en-us/library/office/bb204097(v=exchg.150).aspx

Transport agents in Exchange 2013
https://msdn.microsoft.com/en-us/library/office/dd877026(v=exchg.150).aspx

How to write an Exchange 2013 transport agent
https://blogs.technet.com/b/exchange/archive/2013/01/21/how-to-write-an-exchange-2013-transport-agent.aspx 

Understanding Transport Agents (2010)
https://technet.microsoft.com/en-us/library/bb125012(v=exchg.141).aspx

Transport Agents (2010)
https://msdn.microsoft.com/en-us/library/office/Aa579185(v=EXCHG.140).aspx

View or Configure a Transport Agent (2010)
https://technet.microsoft.com/en-us/library/Aa997996(v=EXCHG.141).aspx

Samples:

Transport agent code samples for Exchange 2013
https://msdn.microsoft.com/en-us/library/office/dd877105(v=exchg.150).aspx

Transport Agent Development Solutions (Exchange 2010 samples)
https://msdn.microsoft.com/en-us/library/office/dd877105(v=exchg.140).aspx

StripIncomingLinkAgent sample Exchange 2010 transport agent
https://code.msdn.microsoft.com/StripIncomingLinkAgent-7004255d#content
Note that this sample writes to the application event log.  Also note that all sample code is just that - a sample.  This means that when you use a sample code such as this you are to make it your own and understand the code.  Microsoft does provide support for sample code.

HOW TO:Rewrite the To address in Transport Agents on a Hub Server
https://blogs.msdn.com/b/akashb/archive/2009/02/24/how-to-rewrite-the-to-address-in-transport-agents-on-a-hub-server.aspx

Body Conversion Sample Application
https://msdn.microsoft.com/en-us/library/office/Bb204066(v=EXCHG.140).aspx

Also see:

About: Messaging APIs
https://blogs.msdn.com/b/webdav_101/archive/2015/08/07/about-messaging-apis.aspx 

Process Monitor v3.2  (Procmon)
https://technet.microsoft.com/en-us/Library/bb896645.aspx
This is helpful for fining where registry and folder access issues are.