---
title: "Convert an Outlook contact to vCard in C#"
url: https://recursiveai.org/onemail/cookbook/convert-outlook-contact-to-vcard/
description: "Convert an Outlook contact to a VCF file in C# with OneMail. Write vCard 3.0 or 4.0, reopen names and phones, and inspect the conversion loss report."
version: "1.0.1"
---

The zip’s `contacts.pst` holds one synthetic contact to export as a vCard (VCF).

```shell
dotnet add package RecursiveAI.OneMail
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
using RecursiveAI.OneMail;
using RecursiveAI.OneMail.Conversion.Stores;
using var file = Mail.Open("contacts.pst");
var result = Mail.Convert(
    file.Enumerate().Single(),
    ConvertFormat.VCard);
File.WriteAllBytes("contact.vcf",
    result.Value ?? throw new IOException());
```

Writes `contact.vcf` as vCard 3.0; the snippet prints nothing.

Unzip [the example](https://recursiveai.org/onemail/cookbook/convert-outlook-contact-to-vcard/convert-outlook-contact-to-vcard.zip), then `dotnet run`.

## Full program

The typed vCard reader is in the Calendar package (also a dependency of OneMail):

```shell
dotnet add package RecursiveAI.OneMail.Calendar
```

The PST contains a Contacts folder with Morgan Lee, given name Morgan, surname Lee, mobile phone +1-202-555-0142, account `staff-42` and the original blue PNG photo. No real person’s data is used. The full program reads this contact, calls `ContactToVCardConverter` directly, writes the resulting component, then parses the saved VCF. It prints non-internal conversion losses instead of hiding them.

```csharp
using RecursiveAI.OneMail.Calendar;
using RecursiveAI.OneMail.Calendar.VCard;
using RecursiveAI.OneMail.Conversion.OxVCard;
using RecursiveAI.OneMail.Pst.Messaging;

if (!PstStore.TryOpen("contacts.pst", out var store, out var defects))
    throw new InvalidDataException(string.Join("; ", defects));
using (store)
{
    var contact = store!.EnumerateFolders().Single(f => f.Name == "Contacts")
        .EnumerateMessages().Single();
    var result = new ContactToVCardConverter().Convert(contact);
    var document = new ContentDocument();
    document.Root.Add(result.Value);
    File.WriteAllBytes("contact.vcf", document.ToArray());
    var card = VCardDocument.Cards(ContentDocument.Parse(File.ReadAllBytes("contact.vcf"))).Single();
    Console.WriteLine($"Version: {card.VersionText}");
    Console.WriteLine($"Name: {card.FormattedName}");
    Console.WriteLine($"Family: {string.Join(" ", card.Name!.Family)}");
    Console.WriteLine($"Phone: {card.Phones.Single().Value}");
    Console.WriteLine($"Photos: {card.Photos.Count}");
    foreach (var loss in result.Report.Where(l => l.Kind.ToString() != "Internal"))
        Console.WriteLine($"{loss.Kind}: {loss.Code}: {loss.Name}");
}
```

`dotnet run` prints:

```text
Version: 3.0
Name: Morgan Lee
Family: Lee
Phone: +1-202-555-0142
Photos: 1
Dropped: NoVCardMapping: PidTagSearchKey
Dropped: NoVCardMapping: PidTagAccount
```

The account field and PST search key have no vCard mapping. An invalid PST makes `TryOpen` return false with defects; a missing input file throws `FileNotFoundException`.

## Variations

**Write vCard 4.0 without a photo.** This uses the same PST and saves a separate VCF:

```csharp
using RecursiveAI.OneMail.Calendar;
using RecursiveAI.OneMail.Calendar.VCard;
using RecursiveAI.OneMail.Conversion.OxVCard;
using RecursiveAI.OneMail.Pst.Messaging;

if (!PstStore.TryOpen("contacts.pst", out var store, out _))
    throw new InvalidDataException();
using (store)
{
    var contact = store!.EnumerateFolders()
        .Single(f => f.Name == "Contacts")
        .EnumerateMessages().Single();
    var options = new ContactToVCardOptions
    {
        Version = VCardVersion.V40,
        IncludePhoto = false
    };
    var result = new ContactToVCardConverter(options).Convert(contact);
    var doc = new ContentDocument();
    doc.Root.Add(result.Value);
    File.WriteAllBytes("contact-4.vcf", doc.ToArray());
    var card = VCardDocument.Cards(
        ContentDocument.Parse(File.ReadAllBytes("contact-4.vcf"))).Single();
    Console.WriteLine($"Version: {card.VersionText}");
    Console.WriteLine($"Photos: {card.Photos.Count}");
}
```

```text
Version: 4.0
Photos: 0
```

## Related recipes

- [Read a VCF file](https://recursiveai.org/onemail/cookbook/read-vcf-file/)
- [Read a PST file](https://recursiveai.org/onemail/cookbook/read-pst-file/)

## The short answer

To convert an Outlook contact to vCard in C#, read the contact’s MAPI message and pass it to `ContactToVCardConverter`. Add the returned component to a `ContentDocument` and write its bytes to a `.vcf` file. The default is vCard 3.0; `ContactToVCardOptions.Version` selects 4.0.

The snippet at the top uses the shorter `Mail.Convert` entry point, which delegates MAPI contacts to that converter. The full program uses the converter directly so you can inspect its options and loss report. Both paths work on the synthetic PST in the download without Outlook or an account connection.

## How to convert Outlook contacts to vCard File?

Start with an actual contact item, not an ordinary email whose sender happens to be in an address book. The sample PST contains one `IPM.Contact` message with display name Morgan Lee, given name Morgan, surname Lee and one mobile telephone number. It also contains a PNG photo and an account property to make the conversion’s boundaries visible.

The [contact mapping documentation](https://recursiveai.org/onemail/docs/contacts/) lists how Outlook fields map to vCard. Display name becomes `FN`; the structured name parts become `N`; phone properties become `TEL` values with types such as home, work or cell. SMTP email addresses become email fields. An Exchange address without an SMTP form is not guessed into an internet email address.

Photos are included by default when the photo attachment is BMP, GIF, JPEG or PNG. Version 3.0 writes an encoded photo property; version 4.0 uses a data URI. The full program reopens the VCF and counts its photos. For applications that should omit them, use `IncludePhoto = false`, as in the variation.

## How do I export contacts to vCard?

For multiple contacts, repeat the conversion for each contact and give each output file a distinct name. Keep the source PST open until you have finished reading and converting its items: a message’s property or attachment data may still come from that store. Do not close the source immediately after collecting message objects and assume all their bytes were copied.

The one-contact sample intentionally uses `Single()` so unexpected inputs are visible. A store with several contacts needs enumeration instead; a store with several folders also needs an explicit folder choice. Changing those selection rules is separate from changing the converter’s mapping.

Choose the output version based on the receiving application. OneMail’s typed reader can inspect vCard 2.1, 3.0 and 4.0, but this converter writes 3.0 or 4.0. Version 4.0 supports gender and distribution-list group output; version 3.0 has `CLASS`, which 4.0 does not. Selecting a version is therefore a format decision, not just changing a version label.

## Why is Outlook contact to vCard conversion not working?

Distinguish a failed read from a successful export with losses. A missing PST is an input-file error. A PST that `TryOpen` refuses has defects to inspect. A valid contact can still contain fields with no vCard mapping, in which case the converter returns output and a report rather than silently promising identical Outlook behavior.

The sample prints `NoVCardMapping` for `PidTagAccount` and the PST’s search key. The name, phone and photo still export. Other documented codes include `NotInThisVersion` and `ExchangeAddressNotExported`. Read the report before deciding that a usable VCF also preserves every property your application cares about.

Parsing the saved file checks what was actually written, not only the converter’s in-memory result. The full program reads back the formatted name, family name, telephone and photo count. Keep that check focused on your required contact fields and retain the original contact when you need Outlook-specific properties that vCard cannot represent.
