Outlook Contacts Management

This article covers standalone Outlook MapiContact items saved as MSG or vCard (VCF). For the format-neutral VCardContact class that reads and writes vCard files directly, see Working with vCard (VCF) Files. To store and read contacts inside a PST, see Managing Contacts in PST Files.

Like MapiMessage, Aspose.Email allows you to create Outlook contacts. The MapiContact class provides all the contact related properties required to create an Outlook contact. This article shows how to create, save and read an Outlook contact using the MapiContact class.

Create and Save Outlook Contact

To create a contact and save it to disc:

Instantiate a new object of the MapiContact class.
Enter contact property information.
Add photo data (if any).
Save the contact as MSG or VCard format.

The following code snippet shows you how to create and save outlook contact.

// The path to the File directory.
string dataDir = RunExamples.GetDataDir_Outlook();

MapiContact contact = new MapiContact();
contact.NameInfo = new MapiContactNamePropertySet("Bertha", "A.", "Buell");
contact.ProfessionalInfo = new MapiContactProfessionalPropertySet("Awthentikz", "Social work assistant");
contact.PersonalInfo.PersonalHomePage = "B2BTies.com";
contact.PhysicalAddresses.WorkAddress.Address = "Im Astenfeld 59 8580 EDELSCHROTT";
contact.ElectronicAddresses.Email1 = new MapiContactElectronicAddress("Experwas", "SMTP", "BerthaABuell@armyspy.com");
contact.Telephones = new MapiContactTelephonePropertySet("06605045265");
contact.PersonalInfo.Children = new string[] { "child1", "child2", "child3" };
contact.Categories = new string[] { "category1", "category2", "category3" };
contact.Mileage = "Some test mileage";
contact.Billing = "Test billing information";
contact.OtherFields.Journal = true;
contact.OtherFields.Private = true;
contact.OtherFields.ReminderTime = new DateTime(2014, 1, 1, 0, 0, 55);
contact.OtherFields.ReminderTopic = "Test topic";
contact.OtherFields.UserField1 = "ContactUserField1";
contact.OtherFields.UserField2 = "ContactUserField2";
contact.OtherFields.UserField3 = "ContactUserField3";
contact.OtherFields.UserField4 = "ContactUserField4";

// Add a photo
using (FileStream fs = File.OpenRead(dataDir + "Desert.jpg"))
{
    byte[] buffer = new byte[fs.Length];
    fs.Read(buffer, 0, buffer.Length);
    contact.Photo = new MapiContactPhoto(buffer,
        MapiContactPhotoImageFormat.Jpeg);
}
// Save the Contact in MSG format
contact.Save(dataDir + "MapiContact_out.msg",ContactSaveFormat.Msg);

// Save the Contact in VCF format
contact.Save(dataDir + "MapiContact_out.vcf", ContactSaveFormat.VCard);

Save MAPI Distribution Lists to VCF Files

The code sample below demonstrates how to save a distribution list to a multi-contact VCF file:

// convert the `msg` object to a `MapiDistributionList` object
var dlist = (MapiDistributionList)msg.ToMapiMessageItem();

//save the distribution list
var options = new MapiDistributionListSaveOptions(ContactSaveFormat.VCard);
dlist.Save("distribution_list.vcf", options);

Convert Multi-Contact VCF Files to MapiDistributionList

Aspose.Email supports the conversion of multi-contact VCF files into MapiDistributionList objects, making it easy to manage and import multiple contacts directly into your applications. This feature is accessible through the following static methods in the MapiDistributionList class:

The code sample below demonstrates how to use this feature:

// Convert a multi-contact VCF file to a MapiDistributionList
MapiDistributionList dlist = MapiDistributionList.FromVCF(fileName);

Save Contacts in VCF Format

To save the contact in version 3 VCF format, use the VCardVersion enumeration to set the VCardSaveOptions.Version property. The following sample code demonstrates the use of VCardVersion enumeration to save the contact VCF version 3 format:

var options = new MapiDistributionListSaveOptions(ContactSaveFormat.VCard);
options.Version = VCardVersion.V30;
dlist.Save("distribution_list.vcf", options);

Reading MAPI Contacts

The MapiContact class can be used to load both Outlook MSG and VCard format contacts. The following code snippet shows you how to load Outlook contacts saved as MSG and VCF into a MapiContact.

Load Contacts from MSG Files

The following code snippet shows you how to load contacts from MSG.

MapiMessage msg = MapiMessage.FromFile(dataDir + "Contact.msg");
MapiContact contact = (MapiContact)msg.ToMapiMessageItem();

Console.WriteLine(contact.NameInfo.DisplayName);

Load Contacts from VCards

The following code snippet shows you how to load a vCard file into a MapiContact using the FromVCard method. To load a vCard into a VCardContact instead, see Working with vCard (VCF) Files.

MapiContact contact = MapiContact.FromVCard(dataDir + "Contact.vcf");

Load MAPI Contacts from vCard with Custom Options

To provide more flexibility when converting vCard (.vcf) files into MAPI contacts, Aspose.Email for .NET provides an overload MapiContact.FromVCard(string filePath, VCardLoadOptions options) method that accepts a VCardLoadOptions object. It offers improved control over how vCard files are interpreted - especially when working with different vCard formats, encodings, or advanced parsing scenarios.

The following code sample demonstrates how to load a .vcf contact file into a MapiContact object using the overload that accepts VCardLoadOptions. The loaded contact can then be used within PST files, MSG export, or other Outlook-compatible formats.

var mapiContact = MapiContact.FromVCard("contact.vcf", new VCardLoadOptions());
Console.WriteLine(mapiContact.NameInfo.DisplayName);

Load Contacts from VCards with Specified Encoding

The encoding of a vCard file is specified through the PreferredEncoding property of the VCardLoadOptions class. The following code snippet shows you how to load contacts from VCard with the specified encoding.

var loadOptions = new VCardLoadOptions { PreferredEncoding = Encoding.UTF8 };
var contactReadFromFile = MapiContact.FromVCard(dataDir + @"Contact.vcf", loadOptions);

Save VCard Files with Extended fields

The UseExtensions property allows you to control whether extended fields can be used when saving vCard files. When set to true (default), extensions are permitted, providing compatibility with custom fields and additional contact information.

The following code sample shows how to disable the extended fields when saving a contact:

var contact = MapiContact.FromVCard("contact.vcf");

var options = new VCardSaveOptions
{
    UseExtensions = false
};

contact.Save("contact_out.vcf", options);

Working with vCard Files Directly

Reading and writing vCard (VCF) files with the format-neutral VCardContact class — loading single or multiple contacts, choosing the text encoding, saving with a specific vCard version, and asynchronous loading — is covered in a dedicated article: Working with vCard (VCF) Files.

Render Contact Information to MHTML

Outlook Contact can be converted to MHTML using Aspose.Email API. This example shows how a VCard is loaded into MapiContact and then converted to MHTML with the help of MailMessage API.

//Load VCF Contact and convert to MailMessage for rendering to MHTML
var contact = MapiContact.FromVCard("Contact.vcf");

MemoryStream ms = new MemoryStream();
contact.Save(ms, ContactSaveFormat.Msg);
ms.Position = 0;
MapiMessage msg = MapiMessage.Load(ms, new MsgLoadOptions());
MailConversionOptions op = new MailConversionOptions();
MailMessage eml = msg.ToMailMessage(op);

//Prepare the MHT format options
MhtSaveOptions mhtSaveOptions = new MhtSaveOptions();
mhtSaveOptions.CheckBodyContentEncoding = true;
mhtSaveOptions.PreserveOriginalBoundaries = true;
MhtFormatOptions formatOp = MhtFormatOptions.WriteHeader | MhtFormatOptions.RenderVCardInfo;
mhtSaveOptions.RenderedContactFields = ContactFieldsSet.NameInfo | ContactFieldsSet.PersonalInfo | ContactFieldsSet.Telephones | ContactFieldsSet.Events;
mhtSaveOptions.MhtFormatOptions = formatOp;
eml.Save("ContactMhtml_out.mhtml", mhtSaveOptions);