Reading custom MAPI properties in a Transport Agent

In Exchange 2007 and 2010 all mail that is sent and received must transit its way through a Hub server where if your a developer you can create a transport agent to perform additional tasks on those messages before the are passed out of your org or into a mailbox. Sometimes these tasks may involve custom mapi properties that you may have created by using customized forms in Outlook or OWA or possibly a custom EWS application. When it comes to accessing these custom properties in a Transport Agent it involves using the TNEFReader in a transport agent to parse TNEF part of a message.

TNEF for those uninitiated stands for Transport Neutral Encapsulation Format which is a serialization format that Exchange uses to send the Mapi properties of a Item via email there is a protocol document that covers this http://msdn.microsoft.com/en-us/library/cc425498%28v=EXCHG.80%29.aspx. What the TNEFReader does is allows a Transport Agent to parse all the different property structures and data-types contained within the TNEF data stream.

One of the harder things to understand when dealing with Mapi properties is that they come in two different types. The following http://msdn.microsoft.com/en-us/library/cc979184.aspx page describes the difference between tagged properties and named properties. And there are different properties for different parts of a messages for instance there are Item properties for the Item, Recipient properties in the recipients collection for each recipients and attachment properties for each attachment. So when you are parsing an Item its not just as simple as reading one particular property collection (depending on what your trying to do).

For custom properties these should always be named properties and for the most they will use the PS_PUBLIC_STRINGS property set (but you may have created your own custom propset GUID) and either a long ID (LID) or String value for the PropertyName. This can all be confirmed using a Mapi Editor like MFCMapi or OutlookSpy to look at an item where this property has been set.

When you have gathered all this information your ready to use the property in your Transport Agent. The first thing to do when parsing a TNEF part in a transport agent is to work out at what level or properties you want to parse eg the Message properties or the attachment properties or possibly an embedded attachments properties (an Item attachment). The TNEFReader parses the properties in a forward direction to test if a property is a named property you use the

reader.PropertyReader.IsNamedProperty

If you want to check the propset GUID

reader.PropertyReader.PropertyNameId.PropertySetGuid

To see if this property is using a LID or String

reader.PropertyReader.PropertyNameId.Kind == TnefNameIdKind.Name

To demonstrate this I've put together a sample that pushes a particular custom property into a x-header which i find it useful for a number of things. I've put a download of the code here the agent looks like

using System;
using System.Collections.Generic;
using System.Text;
using System.Collections;
using System.Diagnostics;
using Microsoft.Exchange.Data.Transport;
using Microsoft.Exchange.Data.Mime;
using Microsoft.Exchange.Data.ContentTypes.Tnef;
using Microsoft.Exchange.Data.Transport.Email;
using Microsoft.Exchange.Data.Transport.Routing;
using Microsoft.Exchange.Data.Common;
using System.IO;
using Microsoft.Win32;
using System.Reflection;

namespace ExchangeRoutingAgents
{
public class MapiPropAgentFactory : RoutingAgentFactory
{
public override RoutingAgent CreateAgent(SmtpServer server)
{
RoutingAgent mpAgent = new MapiPropAgent();
return mpAgent;
}
}
}

public class MapiPropAgent : RoutingAgent
{
public MapiPropAgent()
{
this.OnRoutedMessage += new RoutedMessageEventHandler(MapiPropAgent_OnRoutedMessage);
}
void MapiPropAgent_OnRoutedMessage(RoutedMessageEventSource esEvtsource, QueuedMessageEventArgs qmQueuedMessage)
{
String myPropString = "myExtraInfo";
MimePart tnefPart = qmQueuedMessage.MailItem.Message.TnefPart;
if (tnefPart != null)
{
//Check the Mimeheader to see if the X-header exists
MimeDocument mdMimeDoc = qmQueuedMessage.MailItem.Message.MimeDocument;
HeaderList hlHeaderlist = mdMimeDoc.RootPart.Headers;
Header myPropHeader = hlHeaderlist.FindFirst(myPropString);
TnefReader reader = new TnefReader(tnefPart.GetContentReadStream(), 0, TnefComplianceMode.Loose);
while (reader.ReadNextAttribute())
{
//Find Message Level TNEF attributes
if (reader.AttributeTag == TnefAttributeTag.MapiProperties)
{

while (reader.PropertyReader.ReadNextProperty())
{
if (reader.PropertyReader.IsNamedProperty)
{
if (reader.PropertyReader.PropertyNameId.Name == myPropString)
{

String myPropStringValue = reader.PropertyReader.ReadValueAsString();
if (myPropHeader == null)
{
MimeNode lhLasterHeader = hlHeaderlist.LastChild;
TextHeader nhNewHeader = new TextHeader(myPropString, myPropStringValue);
hlHeaderlist.InsertBefore(nhNewHeader, lhLasterHeader);
lhLasterHeader = null;
nhNewHeader = null;
}
}
}

}

}
}
reader.Dispose();
}


}


}