Managing Outlook Contacts in PST Files

Creating, Saving and Reading Contacts

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

Create and Save Outlook Contacts

To create a contact and save it to disc, follow these steps:

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

The following code snippet shows you how to create and save an Outlook contact:

import aspose.email as ae

data_dir = "path/to/data/directory/"

contact = ae.mapi.MapiContact()
contact.name_info = ae.mapi.MapiContactNamePropertySet("Bertha", "A.", "Buell")
contact.professional_info = ae.mapi.MapiContactProfessionalPropertySet("Awthentikz", "Social work assistant")
contact.personal_info.personal_home_page = "B2BTies.com"
contact.physical_addresses.work_address.address = "Im Astenfeld 59 8580 EDELSCHROTT"
contact.electronic_addresses.email1 = ae.mapi.MapiContactElectronicAddress("Experwas", "SMTP", "BerthaABuell@armyspy.com")
contact.telephones = ae.mapi.MapiContactTelephonePropertySet("06605045265")
contact.personal_info.children = ["child1", "child2", "child3"]
contact.categories = ["category1", "category2", "category3"]
contact.mileage = "Some test mileage"
contact.billing = "Test billing information"
contact.other_fields.journal = True
contact.other_fields.private = True
contact.other_fields.reminder_topic = "Test topic"
contact.other_fields.user_field1 = "ContactUserField1"
contact.other_fields.user_field2 = "ContactUserField2"
contact.other_fields.user_field3 = "ContactUserField3"
contact.other_fields.user_field4 = "ContactUserField4"

# Add a photo
with open(data_dir + "Desert.jpg", "rb") as file:
    buffer = file.read()
    contact.photo = ae.mapi.MapiContactPhoto(buffer, ae.mapi.MapiContactPhotoImageFormat.JPEG)

# Save the Contact in MSG format
contact.save(data_dir + "MapiContact_out.msg", ae.mapi.ContactSaveFormat.MSG)

# Save the Contact in VCF format
contact.save(data_dir + "MapiContact_out.vcf", ae.mapi.ContactSaveFormat.V_CARD)

Save Contacts in VCF Format Version 3

To save a contact in VCF format Version 3, use the version property of the VCardSaveOptions class.

  1. Create a new instance of the VCardSaveOptions class.
  2. Set the version property of the VCardSaveOptions object to VCardVersion.V30. This sets the vCard version to 3.0.
  3. Call the save method of the MapiContact object, passing the file name “contact.vcf” and the VCardSaveOptions object as parameters. This saves the contact as a vCard file with the specified file name and options.

The following code snippet shows you how to save a contact in VCF format Version 3:

import aspose.email as ae

contact = ae.mapi.MapiContact()
contact.name_info = ae.mapi.MapiContactNamePropertySet("Bertha", "A.", "Buell")
options = ae.personalinfo.vcard.VCardSaveOptions()
options.version = ae.personalinfo.vcard.VCardVersion.V30
contact.save("contact.vcf", options)

Load Contacts from MSG or VCard Files

The MapiContact class can be used to load both Outlook MSG and VCard format contacts.

To load a contact from MSG, use the code sample below:

To load a contact from VCard, use the following code sample:

Load MAPI Contacts from vCard with Custom Options

To provide more flexibility when converting vCard (.vcf) files into MAPI contacts, Aspose.Email offers an overload of the MapiContact.from_v_card method that accepts a VCardLoadOptions object. It gives improved control over how vCard files are interpreted — especially when working with different vCard formats, encodings or advanced parsing scenarios.

The loaded contact can then be used within PST files, exported to MSG, or converted to other Outlook-compatible formats.

from aspose.email.mapi import MapiContact
from aspose.email.personalinfo.vcard import VCardLoadOptions

mapi_contact = MapiContact.from_v_card("contact.vcf", VCardLoadOptions())
print(mapi_contact.name_info.display_name)

Load Contacts with Specified Encoding

The following code snippet shows you how to load a contact from vcard with specified encoding.

Save VCard Files with Custom Character Encoding

When saving a vCard file, you can define the character encoding to ensure compatibility with non-ASCII characters. For instance, setting the preferred_text_encoding property of the VCardSaveOptions object to “utf-8” ensures proper encoding of non-ASCII text. This feature is particularly useful for handling multilingual contact data. Below is an example of how to configure and save a vCard file with custom character encoding:

import aspose.email as ae

contact = ae.mapi.MapiContact()
contact.name_info = ae.mapi.MapiContactNamePropertySet("Bertha", "A.", "Buell")
options = ae.personalinfo.vcard.VCardSaveOptions()
options.preferred_text_encoding = "utf-8"
contact.save("contact.vcf", options)

Save VCard Files with Extended Properties

In addition to standard vCard fields, you can enhance your vCard files by including extended properties. These are additional attributes not covered by the standard vCard specification, allowing greater customization. To enable this, set the use_extensions property of the VCardSaveOptions class to True. This is particularly beneficial for adding custom or application-specific metadata. Here’s how you can save a vCard file with extended properties enabled:

import aspose.email as ae

contact = ae.mapi.MapiContact()
contact.name_info = ae.mapi.MapiContactNamePropertySet("Bertha", "A.", "Buell")
options = ae.personalinfo.vcard.VCardSaveOptions()
options.use_extensions = True
contact.save("contact.vcf", options)

Read Multiple Contacts in VCard Format

To retrieve all contacts from a VCard, you can use the following methods:

  • is_multi_contacts method determines if a stream has multiple contacts.
  • load_as_multiple(file_path) method loads a list of all contacts from a VCard file.
  • load_as_multiple(stream) method loads a list of all contacts from a VCard stream.

The code snippet below demonstrates the process of reading multiple contacts from a VCard file:

import aspose.email as ae

contact = ae.mapi.MapiContact()
contact.name_info = ae.mapi.MapiContactNamePropertySet("Bertha", "A.", "Buell")
options = ae.personalinfo.vcard.VCardSaveOptions()
options.use_extensions = True
contact.save("contact.vcf", options)

if ae.personalinfo.vcard.VCardContact.is_multi_contacts("contact.vcf"):
    ae.personalinfo.vcard.VCardContact.load_as_multiple("contact.vcf")

Distribution Lists and VCF Files

Save MAPI Distribution Lists to VCF Files

A MapiDistributionList can be written out as a multi-contact VCF file. Pass a MapiDistributionListSaveOptions object created with ContactSaveFormat.V_CARD to the save method:

from aspose.email.mapi import (MapiDistributionList, MapiDistributionListMember,
                               MapiDistributionListMemberCollection,
                               MapiDistributionListSaveOptions, ContactSaveFormat)

members = MapiDistributionListMemberCollection()
members.append(MapiDistributionListMember("Sebastian Wright", "SebastianWright@dayrep.com"))
members.append(MapiDistributionListMember("Wichert Kroos", "WichertKroos@teleworm.us"))

dlist = MapiDistributionList("Contact List", members)

options = MapiDistributionListSaveOptions(ContactSaveFormat.V_CARD)
dlist.save("distribution_list.vcf", options)

The same works for a distribution list read from an MSG file — convert the loaded message with to_mapi_message_item() first.

Convert Multi-Contact VCF Files to MapiDistributionList

Aspose.Email supports the conversion of multi-contact VCF files into MapiDistributionList objects, which makes it easy to manage and import multiple contacts directly into your applications. The feature is available through the static MapiDistributionList.from_vcf method, which accepts either a file path or a stream:

from aspose.email.mapi import MapiDistributionList

# Convert a multi-contact VCF file to a MapiDistributionList
dlist = MapiDistributionList.from_vcf("distribution_list.vcf")

print(dlist.display_name)
for member in dlist.members:
    print(f"{member.display_name}: {member.email_address}")

Render Contact Information to MHTML

Outlook Contact can be converted to MHTML using Aspose.Email API. The following code sample demonstrates how to generate an MHTML file that contains detailed contact information originally from an MSG file:

  1. Load the MSG file as a MapiMessage object.
  2. Convert the message to EML format.
  3. Prepare MHT save options:
    • Enable body content encoding and preserve original boundaries.
    • Set MHT format options to write headers and render vCard information.
  4. Define fields to render in the MHT.
  5. Save the EML as an MHTML file.
Managing Outlook Calendar Items Managing Outlook Notes