Working with Outlook Contacts

Create Outlook Contact

Aspose.Email for Java supports creating Outlook contacts (VCards) using the MapiContact class. MapiContact contains many methods some of which are given below.

Contact Structure in Aspose.Email for Java

Below is the hierarchy implemented for contacts in Aspose.Email for Java. The relevant class name is given against each property. Hyperlinks are provided to the online documentation for further reference.

  1. Contact (MapiContact)
    1. Electronic Addresses (MapiContactElectronicAddressPropertySet)
      1. Email1 (MapiContactElectronicAddress)
        1. Address Type
        2. Display Name
        3. Email Address
        4. Fax Number
      2. Email2
      3. Email3
      4. Home Fax
      5. Primary Fax
      6. Business Fax
    2. Events (MapiContactEventPropertySet) See below for an example of how to set events.
      1. Birthday
      2. Wedding Anniversary
    3. Name Info (MapiContactNamePropertySet)
      1. Display Name
      2. Display Name Prefix
      3. File Under
      4. File Under ID
      5. Generation
      6. Given Name
      7. Initials
      8. Middle Name
      9. Nick Name
      10. Surname
    4. Personal Info (MapiContactPersonalInfoPropertySet)
      1. Account
      2. Business Home Page
      3. Computer Network Name
      4. Customer ID
      5. Free Business Location
      6. FTP Site
      7. Gender
      8. Government ID Number
      9. Hobbies
      10. HTML
      11. Instant Messaging Address
      12. Language
      13. Location
      14. Notes
      15. Organizational ID Number
      16. Personal Home Page
      17. Referred by Name
      18. Spouse Name
    5. Physical Address (MapiContactPhysicalAddressPropertySet)
      1. Home Address (MapiContactPhysicalAddress)
        1. Address
        2. City
        3. Country
        4. Country Code
        5. Postal Code
        6. Post Office Box
        7. State Or Province
      2. Other Address
      3. Work Address
    6. Professional Info
      1. Assistant
      2. Company Name
      3. Depart Name
      4. Manager Name
      5. Office Location
      6. Profession
      7. Title
    7. Telephones (MapiContactTelephonePropertySet)
      1. Assistant Telephone Number
      2. Business2 Telephone Number
      3. Business Telephone Number
      4. Callback Telephone Number
      5. Car Telephone Number
      6. Company Main Telephone Number
      7. Home2 Telephone Number
      8. Home Telephone Number
      9. ISDN Number
      10. Mobile Telephone Number
      11. Other Telephone Number
      12. Pager Telephone Number
      13. Primary Telephone Number
      14. Radio Telephone Number
      15. Telex Number
      16. TTY/TDD Phone Number

The following code uses Aspose.Email to create an Outlook contact and fills it with name, professional properties, physical address, and email. It also shows adding MapiContactEventPropertySet to the contact.

todo:image_alt_text
Figure: A Microsoft Outlook contact coded in with Aspose.Email

Adding Contact Event Information to a MapiContact

Microsoft Outlook lets users add event information to a contact. The event holds the birthday and wedding anniversary. Aspose.Email provides the MapiContactEventPropertySet class for adding this information to a contact. This is elaborated in the following example.

Creating, Saving and Reading Outlook Contacts

Aspose.Email allows developers to create Microsoft Outlook contacts as well as email messages. The MapiContact class provides all contact 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 a MapiContact

The following steps can be used to create and save a contact to disc:

  1. Instantiate a new object of the MapiContact class.
  2. Enter information related to various properties of the contact.
  3. Add photo data to the contact, if any.
  4. Save the contact as MSG or VCard format.  

Save Contact in Version 3 VCF Format

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

Read a MapiContact

The MapiContact class can be used to load both Microsoft Outlook MSG files as well as VCard format contacts. The following code samples show how to load Outlook contacts saved as MSG and VCF into MapiContact.

Load a Contact from MSG

Load a contact from VCard

The following code shows how to create a MapiContact by loading data from a VCard file using VCardLoadOptions:

MapiContact mapiContact = MapiContact.fromVCard("contact.vcf", new VCardLoadOptions());
System.out.println(mapiContact.getNameInfo().getDisplayName());

Load VCard Contact with specified Encoding

Supported Method: MapiContact.fromVCard(String, Encoding)

Load MAPI Contacts from vCard with Custom Options

To provide more flexibility when converting vCard (.vcf) files into MAPI contacts, Aspose.Email for Java provides the MapiContact.fromVCard(String filePath, VCardLoadOptions options) overload. It offers 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, MSG export, or other Outlook-compatible formats.

MapiContact mapiContact = MapiContact.fromVCard("contact.vcf", new VCardLoadOptions());
System.out.println(mapiContact.getNameInfo().getDisplayName());

Save VCard Files with Extended Fields

The UseExtensions property of VCardSaveOptions allows you to control whether extended (X-) fields may be used when saving vCard files. When set to true (the 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:

MapiContact contact = MapiContact.fromVCard("contact.vcf");

VCardSaveOptions options = new VCardSaveOptions();
options.setUseExtensions(false);

contact.save("contact_out.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 of the MapiDistributionList class:

  • static MapiDistributionList fromVCF(String filePath)
  • static MapiDistributionList fromVCF(InputStream stream)

The code sample below demonstrates how to use this feature:

// Convert a multi-contact VCF file into a MapiDistributionList
MapiDistributionList dlist = MapiDistributionList.fromVCF("contacts.vcf");

System.out.println(dlist.getDisplayName() + ": " + dlist.getMembers().size() + " member(s)");

The resulting distribution list can be written back to a VCF file in the required vCard version:

MapiDistributionList dlist = MapiDistributionList.fromVCF("contacts.vcf");

MapiDistributionListSaveOptions options = new MapiDistributionListSaveOptions(ContactSaveFormat.VCard);
options.setVersion(VCardVersion.V30);

dlist.save("distribution_list.vcf", options);

Working with vCard Files Directly

When your source and target are vCard files and you do not need Outlook/MAPI features, use the VCardContact class instead of MapiContact. It reads and writes VCF directly, supports vCard 2.1/3.0/4.0 and multiple contacts per file. See Working with vCard (VCF) Files for a detailed description of the vCard object model.

Rendering 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.

Working with Message Attachments Working with Outlook Tasks