Introduction to MAPI Message Files API

MAPI Message Files

Aspose.Email Cloud supports files in Microsoft Outlook Email format (MSG files).

First of all, the MSG file could be represented as a list of properties. See this JSON example:

MSG file properties list represented as a JSON array
{
  "properties": [
    {
      "value": "High",
      "descriptor": {
        "name": "Importance",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiImportancePropertyDto"
    },
    {
      "value": "IPM.Note",
      "descriptor": {
        "name": "MessageClass",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "value": 0,
      "descriptor": {
        "name": "Sensitivity",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiIntPropertyDto"
    },
    {
      "value": "Re: Some subject",
      "descriptor": {
        "name": "TagSubject",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "valueBase64": "U01UUDpGUk9NQEFTUE9TRS5DT00A",
      "descriptor": {
        "name": "SentRepresentingSearchKey",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiBinaryPropertyDto"
    },
    {
      "value": "Re: ",
      "descriptor": {
        "name": "SubjectPrefix",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "value": "From Address <from@aspose.com>",
      "descriptor": {
        "name": "SentRepresentingName",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "value": null,
      "descriptor": {
        "name": "SentRepresentingAddressType",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "value": "from@aspose.com",
      "descriptor": {
        "name": "SentRepresentingEmailAddress",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "value": "From: \"From Address\" <from@aspose.com>\r\nReply-To: \r\nTo: \"To Address\" <to@aspose.com>\r\nBcc: \r\nCc: \r\nPriority: urgent\r\nX-Priority: High\r\nImportance: High\r\nSensitivity: None\r\nSubject: Re: Some subject\r\nDate: Mon, 1 Jan 1 00:00:00 +0000\r\nX-Unsent: 1\r\nDisposition-Notification-To: \r\nMIME-Version: 1.0\r\n\r\n",
      "descriptor": {
        "name": "TransportMessageHeaders",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "valueBase64": "AAAAAIErH6S+oxAZnW4A3QEPVAIAAAGAZgByAG8AbQBAAGEAcwBwAG8AcwBlAC4AYwBvAG0AAABTAE0AVABQAAAAZgByAG8AbQBAAGEAcwBwAG8AcwBlAC4AYwBvAG0AAAA=",
      "descriptor": {
        "name": "SenderEntryId",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiBinaryPropertyDto"
    },
    {
      "value": "From Address",
      "descriptor": {
        "name": "SenderName",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "valueBase64": "U01UUDpGUk9NQEFTUE9TRS5DT00A",
      "descriptor": {
        "name": "SenderSearchKey",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiBinaryPropertyDto"
    },
    {
      "value": "SMTP",
      "descriptor": {
        "name": "SenderAddressType",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "value": "from@aspose.com",
      "descriptor": {
        "name": "SenderEmailAddress",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "value": null,
      "descriptor": {
        "name": "DisplayBcc",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "value": null,
      "descriptor": {
        "name": "DisplayCc",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "value": "To Address",
      "descriptor": {
        "name": "DisplayTo",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "value": 25,
      "descriptor": {
        "name": "MessageFlags",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiIntPropertyDto"
    },
    {
      "value": true,
      "descriptor": {
        "name": "HasAttachments",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiBooleanPropertyDto"
    },
    {
      "value": "Some subject",
      "descriptor": {
        "name": "NormalizedSubject",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "value": true,
      "descriptor": {
        "name": "RtfInSync",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiBooleanPropertyDto"
    },
    {
      "value": 2,
      "descriptor": {
        "name": "Access",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiIntPropertyDto"
    },
    {
      "value": 0,
      "descriptor": {
        "name": "AccessLevel",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiIntPropertyDto"
    },
    {
      "value": "Some body",
      "descriptor": {
        "name": "Body",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    {
      "valueBase64": "/QAAAP0AAABNRUxBAAAAAHtccnRmMVxhbnNpXGFuc2ljcGcxMjUyXGZyb21odG1sMSBcZmJpZGlzIFxkZWZmMHtcZm9udHRibA0Ke1xmMFxmc3dpc3MgQXJpYWw7fX0NCntcY29sb3J0YmxccmVkMFxncmVlbjBcYmx1ZTA7fQ0KXHVjMVxwYXJkXHBsYWluXGRlZnRhYjM2MCBcZjBcZnMyNA0Ke1wqXGh0bWx0YWc4NCA8Yj59XGh0bWxydGYge1xiIFxodG1scnRmMCBTb21lIGJvZHkNCntcKlxodG1sdGFnOTIgPC9iPn1caHRtbHJ0ZiB9XGh0bWxydGYwIH0=",
      "descriptor": {
        "name": "RtfCompressed",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiBinaryPropertyDto"
    },
    {
      "valueBase64": "PGI+U29tZSBib2R5PC9iPg==",
      "descriptor": {
        "name": "TagHtml",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiBinaryPropertyDto"
    },
    {
      "value": "2020-07-07T13:07:10.7317118Z",
      "descriptor": {
        "name": "CreationTime",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiDateTimePropertyDto"
    },
    {
      "value": "2020-07-07T13:07:10.7317118Z",
      "descriptor": {
        "name": "LastModificationTime",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiDateTimePropertyDto"
    },
    {
      "valueBase64": "zuEv0QAAAAAAAAAAAAAAAA==",
      "descriptor": {
        "name": "SearchKey",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiBinaryPropertyDto"
    },
    {
      "value": 134777,
      "descriptor": {
        "name": "StoreSupportMask",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiIntPropertyDto"
    },
    {
      "value": 65001,
      "descriptor": {
        "name": "InternetCodepage",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiIntPropertyDto"
    },
    {
      "value": false,
      "descriptor": {
        "name": "AgingDontAgeMe",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiBooleanPropertyDto"
    }
  ]
}

These properties could contain different values. It could be integers, strings, bytes, multiple strings, and a lot of other data types. All properties are identified using property Descriptors. Aspose.Email Cloud supports different types of property descriptors:

  • MapiPidTagPropertyDescriptor - A property, identified by a tag, which consists of a combination of data type and identifier.
  • MapiPidLidPropertyDescriptor - A property, identified by a long id and a property set.
  • MapiPidNamePropertyDescriptor - A property, identified by a name and a property set.
  • MapiKnownPropertyDescriptor - This descriptor implies one of three previous descriptors. It is a property, that is known to Aspose.Email Cloud, so it can be fully identified by the property name. See all known properties here.

Aspose.Email Cloud provides 3 different models to represent the MSG file. These models contain a list of all properties and extra fields for easier file operation. For example, MapiMessageDto has a string field named Subject, which contains a subject for an email message. But this field is just a copy of a property with a TagSubject descriptor:

Part of MapiMessageDto JSON with subject
{
  //...
  "subject": "Re: Some subject",
  //...
  "properties": [
    //...
    {
      "value": "Re: Some subject",
      "descriptor": {
        "name": "TagSubject",
        "discriminator": "MapiKnownPropertyDescriptor"
      },
      "discriminator": "MapiStringPropertyDto"
    },
    //...
  ],
  //...
}

These 3 MAPI models are:

  1. MapiMessageDto - represents an email message. Has properties to represent a message’s subject, body, sender, recipients, etc.
  2. MapiCalendarDto - represents an appointment or a meeting object. Provides properties for meeting start and end, location, recurrence, busy status, etc.
  3. MapiContactDto - represents a contact. Provides properties for name, telephone, email addresses, etc.

All these models can be converted to the corresponding usual models and back:

Aspose.Email Cloud also provides methods to save these models to files in different formats and to read these files back to the corresponding models.

Quick start with MAPI message files API

Aspose.Email Cloud SDK provides the same sets of methods for all supported MAPI models:

  • Convert from the usual model to a MAPI model.
  • Convert from the MAPI model to a usual model.
  • Convert a MAPI model object to a file in a specified format.
  • Read a file to a MAPI model.
  • Save a MAPI model as a file on the cloud storage.
  • Read a file from the cloud storage to a MAPI model.

You can see all these methods in action in examples below:

MapiMessageDto methods

Convert EmailDto to MapiMessageDto