Documentation – Working with OLM Files

Net: Opening OLM Files

Mon, 01 Jan 0001 00:00:00 +0000

Aspose.Email for .NET represents an Outlook for Mac storage file with the OlmStorage class. This article shows how to open an OLM file from a path or a stream, and how to safely load a file that may be corrupted.

Open an OLM File

An OLM file can be opened in two ways:

using a constructor;
using the static FromFile method.

There is a difference in behavior between these two approaches that affects how the folder hierarchy is initialized. See Navigating OLM Folders for details.

Using the Constructor

To open a file, call the constructor of the OlmStorage class and pass the full file name as an argument. Because OlmStorage implements IDisposable, wrap it in a using statement so that the underlying file handle is released when you are done.

var fileName = "MyStorage.olm";
using (var olm = new OlmStorage(fileName))
{
    // work with the storage
}

Using the Static FromFile Method

To open a file, use the static FromFile method and pass the full file name as an argument:

var fileName = "MyStorage.olm";
using (var olm = OlmStorage.FromFile(fileName))
{
    // work with the storage
}

Open an OLM File from a Stream

When the OLM data does not come from a local path - for example, it is received from a database, a network resource, or cloud storage - you can open it directly from a Stream. Use the OlmStorage(Stream) constructor or the static FromStream method.

using (var stream = File.OpenRead("MyStorage.olm"))
using (var olm = new OlmStorage(stream))
{
    // work with the storage
}

The static method works the same way:

using (var stream = File.OpenRead("MyStorage.olm"))
using (var olm = OlmStorage.FromStream(stream))
{
    // work with the storage
}

Keep the source stream open for as long as you access the storage. Disposing the stream before you finish reading folders and messages will cause read errors.

Open a Corrupted OLM File

If a file may be partially corrupted, you can still extract as much data as possible without stopping on the first error. To do this, create the OlmStorage instance with the OlmStorage(TraversalExceptionsCallback callback) constructor, then load the file with the Load method instead of FromFile.

The callback receives the exceptions raised during loading and traversal, so you can log or ignore them. The Load method returns true if the file was loaded successfully and traversal is possible, and false if the file is too corrupted to traverse.

using (var olm = new OlmStorage((exception, id) =>
{
    // Exception handling code.
    Console.WriteLine($"Failed to process item '{id}': {exception.Message}");
}))
{
    if (olm.Load(fileName))
    {
        // The file was loaded and can be traversed.
        var folderHierarchy = olm.GetFolders();
    }
    else
    {
        Console.WriteLine("The OLM file is corrupted and cannot be traversed.");
    }
}

For a complete example of extracting items from a corrupted file, see Reading and Extracting OLM Messages.

Net: Navigating OLM Folders

Mon, 01 Jan 0001 00:00:00 +0000

An OLM file organizes its data into a tree of folders, each represented by an OlmFolder object. This article shows how to enumerate the folder hierarchy, retrieve a specific folder by name, navigate sub-folders, and read folder paths.

Retrieve the Folder Hierarchy

Once a file is open, access its directory structure through the FolderHierarchy property. This property returns a list of OlmFolder objects, each representing a top-level directory in the OLM file. To explore deeper, read the SubFolders property of each folder, which returns its sub-directories. Using these two members you can walk the entire hierarchy.

The example below prints all folders in hierarchical order:

using (var olm = new OlmStorage(fileName))
{
    PrintAllFolders(olm.FolderHierarchy, string.Empty);
}

private void PrintAllFolders(IEnumerable<OlmFolder> folderHierarchy, string indent)
{
    foreach (var folder in folderHierarchy)
    {
        Console.WriteLine($"{indent}{folder.Name}");
        PrintAllFolders(folder.SubFolders, indent + "-");
    }
}

FolderHierarchy and the FromFile Method

The way you open the file affects how FolderHierarchy behaves:

When you open the file with the constructor, the FolderHierarchy property is initialized automatically.
When you open the file with the FromFile method, FolderHierarchy is not initialized by default and returns null. In this case, call the GetFolders method explicitly to initialize the hierarchy and retrieve the list of directories:

using (var olm = OlmStorage.FromFile(fileName))
{
    var folders = olm.GetFolders();
}

Get a Folder by Name

To retrieve a single folder by name, call the GetFolder method. Pass the folder name as the first argument and a boolean as the second argument that indicates whether case should be ignored during the search.

using (var olm = OlmStorage.FromFile(fileName))
{
    // get the Inbox folder by name, ignoring case
    OlmFolder folder = olm.GetFolder("Inbox", true);
}

Get a Sub-folder by Name

Each OlmFolder also lets you locate a child folder directly with the GetSubFolder method. Pass the sub-folder name and whether case should be ignored. This is useful when you already hold a parent folder and want to drill down without re-scanning the whole hierarchy.

using (var olm = OlmStorage.FromFile(fileName))
{
    OlmFolder inbox = olm.GetFolder("Inbox", true);

    // get a sub-folder of Inbox by name
    OlmFolder archive = inbox.GetSubFolder("Archive", true);

    if (archive != null)
    {
        Console.WriteLine($"Found sub-folder: {archive.Name}");
    }
}

Retrieve Folder Paths

You can read the full path of any folder through the OlmFolder.Path property. The following snippet prints the path of every folder in the file:

using (var storage = new OlmStorage("SampleOLM.olm"))
{
    PrintPath(storage.FolderHierarchy);
}

public static void PrintPath(IEnumerable<OlmFolder> folders)
{
    foreach (OlmFolder folder in folders)
    {
        // print the current folder path
        Console.WriteLine(folder.Path);

        PrintPath(folder.SubFolders);
    }
}

Net: Reading and Extracting OLM Messages

Mon, 01 Jan 0001 00:00:00 +0000

After you open an OLM file and locate a folder, you can list its messages, read short message information, filter and page through large folders, and extract individual messages as MapiMessage objects. This article covers all of these operations.

List Messages in a Folder

The OlmFolder class provides two ways to iterate over the messages it contains:

EnumerateMessages returns an OlmMessageInfo object on each iteration. This object holds short information about the message and is the most efficient way to scan a folder.
EnumerateMapiMessages returns a full MapiMessage object on each iteration, with all of the message’s properties loaded.

Using EnumerateMessages

using (var olm = OlmStorage.FromFile(fileName))
{
    var folder = olm.GetFolder("Inbox", true);
    foreach (var messageInfo in folder.EnumerateMessages())
    {
        Console.WriteLine(messageInfo.Subject);
    }
}

Using EnumerateMapiMessages

using (var olm = OlmStorage.FromFile(fileName))
{
    var folder = olm.GetFolder("Inbox", true);

    foreach (var msg in folder.EnumerateMapiMessages())
    {
        // save the message in MSG format
        msg.Save($"{msg.Subject}.msg");
    }
}

Read Message Information

Each OlmMessageInfo object exposes a set of read-only properties that describe a message without loading its full contents. This is the most efficient way to build a list view or to decide which messages to extract.

Property	Description
Subject	The message subject.
From	The sender address.
To	The collection of recipient addresses.
Date	The date of the message.
ModifiedDate	The date the message was last modified.
HasAttachments	Indicates whether the message has attachments.
MessageClass	The sender-defined message class, such as `IPM.Note`.
EntryId	The message entry identifier.

using (var olm = OlmStorage.FromFile(fileName))
{
    var folder = olm.GetFolder("Inbox", true);

    foreach (OlmMessageInfo messageInfo in folder.EnumerateMessages())
    {
        Console.WriteLine($"Subject: {messageInfo.Subject}");
        Console.WriteLine($"From: {messageInfo.From}");
        Console.WriteLine($"To: {string.Join("; ", messageInfo.To)}");
        Console.WriteLine($"Date: {messageInfo.Date}");
        Console.WriteLine($"Modified: {messageInfo.ModifiedDate}");
        Console.WriteLine($"Has attachments: {messageInfo.HasAttachments}");
        Console.WriteLine($"Message class: {messageInfo.MessageClass}");
        Console.WriteLine(new string('-', 30));
    }
}

Get the Modified Date of a Message

The modified date represents the date and time when the OLM message was last modified. Use the OlmMessageInfo.ModifiedDate property to read it:

foreach (OlmMessageInfo messageInfo in inboxFolder.EnumerateMessages())
{
    DateTime modifiedDate = messageInfo.ModifiedDate;
}

Filter Messages with a Query

For large folders, you can retrieve only the messages that match a set of criteria instead of iterating over everything. Pass a MailQuery to the EnumerateMessages(MailQuery query) overload. Build the query with a MailQueryBuilder.

The example below enumerates only the messages received during the last seven days whose subject contains the word “Invoice”:

using (var olm = OlmStorage.FromFile(fileName))
{
    var folder = olm.GetFolder("Inbox", true);

    var builder = new MailQueryBuilder();
    builder.InternalDate.Since(DateTime.Now.AddDays(-7));
    builder.Subject.Contains("Invoice");
    MailQuery query = builder.GetQuery();

    foreach (var messageInfo in folder.EnumerateMessages(query))
    {
        Console.WriteLine(messageInfo.Subject);
    }
}

Page Through Messages

When a folder contains a large number of messages, you can read them in batches with the EnumerateMessages(int skip, int count) overload. The skip parameter is the number of messages to bypass, and count is the number of messages to return.

using (var olm = OlmStorage.FromFile(fileName))
{
    var folder = olm.GetFolder("Inbox", true);

    const int pageSize = 50;
    int pageIndex = 0;

    while (true)
    {
        var page = folder.EnumerateMessages(pageIndex * pageSize, pageSize).ToList();
        if (page.Count == 0)
        {
            break;
        }

        foreach (var messageInfo in page)
        {
            Console.WriteLine(messageInfo.Subject);
        }

        pageIndex++;
    }
}

Extract a Message as a MapiMessage

The OlmStorage class provides the ExtractMapiMessage method, which extracts a full MapiMessage from an OlmMessageInfo object. This is useful when you first scan a folder with EnumerateMessages and then extract only the messages you actually need.

using (var olm = OlmStorage.FromFile(fileName))
{
    var folder = olm.GetFolder("Inbox", true);

    foreach (var messageInfo in folder.EnumerateMessages())
    {
        if (messageInfo.Date.Date == DateTime.Today)
        {
            // extract today's messages from Inbox
            var msg = olm.ExtractMapiMessage(messageInfo);
            msg.Save($"{msg.Subject}.msg");
        }
    }
}

Extract Messages by Identifier

Sometimes you need to extract selected messages by their identifiers. For example, an application can store identifiers in a database and extract a message on demand instead of traversing the entire storage each time. The EntryId property of OlmMessageInfo provides the message entry identifier, and the overloaded ExtractMapiMessage(string id) method retrieves the message by that identifier.

using (var olm = OlmStorage.FromFile(fileName))
{
    var olmFolder = olm.GetFolder("Inbox", true);

    foreach (OlmMessageInfo msgInfo in olmFolder.EnumerateMessages())
    {
        // store msgInfo.EntryId somewhere, then later:
        MapiMessage msg = olm.ExtractMapiMessage(msgInfo.EntryId);
    }
}

Extract Items Using the Traversal API

You can extract every item from an OLM file - as far as possible - without throwing exceptions, even when some data in the original file is corrupted. To do this, create the OlmStorage instance with the OlmStorage(TraversalExceptionsCallback callback) constructor and load the file with the Load method. The callback exposes the loading and traversal exceptions.

The Load method returns true if the file was loaded successfully and traversal is possible, and false if the file is corrupted and no traversal is possible. Note that when traversing items folder by folder, you call the storage’s EnumerateMessages(OlmFolder folder) method, passing the folder as an argument.

The steps are:

Create a new OlmStorage instance, passing an exception-handling callback.
Load the OLM file by calling the Load method.
If the file loads successfully, obtain the folder hierarchy by calling GetFolders.
Recursively iterate over each folder. For folders that have messages, enumerate them with the storage’s EnumerateMessages method and process each one.
Recurse into any sub-folders.

using (var olm = new OlmStorage((exception, id) => { /* Exception handling code. */ }))
{
    if (olm.Load(fileName))
    {
        var folderHierarchy = olm.GetFolders();
        ExtractItems(olm, folderHierarchy);
    }
}

private static void ExtractItems(OlmStorage olm, IEnumerable<OlmFolder> folders)
{
    foreach (var folder in folders)
    {
        if (folder.HasMessages)
        {
            Console.WriteLine(folder);

            foreach (var msg in olm.EnumerateMessages(folder))
            {
                Console.WriteLine(msg.Subject);
            }
        }

        ExtractItems(olm, folder.SubFolders);
    }
}

Net: Counting Items and Working with Categories

Mon, 01 Jan 0001 00:00:00 +0000

Beyond reading individual messages, Aspose.Email for .NET lets you inspect how many items an OLM file or a folder contains and read the Outlook categories - including their colors - that are stored in the file. This article covers both.

Check Whether a Folder Has Messages

The OlmFolder.HasMessages property indicates whether a folder contains any messages, and the OlmFolder.MessageCount property returns how many.

using (var olm = OlmStorage.FromFile(fileName))
{
    var folder = olm.GetFolder("Inbox", true);

    if (folder.HasMessages)
    {
        Console.WriteLine($"Message count: {folder.MessageCount}");
    }
}

Count Items in Each Folder

Use the OlmFolder.MessageCount property to report the number of items in every folder of the file:

using (var storage = new OlmStorage("SampleOLM.olm"))
{
    PrintMessageCount(storage.FolderHierarchy);
}

public static void PrintMessageCount(IEnumerable<OlmFolder> folders)
{
    foreach (OlmFolder folder in folders)
    {
        Console.WriteLine($"Message Count [{folder.Name}]: {folder.MessageCount}");

        PrintMessageCount(folder.SubFolders);
    }
}

Get the Total Number of Items in the Storage

The OlmStorage class has a GetTotalItemsCount() method that returns the total number of message items contained in the whole OLM storage:

using (var olm = new OlmStorage("storage.olm"))
{
    var count = olm.GetTotalItemsCount();
    Console.WriteLine($"Total items: {count}");
}

Retrieve Outlook Category Colors

To work with the Outlook item categories stored in an OLM file, Aspose.Email offers:

the OlmItemCategory class - represents an Outlook item category, available by its Name and associated Color, represented in hexadecimal format;
the GetCategories() method of the OlmStorage class - retrieves the list of categories used in the storage.

The following sample lists every category used in the storage along with its color:

using (var olm = OlmStorage.FromFile("storage.olm"))
{
    var categories = olm.GetCategories();

    foreach (var category in categories)
    {
        Console.WriteLine($"Category name: {category.Name}");

        // Color is represented as a hexadecimal value: #rrggbb
        Console.WriteLine($"Category color: {category.Color}");
    }
}

Get the Category Color of a Message

You can match the categories assigned to a particular message against the storage’s category list to resolve each category’s color. The example below reads the categories of every message in a folder and prints the color of each one:

using (var olm = OlmStorage.FromFile("storage.olm"))
{
    var categories = olm.GetCategories();
    var folder = olm.GetFolder("Inbox", true);

    foreach (var msg in folder.EnumerateMapiMessages())
    {
        if (msg.Categories != null)
        {
            foreach (var msgCategory in msg.Categories)
            {
                Console.WriteLine($"Category name: {msgCategory}");

                var category = categories
                    .FirstOrDefault(c => c.Name.Equals(msgCategory, StringComparison.OrdinalIgnoreCase));

                Console.WriteLine(category != null
                    ? $"Category color: {category.Color}"
                    : "Category color: Not found");
            }
        }
    }
}

Net: Converting OLM to PST

Mon, 01 Jan 0001 00:00:00 +0000

OLM is a database file format used by Microsoft Outlook for Mac. OLM files store email messages, calendar data, contacts, and application settings, and they are not supported by Outlook for Windows. To migrate a mailbox from Outlook for Mac to Outlook for Windows, you need to convert the OLM file to the Outlook PST format. Aspose.Email for .NET lets you do this in code, without Microsoft Outlook installed.

How the Conversion Works

To convert an OLM file to PST, follow these steps:

Create an instance of the OlmStorage class to open the source OLM file.
Create a new PST file with the PersonalStorage.Create method.
Implement a GetContainerClass method that maps a message class to the corresponding folder (container) class, so each folder is created with the correct type in the PST.
Implement an AddToPst method that recursively reads each folder and its messages from the OLM file - using EnumerateMapiMessages - and adds them to the PST in the same order, using the AddSubFolder and AddMessage methods of FolderInfo.

Code Sample

The following code shows how to convert an OLM file to PST.

Main method:

// create an instance of OlmStorage class to open the source OLM
using (var olm = new OlmStorage("my.olm"))
// create a new PST file
using (var pst = PersonalStorage.Create("my.pst", FileFormatVersion.Unicode))
{
    // recursively read each folder and its messages
    // and add them to the PST in the same order
    foreach (var olmFolder in olm.FolderHierarchy)
    {
        AddToPst(pst.RootFolder, olmFolder);
    }
}

GetContainerClass method:

public string GetContainerClass(string messageClass)
{
    if (messageClass.StartsWith("IPM.Contact") || messageClass.StartsWith("IPM.DistList"))
    {
        return "IPF.Contact";
    }

    if (messageClass.StartsWith("IPM.StickyNote"))
    {
        return "IPF.StickyNote";
    }

    if (messageClass.StartsWith("IPM.Activity"))
    {
        return "IPF.Journal";
    }

    if (messageClass.StartsWith("IPM.Task"))
    {
        return "IPF.Task";
    }

    if (messageClass.StartsWith("IPM.Appointment") || messageClass.StartsWith("IPM.Schedule.meeting"))
    {
        return "IPF.Appointment";
    }

    return "IPF.Note";
}

AddToPst method:

public void AddToPst(FolderInfo pstFolder, OlmFolder olmFolder)
{
    FolderInfo pstSubFolder = pstFolder.GetSubFolder(olmFolder.Name);

    foreach (var msg in olmFolder.EnumerateMapiMessages())
    {
        if (pstSubFolder == null)
        {
            pstSubFolder = pstFolder.AddSubFolder(olmFolder.Name, GetContainerClass(msg.MessageClass));
        }

        pstSubFolder.AddMessage(msg);
    }

    if (pstSubFolder == null)
    {
        pstSubFolder = pstFolder.AddSubFolder(olmFolder.Name);
    }

    foreach (var olmSubFolder in olmFolder.SubFolders)
    {
        AddToPst(pstSubFolder, olmSubFolder);
    }
}

Conversion in the opposite direction (PST to OLM) is not supported, because an OLM file is always created by Outlook for Mac when an account is added and synchronized with the mail server.