Managing Distribution Lists in PST Files

This article covers creating, reading, and updating Outlook distribution lists (MapiDistributionList) inside a PST file. To work with standalone distribution lists and vCard (VCF) files, see Working with Distribution Lists.

Creating and Managing Distribution Lists

Create and Save Distribution Lists

This code is used when you want to create a distribution list inside a PST file, with its members linked to existing contact items within the same PST.

  1. Create or load a PST and get the “Contacts” folder.
  2. Create MapiContact objects for the list members and add them to the “Contacts” folder using AddMapiMessageItem. This returns a unique entry ID for each contact.
  3. Create MapiDistributionListMember objects for each contact. Set their EntryIdType to MapiDistributionListEntryIdType.Contact and assign the contact’s entry ID.
  4. Add these members to a MapiDistributionListMemberCollection.
  5. Create a MapiDistributionList object, providing a name and the member collection.
  6. Set additional properties like Body and Subject.
  7. Add the distribution list to the “Contacts” folder using AddMapiMessageItem.

Code Example:

using Aspose.Email.Storage.Pst;
using Aspose.Email.Mapi;

// Load or create the PST file
using (var pst = PersonalStorage.FromFile("your.pst"))
{
    // Get the Contacts folder
    var folder = pst.GetPredefinedFolder(StandardIpmFolder.Contacts);

    if (folder != null)
    {
        // Create individual contact items
        var contact1 = new MapiContact("Susanne Nielsen", "SusanneNielsen@example.com");
        var contact2 = new MapiContact("Lars Rosing", "LarsRosing@example.com");

        // Add contacts to the folder and retrieve their entry IDs
        var idContact1 = folder.AddMapiMessageItem(contact1);
        var idContact2 = folder.AddMapiMessageItem(contact2);

        // Create distribution list members linked to the contacts
        var member1 = new MapiDistributionListMember(contact1.NameInfo.DisplayName, contact1.ElectronicAddresses.Email1.EmailAddress)
        {
            EntryIdType = MapiDistributionListEntryIdType.Contact,
            EntryId = Convert.FromBase64String(idContact1)
        };
        var member2 = new MapiDistributionListMember(contact2.NameInfo.DisplayName, contact2.ElectronicAddresses.Email1.EmailAddress)
        {
            EntryIdType = MapiDistributionListEntryIdType.Contact,
            EntryId = Convert.FromBase64String(idContact2)
        };

        // Create a collection of distribution list members
        var members = new MapiDistributionListMemberCollection
        {
            member1,
            member2
        };

        // Create the distribution list
        var distributionList = new MapiDistributionList("Contact list", members)
        {
            Body = "Distribution List Body",
            Subject = "Sample Distribution List using Aspose.Email"
        };

        // Add the distribution list to the Contacts folder in the PST
        folder.AddMapiMessageItem(distributionList);
    }
}

Read Distribution Lists

This code is used to find and read all distribution lists stored within the “Contacts” folder of a PST file.

  1. Load the PST file using PersonalStorage.FromFile.
  2. Retrieve the predefined “Contacts” folder with GetPredefinedFolder.
  3. Enumerate all messages in the folder using EnumerateMessages().
  4. For each message, check if its MessageClass property is "IPM.DistList" to identify it as a distribution list.
  5. Extract the full message using ExtractMessage and convert it to a MapiDistributionList object using ToMapiMessageItem().

Code Example:

using Aspose.Email.Storage.Pst;
using Aspose.Email.Mapi;

// Load the PST file
using (var pst = PersonalStorage.FromFile("your.pst"))
{
    // Get the built-in Contacts folder
    var folder = pst.GetPredefinedFolder(StandardIpmFolder.Contacts);
    
    if (folder != null)
    {
        // Loop through all items in the Contacts folder
        foreach (var msgInfo in folder.EnumerateMessages())
        {
            // Check if the item is a distribution list by its message class
            if (msgInfo.MessageClass == "IPM.DistList")
            {
                // Extract the distribution list message
                var distList = (MapiDistributionList)pst.ExtractMessage(msgInfo).ToMapiMessageItem();

                // Access distribution list properties
                Console.WriteLine($"Name: {distList.DisplayName}");

                // Iterate through members
                foreach (var member in distList.Members)
                {
                    Console.WriteLine($"Member: {member.DisplayName}, Email: {member.EmailAddress}");
                }
            }
        }
    }
}

Update Distribution Lists

The following code snippet shows you how to update a distribution list in PST.

  1. Load the PST file using PersonalStorage.FromFile.
  2. Retrieve the predefined “Contacts” folder with GetPredefinedFolder(StandardIpmFolder.Contacts).
  3. Enumerate all messages in the folder using EnumerateMessages().
  4. For each message, check if its MessageClass property is "IPM.DistList" to identify it as a distribution list.
  5. Extract the distribution list message using ExtractMessage and convert it to a MapiDistributionList object using ToMapiMessageItem().
  6. Create a new MapiDistributionListMember object with the member’s display name and email address.
  7. Add the new member to the distribution list’s Members collection.
  8. Update the distribution list in the PST folder using UpdateMessage with the message’s entry ID.

Code Example:

using Aspose.Email.Mapi;
using Aspose.Email.Storage.Pst;

// Load PST file
using (PersonalStorage pst = PersonalStorage.FromFile("my.pst"))
{
    // Get Contacts folder
    var folder = pst.GetPredefinedFolder(StandardIpmFolder.Contacts);

    // Add a new member to each distribution list in PST
    foreach (var msg in folder.EnumerateMessages())
    {
        // Check if the message has the "IPM.DistList" message class
        if (msg.MessageClass == "IPM.DistList")
        {
            var distList = (MapiDistributionList)pst.ExtractMessage(msg).ToMapiMessageItem();

            // Create a new member to add
            var member = new MapiDistributionListMember("Edward R. Manuel", "EdwardRManuel@example.com");
            distList.Members.Add(member);

            // Update Distribution List in PST
            folder.UpdateMessage(msg.EntryIdString, distList);
        }
    }
}

See Also

Managing Contacts in PST Files Managing Calendar Items in PST Files