The zip’s contacts.pst holds one synthetic contact to export as a vCard (VCF).
dotnet add package RecursiveAI.OneMailRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
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, then dotnet run.
Full program
The typed vCard reader is in the Calendar package (also a dependency of OneMail):
dotnet add package RecursiveAI.OneMail.CalendarThe 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.
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:
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:
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}"); }
Version: 4.0 Photos: 0
Related recipes
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 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.