Rebex MSG

Outlook MSG file format library for .NET

Download 30-day free trial Buy from $199
More .NET components

Back to feature list...

MAPI properties

This API is provided by Rebex.Msg.dll assembly.

MAPI property IDs 

Outlook .MSG files contain three kinds of MAPI properties:

  • Tagged properties - identified by a tag (MsgPropertyTag enum).
  • Numerical named properties - with numerical identifier (MsgPropertyId and MsgPropertySet enums).
  • String named properties - with string identifier (string and MsgPropertySet enum).
// load an MsgMessage
// ...

// display all MAPI properties of the MSG message
foreach (MsgProperty prop in message.Properties)
    switch (prop.Kind)
        case MsgPropertyKind.Tagged:
            Console.WriteLine("Tagged: {0}", prop.Tag);
        case MsgPropertyKind.NumericalNamed:
            Console.WriteLine("Numerical: {0}", prop.Id);
        case MsgPropertyKind.StringNamed:
            Console.WriteLine("String: {0}", prop.Name);

// get a 'Tagged' property
MsgProperty subject = message.Properties[MsgPropertyTag.Subject];

// get a 'Numerical-named' property
MsgProperty account = message.Properties[MsgPropertyId.InternetAccountName];

// get a 'String-named' property
MsgProperty contentType = message.Properties["content-type"];
' load an MsgMessage
' ...

' display all MAPI properties of the MSG message
For Each prop As MsgProperty In message.Properties

    Select Case prop.Kind
        Case MsgPropertyKind.Tagged
            Console.WriteLine("Tagged: {0}", prop.Tag)
        Case MsgPropertyKind.NumericalNamed
            Console.WriteLine("Numerical: {0}", prop.Id)
        Case MsgPropertyKind.StringNamed
            Console.WriteLine("String: {0}", prop.Name)
    End Select

' get a 'Tagged' property
Dim subject As MsgProperty = message.Properties(MsgPropertyTag.Subject)

' get a 'Numerical-named' property
Dim account As MsgProperty = message.Properties(MsgPropertyId.InternetAccountName)

' get a 'String-named' property
Dim contentType As MsgProperty = message.Properties("content-type")
Numerical named properties and string named properties are identified by MsgPropertySet in addition to their primary identifiers (MsgPropertyId or string). However, it is uncommon for a MSG message to contain more than one property identified by the same primary identifier from two different property sets. Therefore, the API is simplified to address properties by the primary identifier only. In case there are more properties using the same primary identifier, only a property from one property set is returned.

MAPI property data types 

MAPI properties are of various data types defined by MsgPropertyDataType enum (which corresponds to [MS-OXCDATA] specification). The particular data type of a MAPI property can be determined using MsgProperty.DataType property.

MsgProperty.Value returns and accepts an instance of object, but it can be safely casted to a strongly-typed value based on MsgProperty.DataType property.

When setting MsgProperty.Value the type of the value must correspond to the type specified by MsgProperty.DataType property.

To replace a property, use MsgPropertyCollection.SetValue<T>() method as shown in Getting and setting values section.
// load an MsgMessage
// ...

// get the 'Subject' property
MsgProperty subjectProp = message.Properties[MsgPropertyTag.Subject];
if (subjectProp == null)
    throw new InvalidDataException("Subject not found.");

// get the property value based on its data type
string subject;
switch (subjectProp.DataType)
    case MsgPropertyDataType.String:
    case MsgPropertyDataType.String8:
        subject = (string)subjectProp.Value;
    case MsgPropertyDataType.Binary:
        subject = Encoding.UTF8.GetString((byte[])subjectProp.Value);
        throw new InvalidDataException("Subject data format is unknown.");
' load an MsgMessage
' ...

' get the 'Subject' property
Dim subjectProp As MsgProperty = message.Properties(MsgPropertyTag.Subject)
If subjectProp Is Nothing Then
    Throw New InvalidDataException("Subject not found.")
End If

' get the property value based on its data type
Dim subject As String

Select Case subjectProp.DataType
    Case MsgPropertyDataType.String, MsgPropertyDataType.String8
        subject = CStr(subjectProp.Value)
    Case MsgPropertyDataType.Binary
        subject = Encoding.UTF8.GetString(CType(subjectProp.Value, Byte()))
    Case Else
        Throw New InvalidDataException("Subject data format is unknown.")
End Select

Getting and setting values 

To add, update or delete a MAPI property, use MsgPropertyCollection.SetValue<T>() method. To delete a property, specify the value argument of null (Nothing in VB.NET).

To read a value of a MAPI property, use one of the three methods:

  • MsgPropertyCollection.GetValue<T>(identifier) - fails if the property does not exist or has data type other than specified by the generic type parameter <T>.
  • MsgPropertyCollection.GetValue<T>(identifier, defaultValue) - returns defaultValue if the property does not exist, but still fails if data type is mismatched.
  • MsgPropertyCollection.TryGetValue<T>(identifier, out value) - safely assigns the value argument and returns true; returns false if the value argument cannot be assigned (either the property does not exists or data type is mismatched).
// load an MsgMessage
// ...

// get the value of 'Subject' property
string subject = message.Properties.GetValue<string>(MsgPropertyTag.Subject);

// set a new 'Subject' property value
message.Properties.SetValue(MsgPropertyTag.Subject, "New subject");
' load an MsgMessage
' ...

' get the value of 'Subject' property
Dim subject As String = message.Properties.GetValue(Of String)(MsgPropertyTag.Subject)

' set a new 'Subject' property value
message.Properties.SetValue(MsgPropertyTag.Subject, "New subject")

Back to feature list...