Saturday, April 02, 2011

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();
}


}


}

6 comments:

Anonymous said...

Dear Glen,

using your code as a base, I've tried to get all named properties. Unfortunately it allows me to retrieve only 2 named properties but OutlookSpy shows about 10 ones. I'm trying to get 0x85b5 and 0x85b6 ({00062008-0000-0000-C000-000000000046}) named properties that tied with message classifictaion.

Could you help please?

Thanks in advance,
Victor Ivanidze

Glen said...

Hi Victor

The categorization Mapi properties aren't transmitted the Sending Client converts them to X-headers as per http://207.46.16.248/en-us/library/ee217686%28EXCHG.80%29.aspx so what you will see in the Message is generally one x-header x-ms-exchange-organization-classification with the GUID of the message classification. This is done to stop cross org pollution

Cheers
Glen

Anonymous said...

Dear Glen,

thanks for your answer, but I'm still a bit discouraged.

Look: in OWA you create a test message to yourself, assign classifictaion and send it. Do you mean that the message recieved will contain x-ms-exchange-organization-classification header?
My test message hasn't got such header.

Do you know a technique that could retrieve the message classification info in a transport agent?

Thanks again and regards,
Victor

Glen said...

Hi Victor

Have you tried this in a Transport Agent? When i try it i see the X-header for the classification guid and no Mapi properties for classification. When the message arrives in a mailbox it doesn't have the X-header but the Mapi properties are reconstituted.

Cheers
Glen

Victor Ivanidze said...

Thank you so much, Glen!

I've figured it out with your help.
Much appreciated.


Another question:

I'm trying to reproduce
"Remove Read Access from Message Classifications" (http://technet.microsoft.com/en-us/library/ee861105.aspx)
It just doesn't work on my Exchange 2010 SP1. Have you ever tried to follow their instructions?

Regards,
Victor

Anonymous said...

Hi Glen,

Have hit a roadblock trying to repurpose your script. Need to get the Send-As MAPI property (0x5D09001E), append it as a X Header through a transport agent. Unfortunately, the attribute has only a tag, no propertyname. Can this be done using your script?

Also, for some reason, I find that reader.PropertyReader.IsNamedProperty is False when i send simple messages between Exchange users. Any reason why?

Thanks,
Sunil