Bastion.Pst

Introduction

Bastion.Pst is a fully managed .NET library for working with Microsoft Outlook data files — .pst and .ost — without Outlook, without MAPI, and without any external runtime. It reads both legacy ANSI and modern Unicode stores and writes standards-compliant Unicode PST files that open cleanly in every version of Outlook from Outlook 2003 onwards (Outlook 2003, 2007, 2010, 2013, 2016, 2019, 2021 and Microsoft 365). The Unicode PST format was introduced in Outlook 2003; Outlook 2002 and earlier read only the legacy ANSI format, so Bastion PST SDK will not silently upgrade an ANSI store to Unicode without your explicit consent (see the ANSI → Unicode safety gate).

What it does

• Read messages, folders, recipients, attachments and properties from any PST/OST, ANSI or Unicode, of any size — with a streaming engine that keeps memory bounded even on multi-gigabyte files.
• Merge any number of PST files into one, with two layouts — Stacked (each source kept as its own folder tree) and Unified (same-named folders blended into one Inbox, one Sent Items, …) — with optional duplicate removal, item-type filtering, empty-folder pruning and automatic removal of blank “junk” messages.
• Split a store into size-limited volumes or by an arbitrary predicate (for example, everything matching a subject).
• Convert legacy ANSI PST/OST to Unicode PST.
• Export messages out of a PST to standard interchange files — EML (MIME), MSG (Outlook [MS-OXMSG]), MHTML, ICS (appointments), VCF (contacts) and MBOX, with recipients and attachments, including a one-call “whole PST → a folder tree of files” bulk export.
• Import those formats back — parse EML, MSG, MBOX, ICS, VCF and Outlook-for-Mac OLM archives into a neutral message model (headers, addresses, both bodies, decoded attachments), each input validated — and write them into a PST (clsStoreImporter): into an existing store or a brand-new one, with the target folder path created on demand and folder counts maintained. ImportOlm mirrors the OLM folder tree.
• Author Outlook items from code — mail, appointments (including recurring series with deleted-occurrence exceptions), contacts, tasks, notes, journal entries and distribution lists — with a fluent builder, folder create/rename/move/delete, item move/edit/attachment-removal, and a batching session that commits many edits in one atomic write (Bastion.Pst.Authoring).
• Show a mailbox — a bindable read model per section (store.Views.Mail(), .Contacts(), .Appointments(), .Tasks(), .Notes(), .Rss()): flat rows a grid, card view or scheduler binds to directly, with folder classification, Outlook's hidden address-book caches, contact groups (distribution lists, with their members decoded) and duplicate-contact folding handled once, in the library. MailIn lists a single folder from its contents table alone, and clsItemQuery filters before an item is opened — the difference between reading a few hundred items and reading a hundred thousand (Bastion.Pst.Views).
• Edit as a host application does — save, copy, move, delete and import items of every kind through clsItemOps, which knows that a source is never written to, that a legacy ANSI store never accepts data, and that every write is an atomic, reopen-validated rewrite.
• Observe — subscribe once to clsPstEvents.Default for store opens, read progress (Current/Total/Percent), folder selections, closes and errors from anywhere in the library: no polling, and no callback threaded through every call.
• Create a new, empty Outlook-mountable PST from code (clsStoreBuilder.CreateEmpty), or clone just the folder hierarchy of an existing store (clsStoreImporter.CloneStructure).
• Repair & validate — rebuild a readable-but-malformed store into a fresh, structurally-canonical Unicode PST, and run strict Outlook-style validation that catches problems Outlook would reject before your user ever mounts the file.
• Diagnose — a plain-language user activity log, corruption detection on open, and privacy-safe support reports (structural metadata only, never message content).
• Cancel & protect — long operations honour a CancellationToken and stop cleanly (the atomic-write model leaves nothing partial); and an ANSI → Unicode safety gate refuses to silently upgrade a legacy ANSI store (which would make it unopenable in Outlook 2002 and earlier) without your explicit consent. A cheap header-only clsPersonalStorage.PeekFormat / IsAnsi lets you detect the format up front.

Designed for shipping software

• Every call returns a result code. The library never throws into your application. Each operation returns a result object whose ErrorCode is 0 on success and a documented number otherwise, alongside a human-readable ErrorDescription. See Quick Start.
• No native dependencies. 100% managed code; ships for every current .NET — see the tables below.
• Clean-room implementation of the published [MS-PST] file format.

Outlook compatibility — which versions open the files it writes

Bastion PST SDK always writes the Unicode PST format (the modern large-file format, introduced with Outlook 2003). Every Outlook release from 2003 onward opens the files it produces:

It will not open in Outlook 2002/XP or earlier — those releases only understand the legacy ANSI PST format (2 GB ceiling) and cannot read a Unicode PST. If you must target one of those, the file is not compatible; there is no ANSI-write mode. Note the reverse works: Bastion PST SDK happily reads those old ANSI PST/OST files and converts them to Unicode. (The classic “new Outlook” Windows app and Outlook on the web do not use on-disk PST files at all, so this table concerns desktop Outlook.)

.NET compatibility — the library ships for every current runtime

Reference the assembly under lib/ that matches your project. The API is identical across all of them.

Eighteen builds, one per framework. There is no netstandard build: each runtime gets a native assembly instead of a shim. A WinForms app targeting net8.0-windows uses lib/net8.0 — the library is portable and needs no Windows-specific build.

On .NET Core and .NET 5+ also add the Microsoft package System.Text.Encoding.CodePages (for correct ANSI→Unicode transcoding). The eight .NET Framework builds need nothing beyond the framework: those code pages are built in, and the assembly does not reference the package at all, so Bastion.Pst.dll can simply be dropped next to your executable.

PowerShell

Because it is an ordinary managed assembly with no native parts, Bastion PST SDK is also a practical PowerShell library — useful for auditing a directory of archives, exporting a mailbox, or merging a decade of PST files from a scheduled job. Load lib\net48 from Windows PowerShell 5.1 and lib\net8.0 from PowerShell 7+. The distribution ships a ready-made module and fourteen worked tasks in samples/PowerShell; see example 32.

Product & support

© 2026 Bastion Software Solutions Ltd — bastionsoftwaresolutions.com. This page documents the public API only; internal types are intentionally omitted.

Evaluation build. The library runs as a thirty-day evaluation with every feature available. During the evaluation, input .pst and .ost files are limited to 100 MB, and merged or stacked output is split into 500 MB volumes instead of the 50 GB a licensed build uses.

Quick Start

Every example below shows the same operation in VB.NET and C#, and every one demonstrates the return-code pattern — check ErrorCode first, then read the human-readable description. The library never throws into your code, so you never need a Try/Catch around a call for control flow.

Imports / usings

Imports Bastion.Pst               ' enmErrorCode, clsOperationResult
Imports Bastion.Pst.Convert       ' clsStoreMerger, clsDedup, enmMergeLayout
Imports Bastion.Pst.Diagnostics   ' clsDiagnostics
Imports Bastion.Pst.Messaging     ' enmItemKind, clsPersonalStorage

using Bastion.Pst;               // enmErrorCode, clsOperationResult
using Bastion.Pst.Convert;       // clsStoreMerger, clsDedup, enmMergeLayout
using Bastion.Pst.Diagnostics;   // clsDiagnostics
using Bastion.Pst.Messaging;     // enmItemKind, clsPersonalStorage

1. Simplest merge (Stacked) — and how to read the return code

Merge several PSTs into one. Each source keeps its own folder tree under the destination root. overwrite:=True replaces the destination if it already exists (otherwise you get ErrorCode 7 DestinationExists).

Dim report = clsStoreMerger.Merge({"a.pst", "b.pst", "c.pst"}, "merged.pst", overwrite:=True)

' --- return-code handling (applies to every operation in the library) ---
If report.ErrorCode <> enmErrorCode.Ok Then
    Console.WriteLine("Error number : " & CInt(report.ErrorCode))     ' e.g. 3
    Console.WriteLine("Error text   : " & report.ErrorDescription)    ' "The file is locked ..."
    Console.WriteLine("Combined     : " & report.ToString())          ' "3: The file is locked ..."
    Console.WriteLine("Technical    : " & report.Detail)              ' full detail for support
    Return
End If
Console.WriteLine($"{report.TotalNodes:N0} items written to merged.pst.")

var report = clsStoreMerger.Merge(new[] { "a.pst", "b.pst", "c.pst" }, "merged.pst", overwrite: true);

// --- return-code handling (applies to every operation in the library) ---
if (report.ErrorCode != enmErrorCode.Ok)
{
    Console.WriteLine("Error number : " + (int)report.ErrorCode);      // e.g. 3
    Console.WriteLine("Error text   : " + report.ErrorDescription);    // "The file is locked ..."
    Console.WriteLine("Combined     : " + report.ToString());          // "3: The file is locked ..."
    Console.WriteLine("Technical    : " + report.Detail);              // full detail for support
    return;
}
Console.WriteLine($"{report.TotalNodes:N0} items written to merged.pst.");

report.Succeeded is a convenience boolean equal to ErrorCode == Ok. The full list of numbers is in the enmErrorCode reference below.

2. Unified merge with duplicate removal, a custom store name, and cleanup

Unified blends same-named folders across all sources into one (one Inbox, one Sent Items). Passing a clsDedup removes duplicate messages; rootName sets the name Outlook shows for the mounted store; pruneEmpty drops folders left empty; blank “junk” messages are removed by default and written to the user log.

Dim diag As New clsDiagnostics With {.CreateUserLog = True, .RecoverFromCorruption = True}

Dim report = clsStoreMerger.Merge(
    {"2019.pst", "2020.pst", "2021.pst"}, "combined.pst",
    dedup:=New clsDedup(),
    diag:=diag,
    overwrite:=True,
    layout:=enmMergeLayout.Unified,
    rootName:="All Mail 2019-2021",
    pruneEmpty:=True)

If report.ErrorCode = enmErrorCode.Ok Then
    Console.WriteLine($"OK - {report.DuplicatesRemoved:N0} duplicates, " &
                      $"{report.BlankMessagesRemoved:N0} blank and " &
                      $"{report.FoldersPruned:N0} empty folders removed.")
    Console.WriteLine($"Activity log: {diag.UserLogPath}")
Else
    Console.WriteLine(report.ToString())
End If

var diag = new clsDiagnostics { CreateUserLog = true, RecoverFromCorruption = true };

var report = clsStoreMerger.Merge(
    new[] { "2019.pst", "2020.pst", "2021.pst" }, "combined.pst",
    dedup: new clsDedup(),
    diag: diag,
    overwrite: true,
    layout: enmMergeLayout.Unified,
    rootName: "All Mail 2019-2021",
    pruneEmpty: true);

if (report.ErrorCode == enmErrorCode.Ok)
{
    Console.WriteLine($"OK - {report.DuplicatesRemoved:N0} duplicates, " +
                      $"{report.BlankMessagesRemoved:N0} blank and " +
                      $"{report.FoldersPruned:N0} empty folders removed.");
    Console.WriteLine($"Activity log: {diag.UserLogPath}");
}
else
{
    Console.WriteLine(report.ToString());
}

3. Merge only certain item types

Pass a set of enmItemKind values to keep only those (here: mail and contacts); everything else is filtered out and counted in report.FilteredOut.

Dim kinds As New HashSet(Of enmItemKind) From {enmItemKind.Mail, enmItemKind.Contact}

Dim report = clsStoreMerger.Merge({"source.pst"}, "mail-and-contacts.pst",
                                  keepKinds:=kinds, overwrite:=True)
Console.WriteLine($"{report.MessagesMerged:N0} kept, {report.FilteredOut:N0} filtered out.")

var kinds = new HashSet<enmItemKind> { enmItemKind.Mail, enmItemKind.Contact };

var report = clsStoreMerger.Merge(new[] { "source.pst" }, "mail-and-contacts.pst",
                                  keepKinds: kinds, overwrite: true);
Console.WriteLine($"{report.MessagesMerged:N0} kept, {report.FilteredOut:N0} filtered out.");

4. Keep everything verbatim (no dedup, no blank drop, no prune)

For a byte-faithful archive, turn the cleanups off.

Dim report = clsStoreMerger.Merge({"a.pst", "b.pst"}, "verbatim.pst",
                                  overwrite:=True,
                                  pruneEmpty:=False,
                                  dropBlankMessages:=False)   ' keep blank/empty messages too

var report = clsStoreMerger.Merge(new[] { "a.pst", "b.pst" }, "verbatim.pst",
                                  overwrite: true,
                                  pruneEmpty: false,
                                  dropBlankMessages: false);  // keep blank/empty messages too

5. Merge into size-limited volumes

When the combined data would exceed a size you want per file, MergeToVolumes writes a numbered series of PSTs, each capped at capBytes. The result carries per-volume details.

Dim vol = clsStoreMerger.MergeToVolumes(
    {"big1.pst", "big2.pst"}, "archive.pst",
    capBytes:=10L * 1024 * 1024 * 1024,       ' 10 GB per volume
    dedup:=New clsDedup(),
    overwrite:=True,
    rootName:="Archive")

If vol.ErrorCode <> enmErrorCode.Ok Then
    Console.WriteLine(vol.ToString())
Else
    Console.WriteLine($"{vol.Volumes.Count} volume(s), {vol.TotalMessages:N0} messages.")
    For Each v In vol.Volumes
        Console.WriteLine($"  {v.Path}: {v.Messages:N0} msgs, {v.SizeBytes / 1048576.0:N0} MB")
    Next
End If

var vol = clsStoreMerger.MergeToVolumes(
    new[] { "big1.pst", "big2.pst" }, "archive.pst",
    capBytes: 10L * 1024 * 1024 * 1024,       // 10 GB per volume
    dedup: new clsDedup(),
    overwrite: true,
    rootName: "Archive");

if (vol.ErrorCode != enmErrorCode.Ok)
{
    Console.WriteLine(vol.ToString());
}
else
{
    Console.WriteLine($"{vol.Volumes.Count} volume(s), {vol.TotalMessages:N0} messages.");
    foreach (var v in vol.Volumes)
        Console.WriteLine($"  {v.Path}: {v.Messages:N0} msgs, {v.SizeBytes / 1048576.0:N0} MB");
}

Merge options at a glance

More VB.NET merge recipes

The same Merge / MergeToVolumes methods cover a wide range of tasks. These VB.NET snippets assume the imports shown at the top.

VB.NET — live progress and corruption recovery

Dim diag As New clsDiagnostics With {.RecoverFromCorruption = True, .CreateUserLog = True}
AddHandler diag.WriteProgress, Sub(s, ev) Console.Write($"{vbCr}Writing {ev.PercentComplete}%   ")
AddHandler diag.ErrorOccurred, Sub(s, ev) Console.WriteLine($"  recovered: {ev.Message}")

Dim report = clsStoreMerger.Merge({"a.pst", "b.pst"}, "merged.pst", diag:=diag, overwrite:=True)
Console.WriteLine()
Console.WriteLine(If(report.Succeeded, "Done.", report.ToString()))

VB.NET — cap output size, and fall back to volumes if it won't fit

Dim sources = {"2019.pst", "2020.pst", "2021.pst"}
Dim cap As Long = 20L * 1024 * 1024 * 1024        ' 20 GB

Dim report = clsStoreMerger.Merge(sources, "merged.pst",
                                  dedup:=New clsDedup(), overwrite:=True, maxBytes:=cap)

If report.ErrorCode = enmErrorCode.OutputSizeExceeded Then
    Console.WriteLine("Too big for one file - writing 20 GB volumes instead.")
    Dim vol = clsStoreMerger.MergeToVolumes(sources, "merged.pst", cap,
                                            dedup:=New clsDedup(), overwrite:=True)
    Console.WriteLine(If(vol.Succeeded, $"{vol.Volumes.Count} volume(s) written.", vol.ToString()))
ElseIf Not report.Succeeded Then
    Console.WriteLine(report.ToString())
End If

VB.NET — clean up a single PST (dedup + drop blanks + prune empties, keep its name)

Dim report = clsStoreMerger.Merge({"messy.pst"}, "clean.pst",
                                  dedup:=New clsDedup(),
                                  overwrite:=True,
                                  pruneEmpty:=True)   ' single source keeps its original store name
Console.WriteLine($"{report.DuplicatesRemoved:N0} duplicates, " &
                  $"{report.BlankMessagesRemoved:N0} blank, " &
                  $"{report.FoldersPruned:N0} empty folders removed.")

VB.NET — merge, then verify the result is complete and valid

Imports Bastion.Pst.Validation   ' clsPstHealth

Dim report = clsStoreMerger.Merge(sources, "merged.pst", dedup:=New clsDedup(), overwrite:=True)
If report.Succeeded Then
    Dim health = clsPstHealth.Check("merged.pst")
    Console.WriteLine(If(health.IsCorrupted, "PROBLEM: " & health.ToString(), "Output verified OK."))
End If

VB.NET — read every figure the merge report carries

Dim report = clsStoreMerger.Merge(sources, "merged.pst", dedup:=New clsDedup(),
                                  overwrite:=True, layout:=enmMergeLayout.Unified, pruneEmpty:=True)

Console.WriteLine($"code            : {CInt(report.ErrorCode)} ({report.ErrorDescription})")
Console.WriteLine($"items written   : {report.TotalNodes:N0}")
Console.WriteLine($"messages merged : {report.MessagesMerged:N0}")
Console.WriteLine($"duplicates      : {report.DuplicatesRemoved:N0}")
Console.WriteLine($"blank removed   : {report.BlankMessagesRemoved:N0}")
Console.WriteLine($"filtered out    : {report.FilteredOut:N0}")
Console.WriteLine($"folders pruned  : {report.FoldersPruned:N0}")
If report.Warning IsNot Nothing Then Console.WriteLine($"warning         : {report.Warning}")

VB.NET — react to specific error codes

Dim report = clsStoreMerger.Merge(sources, "merged.pst")   ' overwrite defaults to False

Select Case report.ErrorCode
    Case enmErrorCode.Ok
        Console.WriteLine("Merged.")
    Case enmErrorCode.DestinationExists
        Console.WriteLine("Output already exists - pass overwrite:=True to replace it.")
    Case enmErrorCode.FileLocked
        Console.WriteLine("A file is open in Outlook - close Outlook and retry.")
    Case enmErrorCode.DiskFull, enmErrorCode.InsufficientDiskSpace
        Console.WriteLine("Not enough disk space.")
    Case Else
        Console.WriteLine(report.ToString())    ' "code: description"
End Select

6. Export messages out of a PST (to EML or MSG files)

Export every message in a store to its own file — .eml (RFC 5322 / MIME) or .msg (Outlook message, [MS-OXMSG]) — with recipients and attachments, under a folder tree that mirrors the PST. Pass enmExportFormat.Eml or enmExportFormat.Msg. Add Imports Bastion.Pst.Export / using Bastion.Pst.Export;.

Dim diag As New clsDiagnostics With {.CreateUserLog = True, .RecoverFromCorruption = True}

Dim rep = clsStoreExporter.ExportToFolder("mail.pst", "C:\out\mail",
                                          enmExportFormat.Eml, diag, overwrite:=True)
If rep.ErrorCode <> enmErrorCode.Ok Then
    Console.WriteLine(rep.ToString())
Else
    Console.WriteLine($"{rep.FilesWritten:N0} message(s) written, " &
                      $"{rep.FoldersVisited:N0} folder(s), {rep.Failed:N0} skipped.")
End If

var diag = new clsDiagnostics { CreateUserLog = true, RecoverFromCorruption = true };

var rep = clsStoreExporter.ExportToFolder("mail.pst", @"C:\out\mail",
                                          enmExportFormat.Eml, diag, overwrite: true);
if (rep.ErrorCode != enmErrorCode.Ok)
    Console.WriteLine(rep.ToString());
else
    Console.WriteLine($"{rep.FilesWritten:N0} message(s) written, " +
                      $"{rep.FoldersVisited:N0} folder(s), {rep.Failed:N0} skipped.");

To export a single message you already have in hand, use clsMessageExporter.ExportEml(msg, "message.eml") or clsMessageExporter.ExportMsg(msg, "message.msg") (each returns a clsFileOpResult), or clsMessageExporter.ToEml(msg) for the MIME text. To export the whole store to .msg, pass enmExportFormat.Msg to ExportToFolder.

Reading a file safely (bonus)

The non-throwing open returns a result you check the same way.

Dim opened = clsPersonalStorage.TryOpen("mail.pst")
If opened.ErrorCode <> enmErrorCode.Ok Then
    Console.WriteLine(opened.ToString())
    Return
End If
Using store = opened.Store
    For Each folder In store.RootFolder.SubFolders()
        Console.WriteLine($"{folder.DisplayName}: {folder.ContentCount} items")
    Next
End Using

var opened = clsPersonalStorage.TryOpen("mail.pst");
if (opened.ErrorCode != enmErrorCode.Ok)
{
    Console.WriteLine(opened.ToString());
    return;
}
using (var store = opened.Store)
{
    foreach (var folder in store.RootFolder.SubFolders())
        Console.WriteLine($"{folder.DisplayName}: {folder.ContentCount} items");
}

Examples

A task-by-task cookbook covering every feature of the library, each in both VB.NET and C#. All snippets assume these imports/usings and follow the return-code pattern — check ErrorCode (0 = Ok); the library never throws into your code.

Imports Bastion.Pst               ' enmErrorCode, result types
Imports Bastion.Pst.Messaging     ' clsPersonalStorage, clsFolder, clsMessage, clsMessageQuery, enmItemKind
Imports Bastion.Pst.Convert       ' clsStoreMerger, clsStoreConverter, clsStoreSplitter, clsDedup, enmMergeLayout
Imports Bastion.Pst.Validation    ' clsPstValidator, clsPstHealth
Imports Bastion.Pst.Repair        ' clsPstRepair
Imports Bastion.Pst.Export        ' clsStoreBuilder, clsStoreExporter, clsMessageExporter, enmExportFormat
Imports Bastion.Pst.Import        ' clsEmlReader, clsMsgReader, clsMboxReader, clsStoreImporter
Imports Bastion.Pst.Authoring     ' clsAuthor, clsAuthoringSession, clsItemBuilder
Imports Bastion.Pst.Views         ' clsStoreViews, clsItemQuery, clsItemOps, clsContactMerger
Imports Bastion.Pst.Diagnostics   ' clsDiagnostics

using Bastion.Pst;
using Bastion.Pst.Messaging;
using Bastion.Pst.Convert;
using Bastion.Pst.Validation;
using Bastion.Pst.Repair;
using Bastion.Pst.Export;
using Bastion.Pst.Import;
using Bastion.Pst.Authoring;
using Bastion.Pst.Views;
using Bastion.Pst.Diagnostics;

1. Check a PST for corruption and repair it

clsPstHealth.Check inspects a file the moment you read it and never throws. If it is damaged, RepairTo rebuilds it into a fresh, validated file, and SaveSupportReport writes a privacy-safe report (structural metadata only).

Dim health = clsPstHealth.Check("mail.pst")
If health.ErrorCode <> enmErrorCode.Ok Then Console.WriteLine(health.ToString()) : Return

If health.IsCorrupted Then
    Console.WriteLine("Damage detected - repairing…")
    Dim report = health.SaveSupportReport()              ' empty path -> user temp; safe to email
    Console.WriteLine("Support report: " & report.Path)
    Dim fix = health.RepairTo("mail-repaired.pst")
    Console.WriteLine(If(fix.Succeeded, "Repaired -> mail-repaired.pst", fix.ToString()))
Else
    Console.WriteLine("Healthy.")
End If

var health = clsPstHealth.Check("mail.pst");
if (health.ErrorCode != enmErrorCode.Ok) { Console.WriteLine(health.ToString()); return; }

if (health.IsCorrupted)
{
    Console.WriteLine("Damage detected - repairing…");
    var report = health.SaveSupportReport();             // empty path -> user temp; safe to email
    Console.WriteLine("Support report: " + report.Path);
    var fix = health.RepairTo("mail-repaired.pst");
    Console.WriteLine(fix.Succeeded ? "Repaired -> mail-repaired.pst" : fix.ToString());
}
else Console.WriteLine("Healthy.");

For direct control, clsPstRepair.Repair(src, out, diag, overwrite, stripPassword) returns a clsRepairReport whose Succeeded is true only when the rebuilt file passes strict validation; it also carries before/after validation reports and NodesWritten.

2. Create a new, empty PST

clsStoreBuilder.CreateEmpty writes a fresh, Outlook-mountable empty store at the path you pass, and validates it (reopens it) before returning. The optional storeName sets the title Outlook shows for the store in its nav pane (omit it to keep the default “Outlook Data File”).

Dim res = clsStoreBuilder.CreateEmpty("C:\data\new.pst", overwrite:=True, storeName:="My Archive")
If res.ErrorCode = enmErrorCode.Ok Then
    Console.WriteLine("Created " & res.Path)
Else
    Console.WriteLine(res.ToString())      ' e.g. "7: The file ... already exists ..."
End If

var res = clsStoreBuilder.CreateEmpty(@"C:\data\new.pst", overwrite: true, storeName: "My Archive");
if (res.ErrorCode == enmErrorCode.Ok)
    Console.WriteLine("Created " + res.Path);
else
    Console.WriteLine(res.ToString());     // e.g. "7: The file ... already exists ..."

3. Merge two or more PSTs into one

See the Quick Start for the full option set. The essentials:

Dim diag As New clsDiagnostics With {.CreateUserLog = True, .RecoverFromCorruption = True}
Dim rep = clsStoreMerger.Merge({"a.pst", "b.pst", "c.pst"}, "merged.pst",
                               dedup:=New clsDedup(), diag:=diag, overwrite:=True,
                               layout:=enmMergeLayout.Unified, rootName:="All Mail", pruneEmpty:=True)
Console.WriteLine(If(rep.Succeeded,
    $"{rep.TotalNodes:N0} items, {rep.DuplicatesRemoved:N0} duplicates removed", rep.ToString()))

var diag = new clsDiagnostics { CreateUserLog = true, RecoverFromCorruption = true };
var rep = clsStoreMerger.Merge(new[] { "a.pst", "b.pst", "c.pst" }, "merged.pst",
                               dedup: new clsDedup(), diag: diag, overwrite: true,
                               layout: enmMergeLayout.Unified, rootName: "All Mail", pruneEmpty: true);
Console.WriteLine(rep.Succeeded
    ? $"{rep.TotalNodes:N0} items, {rep.DuplicatesRemoved:N0} duplicates removed" : rep.ToString());

4. Merge into size-capped volumes

Dim vol = clsStoreMerger.MergeToVolumes({"big1.pst", "big2.pst"}, "archive.pst",
                                        capBytes:=10L * 1024 * 1024 * 1024, overwrite:=True)
For Each v In vol.Volumes : Console.WriteLine($"{v.Path}: {v.Messages:N0} msgs") : Next

var vol = clsStoreMerger.MergeToVolumes(new[] { "big1.pst", "big2.pst" }, "archive.pst",
                                        capBytes: 10L * 1024 * 1024 * 1024, overwrite: true);
foreach (var v in vol.Volumes) Console.WriteLine($"{v.Path}: {v.Messages:N0} msgs");

5. Open a PST and walk its folders and messages

Dim opened = clsPersonalStorage.TryOpen("mail.pst")
If opened.ErrorCode <> enmErrorCode.Ok Then Console.WriteLine(opened.ToString()) : Return
Using store = opened.Store
    Walk(store.RootFolder, 0)
End Using

Sub Walk(folder As clsFolder, depth As Integer)
    Console.WriteLine(New String(" "c, depth * 2) & $"{folder.DisplayName} ({folder.ContentCount})")
    For Each m In folder.Messages()
        Console.WriteLine(New String(" "c, depth * 2 + 2) & $"- {m.Subject}")
    Next
    For Each child In folder.SubFolders() : Walk(child, depth + 1) : Next
End Sub

var opened = clsPersonalStorage.TryOpen("mail.pst");
if (opened.ErrorCode != enmErrorCode.Ok) { Console.WriteLine(opened.ToString()); return; }
using (var store = opened.Store)
    Walk(store.RootFolder, 0);

void Walk(clsFolder folder, int depth)
{
    Console.WriteLine(new string(' ', depth * 2) + $"{folder.DisplayName} ({folder.ContentCount})");
    foreach (var m in folder.Messages())
        Console.WriteLine(new string(' ', depth * 2 + 2) + $"- {m.Subject}");
    foreach (var child in folder.SubFolders()) Walk(child, depth + 1);
}

6. Read a message in full — sender, recipients, body, attachments

Dim m As clsMessage = ...   ' from folder.Messages() or a search hit
Console.WriteLine($"Subject : {m.Subject}")
Console.WriteLine($"From    : {m.SenderName} <{m.SenderEmail}>")
Console.WriteLine($"Sent    : {m.DeliveryTime}")
Console.WriteLine($"Unread  : {m.IsUnread}")
For Each r In m.Recipients
    Console.WriteLine($"  {r.RecipientType}: {r.DisplayName} <{r.SmtpAddress}>")
Next
Console.WriteLine(m.Body)
For Each a In m.Attachments
    Console.WriteLine($"  attachment: {a.FileName} ({a.Size:N0} bytes, {a.MimeTag})")
    Dim bytes = a.GetData()
    If bytes IsNot Nothing Then IO.File.WriteAllBytes(a.FileName, bytes)   ' save it
Next

clsMessage m = ...;   // from folder.Messages() or a search hit
Console.WriteLine($"Subject : {m.Subject}");
Console.WriteLine($"From    : {m.SenderName} <{m.SenderEmail}>");
Console.WriteLine($"Sent    : {m.DeliveryTime}");
Console.WriteLine($"Unread  : {m.IsUnread}");
foreach (var r in m.Recipients)
    Console.WriteLine($"  {r.RecipientType}: {r.DisplayName} <{r.SmtpAddress}>");
Console.WriteLine(m.Body);
foreach (var a in m.Attachments)
{
    Console.WriteLine($"  attachment: {a.FileName} ({a.Size:N0} bytes, {a.MimeTag})");
    var bytes = a.GetData();
    if (bytes != null) System.IO.File.WriteAllBytes(a.FileName, bytes);   // save it
}

7. Read non-mail items — appointments, contacts, tasks, notes

Every item exposes its Kind; calendar/contact fields are available directly.

For Each m In folder.Messages()
    Select Case m.Kind
        Case enmItemKind.Appointment
            Console.WriteLine($"Appt: {m.Subject}  {m.AppointmentStart}-{m.AppointmentEnd} @ {m.Location}")
        Case enmItemKind.Contact
            Console.WriteLine($"Contact: {m.Subject}  {m.ContactEmail}")
        Case enmItemKind.Mail
            Console.WriteLine($"Mail: {m.Subject}")
    End Select
Next

foreach (var m in folder.Messages())
{
    switch (m.Kind)
    {
        case enmItemKind.Appointment:
            Console.WriteLine($"Appt: {m.Subject}  {m.AppointmentStart}-{m.AppointmentEnd} @ {m.Location}"); break;
        case enmItemKind.Contact:
            Console.WriteLine($"Contact: {m.Subject}  {m.ContactEmail}"); break;
        case enmItemKind.Mail:
            Console.WriteLine($"Mail: {m.Subject}"); break;
    }
}

8. Search a PST with a fluent query

Using store = clsPersonalStorage.Open("mail.pst")
    Dim q = New clsMessageQuery().SubjectContains("invoice").
                                  SenderContains("acme.com").
                                  OfKind(enmItemKind.Mail).
                                  WithAttachments().Unread()
    For Each hit In store.Search(q)
        Console.WriteLine($"{hit.FolderPath}\{hit.Message.Subject}")
    Next
End Using

using (var store = clsPersonalStorage.Open("mail.pst"))
{
    var q = new clsMessageQuery().SubjectContains("invoice")
                                 .SenderContains("acme.com")
                                 .OfKind(enmItemKind.Mail)
                                 .WithAttachments().Unread();
    foreach (var hit in store.Search(q))
        Console.WriteLine($@"{hit.FolderPath}\{hit.Message.Subject}");
}

9. Convert a legacy ANSI PST/OST to Unicode

Dim res = clsStoreConverter.ConvertToUnicode("old-ansi.pst", "unicode.pst",
                                             New clsDiagnostics(), overwrite:=True)
Console.WriteLine(If(res.Succeeded, "Converted.", res.ToString()))

var res = clsStoreConverter.ConvertToUnicode("old-ansi.pst", "unicode.pst",
                                             new clsDiagnostics(), overwrite: true);
Console.WriteLine(res.Succeeded ? "Converted." : res.ToString());

10. Split a large PST into smaller parts

By size, or by any predicate over each message row (here: subject contains a word).

' by size: <= 2 GB parts
Dim r1 = clsStoreSplitter.SplitBySize("big.pst", "C:\out", 2L * 1024 * 1024 * 1024, New clsDiagnostics())
For Each p In r1.Parts : Console.WriteLine($"{p.Path}: {p.MessageCount:N0} msgs") : Next

' by predicate: everything whose subject contains "2024" into one file, the rest into another
Dim pred As Func(Of clsMessage, Boolean) =
    Function(m) (If(m.Subject, "")).IndexOf("2024", StringComparison.OrdinalIgnoreCase) >= 0
Dim r2 = clsStoreSplitter.SplitByPredicate("big.pst", "2024.pst", "rest.pst", pred, New clsDiagnostics())

// by size: <= 2 GB parts
var r1 = clsStoreSplitter.SplitBySize("big.pst", @"C:\out", 2L * 1024 * 1024 * 1024, new clsDiagnostics());
foreach (var p in r1.Parts) Console.WriteLine($"{p.Path}: {p.MessageCount:N0} msgs");

// by predicate: subject contains "2024" -> one file, the rest -> another
Func<clsMessage, bool> pred =
    m => (m.Subject ?? "").IndexOf("2024", StringComparison.OrdinalIgnoreCase) >= 0;
var r2 = clsStoreSplitter.SplitByPredicate("big.pst", "2024.pst", "rest.pst", pred, new clsDiagnostics());

11. Export messages out of a PST (EML, MSG, ICS, VCF, MHTML, MBOX)

The bulk exporter mirrors the folder tree; the per-message exporters produce one file. ICS covers appointments, VCF covers contacts (non-matching items are skipped), and MBOX writes one file per folder.

' whole store -> a folder tree of files in any format
Dim rep = clsStoreExporter.ExportToFolder("mail.pst", "C:\out", enmExportFormat.Eml,
                                          New clsDiagnostics(), overwrite:=True)
Console.WriteLine($"{rep.FilesWritten:N0} written, {rep.Failed:N0} skipped")
' …or enmExportFormat.Msg / .Ics / .Vcf / .Mhtml / .Mbox

' a single item you already hold
clsMessageExporter.ExportEml(m, "message.eml")     ' RFC 5322 / MIME
clsMessageExporter.ExportMsg(m, "message.msg")     ' Outlook [MS-OXMSG]
clsMessageExporter.ExportMhtml(m, "message.mhtml") ' web archive (RFC 2557)
clsItemExporter.ExportIcs(appt, "event.ics")       ' appointment -> iCalendar
clsItemExporter.ExportVcf(contact, "card.vcf")     ' contact -> vCard 3.0

// whole store -> a folder tree of files in any format
var rep = clsStoreExporter.ExportToFolder("mail.pst", @"C:\out", enmExportFormat.Eml,
                                          new clsDiagnostics(), overwrite: true);
Console.WriteLine($"{rep.FilesWritten:N0} written, {rep.Failed:N0} skipped");
// …or enmExportFormat.Msg / .Ics / .Vcf / .Mhtml / .Mbox

// a single item you already hold
clsMessageExporter.ExportEml(m, "message.eml");     // RFC 5322 / MIME
clsMessageExporter.ExportMsg(m, "message.msg");     // Outlook [MS-OXMSG]
clsMessageExporter.ExportMhtml(m, "message.mhtml"); // web archive (RFC 2557)
clsItemExporter.ExportIcs(appt, "event.ics");       // appointment -> iCalendar
clsItemExporter.ExportVcf(contact, "card.vcf");     // contact -> vCard 3.0

12. Validate a PST's structure (Outlook-style, without Outlook)

Dim v = clsPstValidator.Validate("mail.pst")
If v Is Nothing Then
    Console.WriteLine("ANSI/legacy or unreadable header.")
ElseIf v.IsValid Then
    Console.WriteLine($"VALID - {v.PagesChecked:N0} pages, {v.BlocksChecked:N0} blocks.")
Else
    Console.WriteLine($"INVALID - {v.ErrorCount} issue(s):")
    For Each grp In v.Issues.GroupBy(Function(i) i.Category)
        Console.WriteLine($"  {grp.Key} x{grp.Count()}: {grp.First().Message}")
    Next
End If

var v = clsPstValidator.Validate("mail.pst");
if (v == null)
    Console.WriteLine("ANSI/legacy or unreadable header.");
else if (v.IsValid)
    Console.WriteLine($"VALID - {v.PagesChecked:N0} pages, {v.BlocksChecked:N0} blocks.");
else
{
    Console.WriteLine($"INVALID - {v.ErrorCount} issue(s):");
    foreach (var grp in v.Issues.GroupBy(i => i.Category))
        Console.WriteLine($"  {grp.Key} x{grp.Count()}: {grp.First().Message}");
}

13. Verify folder counts match reality

Using store = clsPersonalStorage.Open("mail.pst")
    For Each f In AllFolders(store.RootFolder)
        Dim declared = f.ContentCount, actual = f.Messages().Count()
        If declared <> actual Then Console.WriteLine($"MISMATCH {f.DisplayName}: {declared} vs {actual}")
    Next
End Using

using (var store = clsPersonalStorage.Open("mail.pst"))
    foreach (var f in AllFolders(store.RootFolder))
    {
        int declared = f.ContentCount, actual = f.Messages().Count();
        if (declared != actual) Console.WriteLine($"MISMATCH {f.DisplayName}: {declared} vs {actual}");
    }

14. Track progress, log activity, and recover from corruption

One clsDiagnostics drives progress events, a plain-language user log, an automatic corruption scan on open, and skip-on-error recovery — pass it to any operation.

Dim diag As New clsDiagnostics With {
    .CreateUserLog = True,          ' plain-language activity log for end users
    .RecoverFromCorruption = True,  ' skip damaged items instead of aborting
    .ScanSourcesOnOpen = True}      ' detect corruption as soon as a source is opened
AddHandler diag.WriteProgress, Sub(s, e) Console.Write($"{vbCr}{e.PercentComplete}%   ")
AddHandler diag.ErrorOccurred, Sub(s, e) Console.WriteLine($"recovered: {e.Message}")

Dim rep = clsStoreMerger.Merge({"a.pst", "b.pst"}, "merged.pst", diag:=diag, overwrite:=True)
Console.WriteLine(vbCrLf & "activity log: " & diag.UserLogPath)

var diag = new clsDiagnostics {
    CreateUserLog = true,           // plain-language activity log for end users
    RecoverFromCorruption = true,   // skip damaged items instead of aborting
    ScanSourcesOnOpen = true };     // detect corruption as soon as a source is opened
diag.WriteProgress += (s, e) => Console.Write($"\r{e.PercentComplete}%   ");
diag.ErrorOccurred += (s, e) => Console.WriteLine($"recovered: {e.Message}");

var rep = clsStoreMerger.Merge(new[] { "a.pst", "b.pst" }, "merged.pst", diag: diag, overwrite: true);
Console.WriteLine("\nactivity log: " + diag.UserLogPath);

15. Handle every error the library can report

Dim rep = clsStoreMerger.Merge(sources, "merged.pst")
Select Case rep.ErrorCode
    Case enmErrorCode.Ok                     : Console.WriteLine("Done.")
    Case enmErrorCode.FileNotFound           : Console.WriteLine("A source is missing.")
    Case enmErrorCode.FileLocked             : Console.WriteLine("Close Outlook and retry.")
    Case enmErrorCode.DestinationExists      : Console.WriteLine("Pass overwrite:=True.")
    Case enmErrorCode.DiskFull,
         enmErrorCode.InsufficientDiskSpace  : Console.WriteLine("Free up disk space.")
    Case enmErrorCode.OutputSizeExceeded,
         enmErrorCode.NodeIdCapacityExceeded : Console.WriteLine("Use MergeToVolumes.")
    Case Else                                : Console.WriteLine(rep.ToString() & " / " & rep.Detail)
End Select

var rep = clsStoreMerger.Merge(sources, "merged.pst");
switch (rep.ErrorCode)
{
    case enmErrorCode.Ok:                     Console.WriteLine("Done."); break;
    case enmErrorCode.FileNotFound:           Console.WriteLine("A source is missing."); break;
    case enmErrorCode.FileLocked:             Console.WriteLine("Close Outlook and retry."); break;
    case enmErrorCode.DestinationExists:      Console.WriteLine("Pass overwrite: true."); break;
    case enmErrorCode.DiskFull:
    case enmErrorCode.InsufficientDiskSpace:  Console.WriteLine("Free up disk space."); break;
    case enmErrorCode.OutputSizeExceeded:
    case enmErrorCode.NodeIdCapacityExceeded: Console.WriteLine("Use MergeToVolumes."); break;
    default:                                  Console.WriteLine(rep.ToString() + " / " + rep.Detail); break;
}

16. Read an EML / MSG file into the message model

The import readers (Imports Bastion.Pst.Import) parse an interchange file into a neutral clsImportedMessage — headers, addresses, both bodies, and attachments (bytes decoded). They validate the input and return a result code; they never throw.

Dim res = clsEmlReader.ParseFile("message.eml")     ' or clsMsgReader.ParseFile("message.msg")
If res.ErrorCode <> enmErrorCode.Ok Then Console.WriteLine(res.ToString()) : Return
Dim m = res.Message
Console.WriteLine($"{m.Subject} — from {m.FromEmail}, {m.To.Count} to, {m.Attachments.Count} attachment(s)")
For Each a In m.Attachments
    IO.File.WriteAllBytes(a.FileName, a.Data)        ' save each attachment
Next

var res = clsEmlReader.ParseFile("message.eml");    // or clsMsgReader.ParseFile("message.msg")
if (res.ErrorCode != enmErrorCode.Ok) { Console.WriteLine(res.ToString()); return; }
var m = res.Message;
Console.WriteLine($"{m.Subject} — from {m.FromEmail}, {m.To.Count} to, {m.Attachments.Count} attachment(s)");
foreach (var a in m.Attachments)
    System.IO.File.WriteAllBytes(a.FileName, a.Data); // save each attachment

17. Read every message out of an MBOX file

For Each m In clsMboxReader.ReadFile("archive.mbox")
    Console.WriteLine($"{m.Date}  {m.FromEmail}  {m.Subject}")
Next

foreach (var m in clsMboxReader.ReadFile("archive.mbox"))
    Console.WriteLine($"{m.Date}  {m.FromEmail}  {m.Subject}");

18. Import EML / MSG / MBOX files into a PST

clsStoreImporter writes imported messages into a real PST — subject, sender, recipients, both bodies, internet headers and attachments become native Outlook properties. Pass an existing store to add to (its content is preserved; the result goes to a new output file), or Nothing/null to start from a fresh, empty store. The target folder path is relative to the mail root and is created if missing ("/" separates subfolders). Folder counts are maintained and the output is validated (reopened) before the call returns.

Imports Bastion.Pst.Import

' A whole MBOX archive into a brand-new PST. storeName sets the title Outlook shows in its nav
' pane (the same idea as the merge tool's rootName); omit it to keep the default "Outlook Data File".
Dim rep = clsStoreImporter.ImportMbox(Nothing, "archive.pst", "archive.mbox", "Imported/2026",
                                      storeName:="2026 Mail Archive")
Console.WriteLine(rep.ToString())        ' "OK: 433 message(s) imported (…)"

' Individual EML/MSG files into an existing store's Inbox (result written to out.pst):
rep = clsStoreImporter.ImportFiles("mail.pst", "out.pst",
                                   IO.Directory.GetFiles("mails", "*.eml"), "Inbox",
                                   overwrite:=True)
If rep.ErrorCode <> enmErrorCode.Ok Then Console.WriteLine(rep.ToString())
For Each line In rep.Failures : Console.WriteLine(line) : Next   ' per-file parse problems

using Bastion.Pst.Import;

// A whole MBOX archive into a brand-new PST. storeName titles the store in Outlook's nav pane.
var rep = clsStoreImporter.ImportMbox(null, "archive.pst", "archive.mbox", "Imported/2026",
                                      storeName: "2026 Mail Archive");
Console.WriteLine(rep.ToString());       // "OK: 433 message(s) imported (…)"

// Individual EML/MSG files into an existing store's Inbox (result written to out.pst):
rep = clsStoreImporter.ImportFiles("mail.pst", "out.pst",
                                   System.IO.Directory.GetFiles("mails", "*.eml"), "Inbox",
                                   overwrite: true);
if (rep.ErrorCode != enmErrorCode.Ok) Console.WriteLine(rep.ToString());
foreach (var line in rep.Failures) Console.WriteLine(line);      // per-file parse problems

19. Set, verify or remove the PST open password

A PST password is not encryption — Outlook stores only a CRC hash of the password on the message store and prompts on open. clsStorePassword reads that state (GetStatus), sets or clears it (SetPassword / RemovePassword — atomic, validated output; pass the same path twice with overwrite:=True to change a file in place), and computes the hash Outlook would store (ComputeCrc) so you can verify a user-typed password before opening. The hash is bit-identical to Outlook's (verified against an independent implementation).

' Is the file password-protected?
Dim status = clsStorePassword.GetStatus("mail.pst")
If status.ErrorCode <> enmErrorCode.Ok Then Console.WriteLine(status.ToString()) : Return
Console.WriteLine(If(status.HasPassword, "Password is set.", "No password."))

' Verify what the user typed without touching the file:
If clsStorePassword.ComputeCrc(userTyped) = status.PasswordCrc Then Console.WriteLine("Correct.")

' Set a password (writes locked.pst; mail.pst is untouched):
Dim setRep = clsStorePassword.SetPassword("mail.pst", "locked.pst", "s3cret!")
Console.WriteLine(If(setRep.Succeeded, "Password set and output validated.", setRep.ToString()))

' Remove it in place:
Dim remRep = clsStorePassword.RemovePassword("locked.pst", "locked.pst", overwrite:=True)
Console.WriteLine(If(remRep.Succeeded, "Opens without a prompt now.", remRep.ToString()))

// Is the file password-protected?
var status = clsStorePassword.GetStatus("mail.pst");
if (status.ErrorCode != enmErrorCode.Ok) { Console.WriteLine(status.ToString()); return; }
Console.WriteLine(status.HasPassword ? "Password is set." : "No password.");

// Verify what the user typed without touching the file:
if (clsStorePassword.ComputeCrc(userTyped) == status.PasswordCrc) Console.WriteLine("Correct.");

// Set a password (writes locked.pst; mail.pst is untouched):
var setRep = clsStorePassword.SetPassword("mail.pst", "locked.pst", "s3cret!");
Console.WriteLine(setRep.Succeeded ? "Password set and output validated." : setRep.ToString());

// Remove it in place:
var remRep = clsStorePassword.RemovePassword("locked.pst", "locked.pst", overwrite: true);
Console.WriteLine(remRep.Succeeded ? "Opens without a prompt now." : remRep.ToString());

20. Author Outlook items from code (mail, appointment, contact, task, note, journal, list)

The fluent builders in Bastion.Pst.Authoring produce every item type. Hand the items to clsAuthor.CreateStoreWith (a new store) or AddItems (an existing one); the target folder is created on demand.

Dim mail = clsItemBuilder.Mail().Subject("Welcome").From("Team", "team@x.test").
              [To]("Ada", "ada@x.test").BodyText("Hello!").
              AddAttachment("logo.png", pngBytes, "image/png").Build()
Dim contact = clsItemBuilder.Contact().Name("Ada", "Lovelace").Company("Analytical").
                 Email("ada@x.test").Phone(business:="+44 20 0000").Build()
Dim task = clsItemBuilder.Task().Subject("Ship v1").Status(1).PercentComplete(0.5).
              DueDate(New Date(2026, 7, 20)).Build()
Dim note = clsItemBuilder.Note().Text("Remember the milk").Color(3).Build()
Dim journal = clsItemBuilder.Journal().Subject("Call with Ada").JournalType("Phone call").
                 DurationMinutes(15).Build()
Dim list = clsItemBuilder.DistributionList().Name("Team").
              AddMember("Ada", "ada@x.test").AddMember("Alan", "alan@x.test").Build()

Dim r = clsAuthor.CreateStoreWith("new.pst", {mail}, "Inbox", storeName:="My Data")
clsAuthor.AddItems("new.pst", "new.pst", {contact, list}, "Contacts", overwrite:=True)

var appt = clsItemBuilder.Appointment().Subject("Weekly standup")
              .StartsAt(new DateTime(2026, 7, 8, 9, 0, 0, DateTimeKind.Utc))
              .EndsAt(new DateTime(2026, 7, 8, 9, 30, 0, DateTimeKind.Utc))
              .RecurWeekly(days: enmRecurDays.Monday, occurrences: 10)   // a recurring series…
              .ExcludeOccurrences(new DateTime(2026, 8, 31))             // …skipping a bank holiday
              .Build();
var r = clsAuthor.AddItems("new.pst", "new.pst", new[] { appt }, "Calendar", overwrite: true);

21. Batch several edits into one atomic write (authoring session)

The session verbs are RenameFolder, SetFolderClass, MoveFolder, DeleteFolder, MoveItems, DeleteItems, EditItems and RemoveAttachments. Creating a folder and adding items are not session verbs — use clsAuthor.CreateFolder and clsAuthor.AddItems for those, then batch the edits.

Dim rep = New clsAuthoringSession("data.pst").
    RenameFolder("Old", "Archive").
    SetFolderClass("Archive", clsFolderClass.Mail).
    DeleteItems("Spam", Function(m) m.Subject.Contains("[AD]")).
    Commit("out.pst", overwrite:=True)      ' one rewrite; ErrorCode 0 == all applied

var rep = new clsAuthoringSession("data.pst")
    .RenameFolder("Old", "Archive")
    .SetFolderClass("Archive", clsFolderClass.Mail)
    .DeleteItems("Spam", m => m.Subject.Contains("[AD]"))
    .Commit("out.pst", overwrite: true);      // one rewrite; ErrorCode 0 == all applied

22. Make a folder a calendar, contacts or tasks folder

A folder is a mail folder ("IPF.Note") until you say otherwise. Its container class (PidTagContainerClass) is what tells Outlook — and any other client — to render a calendar grid instead of a message list, so this is the step that turns an authored folder into a real Calendar or Contacts folder. Use the clsFolderClass constants rather than typing the strings.

The value is written to both the folder's own property context and its row in the parent's hierarchy table, because different readers consult different ones.

' One folder, one call. The source is never modified — every edit is an atomic rewrite.
Dim rep = clsAuthor.SetFolderClass("data.pst", "out.pst", "Team Calendar",
                                   clsFolderClass.Appointment, overwrite:=True)
Console.WriteLine($"{rep.FoldersReclassified} folder(s) reclassified.")

' Read it back — this is also how you audit an existing store's folder kinds.
Using pst = clsPersonalStorage.Open("out.pst")
    For Each top In pst.RootFolder.SubFolders()
        For Each f In top.SubFolders()
            Console.WriteLine($"[{f.DisplayName}] {f.ContainerClass}")
        Next
    Next
End Using

// One folder, one call. The source is never modified — every edit is an atomic rewrite.
var rep = clsAuthor.SetFolderClass("data.pst", "out.pst", "Team Calendar",
                                   clsFolderClass.Appointment, overwrite: true);
Console.WriteLine($"{rep.FoldersReclassified} folder(s) reclassified.");

// Read it back — this is also how you audit an existing store's folder kinds.
using var pst = clsPersonalStorage.Open("out.pst");
foreach (var top in pst.RootFolder.SubFolders())
    foreach (var f in top.SubFolders())
        Console.WriteLine($"[{f.DisplayName}] {f.ContainerClass}");

Every authoring call rewrites the whole store, so type a whole mailbox in one rewrite with a session rather than one rewrite per folder:

Dim rep = New clsAuthoringSession("data.pst").
    SetFolderClass("Team Calendar", clsFolderClass.Appointment).
    SetFolderClass("Team Contacts", clsFolderClass.Contact).
    Commit("mailbox.pst", overwrite:=True)

var rep = new clsAuthoringSession("data.pst")
    .SetFolderClass("Team Calendar", clsFolderClass.Appointment)
    .SetFolderClass("Team Contacts", clsFolderClass.Contact)
    .Commit("mailbox.pst", overwrite: true);

Creating a folder is not a session verb — use clsAuthor.CreateFolder first, then type the finished tree in one commit.

Set-PstFolderClass C:\mail.pst -Destination C:\out.pst `
                   -Folder 'Team Calendar' -ContainerClass IPF.Appointment
Get-PstFolder C:\out.pst | Select-Object Name, Class

The classes. clsFolderClass.Mail ("IPF.Note", the default), Appointment, Contact, Task, StickyNote, Journal, Birthday, Homepage. An unset class is treated as mail, so a mail folder does not strictly need one stamped on it.

It identifies a kind, not an identity. The class is inherited by subfolders in practice — every folder under a Calendar is usually IPF.Appointment too — so two sibling folders can legitimately share one. Never use it alone to decide that two folders are "the same folder".

23. Clone just the folder structure of a store

// A new, empty Unicode PST mirroring the source's folder tree (no messages copied).
var rep = clsStoreImporter.CloneStructure("live.pst", "template.pst", overwrite: true);
Console.WriteLine($"{rep.FoldersCreated} folders mirrored.");

24. Import an Outlook-for-Mac .olm archive into a PST

OLM is Outlook for Mac's export format (a ZIP of XML). ImportOlm reads the mail and recreates the OLM folder hierarchy in a new Unicode PST.

var rep = clsStoreImporter.ImportOlm("MacExport.olm", "converted.pst", overwrite: true);
Console.WriteLine($"{rep.MessagesImported} messages into {rep.FoldersCreated} folders.");

// …or read the items into the neutral model without writing a PST:
foreach (var m in clsOlmReader.ReadFile("MacExport.olm"))
    Console.WriteLine($"[{m.SourceFolder}] {m.Subject}  ({m.Attachments.Count} attachments)");

25. Cancel a long operation, and stay safe on legacy ANSI stores

Every long operation honours a CancellationToken; because writes are atomic, a cancellation leaves the destination untouched. And because the library only writes Unicode, adding to or editing a legacy ANSI store would rewrite it as Unicode — which Outlook 2002 and earlier cannot open — so that upgrade is refused by default and must be authorised explicitly.

// --- cancellation ---
var cts = new CancellationTokenSource();
var diag = new clsDiagnostics { CancellationToken = cts.Token };
// cts.Cancel() from your UI thread… the call returns enmErrorCode.OperationCancelled, nothing written.
var conv = clsStoreConverter.ConvertToUnicode("huge.pst", "out.pst", diag, overwrite: true);

// --- ANSI safety gate ---
if (clsPersonalStorage.IsAnsi("legacy.pst"))                 // cheap header-only pre-flight
    Warn("Legacy ANSI file — adding items upgrades it to Unicode (Outlook 2002- can't open it).");

var g = new clsDiagnostics();
g.AnsiUpgradeRequired += (s, e) => e.Proceed = UserConfirmed;  // the hard yes/no
var add = clsAuthor.AddItems("legacy.pst", "out.pst", items, "Inbox", g);
if (add.ErrorCode == enmErrorCode.AnsiUpgradeRequired) { /* declined — source untouched */ }

26. Show a mailbox — one bindable list per section

store.Views is the read model a host application binds to: flat rows, not a message graph, so a grid binds to Mail(), a card view to Contacts() and a scheduler to Appointments(). The rows are plain data — no store handles, no lazy reads — so they are safe to hold and to bind, and a damaged item yields a row with blank fields rather than taking the view down. Which folders hold contacts, which hold feeds, and which are Outlook's hidden address-book plumbing is decided here, once, instead of in every host that shows a mailbox.

Note that RSS posts are a section of their own. Outlook files them under a container class that is a variation on “mail”, so anywhere else they are swept in with your messages — in one real archive that was nearly 13,000 posts inflating the mail counts.

Using store = clsPersonalStorage.Open("mail.pst")

    For Each m In store.Views.Mail(New clsItemQuery().Take(200))
        Console.WriteLine($"{m.FromDisplay}  {m.Display}  {m.Date:d}" &
                          If(m.IsUnread, "  unread", "") & If(m.HasAttachments, "  clip", ""))
    Next

    For Each c In store.Views.Contacts()
        Console.WriteLine($"{c.SortKey}  {c.Email}  {c.Phone}")     ' c.Photo is the card picture
    Next

    For Each a In store.Views.Appointments()
        Console.WriteLine($"{a.Display}  {a.StartTime:g}-{a.EndTime:t} @{a.Location}")
    Next

    For Each t In store.Views.Tasks()
        Console.WriteLine($"{t.Display}  {t.StatusText}  {t.PercentComplete:P0}" &
                          If(t.IsOverdue, "  OVERDUE", ""))
    Next

    For Each n In store.Views.Notes() : Console.WriteLine(n.Display) : Next
    For Each r In store.Views.Rss()   : Console.WriteLine($"[{r.FeedName}] {r.Display}") : Next
End Using

using var store = clsPersonalStorage.Open("mail.pst");

foreach (var m in store.Views.Mail(new clsItemQuery().Take(200)))
    Console.WriteLine($"{m.FromDisplay}  {m.Display}  {m.Date:d}"
                      + (m.IsUnread ? "  unread" : "") + (m.HasAttachments ? "  clip" : ""));

foreach (var c in store.Views.Contacts())
    Console.WriteLine($"{c.SortKey}  {c.Email}  {c.Phone}");        // c.Photo is the card picture

foreach (var a in store.Views.Appointments())
    Console.WriteLine($"{a.Display}  {a.StartTime:g}-{a.EndTime:t} @{a.Location}");

foreach (var t in store.Views.Tasks())
    Console.WriteLine($"{t.Display}  {t.StatusText}  {t.PercentComplete:P0}"
                      + (t.IsOverdue ? "  OVERDUE" : ""));

foreach (var n in store.Views.Notes()) Console.WriteLine(n.Display);
foreach (var r in store.Views.Rss())   Console.WriteLine($"[{r.FeedName}] {r.Display}");

Every view is a lazy IEnumerable, so LINQ composes over it and nothing is materialised until you enumerate. Each row carries Nid, FolderPath, FolderNid and StorePath — enough to act on the item later without re-walking the tree, which matters when the host has several files open at once.

27. List one folder, then read the one item the user clicked

This is what a mailbox UI actually does, and the two halves have deliberately different shapes. A list row must be thin — a mail list of 97,803 rows must not carry 97,803 message bodies — so MailIn reads the folder's contents table and nothing else: a 23,000-message Inbox costs one table read rather than 23,000 message opens. Detail is the read that happens on selection, and it decides which body to show (a message may hold HTML, RTF, plain, or several) rather than leaving every caller to guess. Attachment bytes are fetched only when the user actually saves or opens one.

Using store = clsPersonalStorage.Open("mail.pst")
    Dim folder = ...                                    ' the folder the user clicked

    ' The list: one table read, no message opened.
    Dim rows = store.Views.MailIn(folder).ToList()

    ' The selection: everything needed to display ONE item, in a single pass.
    Dim d = store.Views.Detail(folder, rows(0).Nid)
    Console.WriteLine($"{d.Subject} - from {d.SenderName} <{d.SenderEmail}> to {d.DisplayTo}")
    RenderBody(If(d.HasHtml, d.BodyHtml, d.BodyPlain), asHtml:=d.HasHtml)

    ' Inline images belong in the body, not the paperclip list.
    For Each a In d.Attachments.Where(Function(x) Not x.IsInline)
        Dim bytes = store.Views.AttachmentBytes(folder, d.Nid, a.Index)     ' on demand
        IO.File.WriteAllBytes(IO.Path.Combine(saveDir, a.FileName), bytes)
    Next

    ' The folders that make up a section, so the host can offer them as a list.
    For Each sf In store.Views.SectionFolders(enmSection.Calendar)
        Console.WriteLine($"{sf.FullPath}  [{sf.ItemCount:N0}]")
    Next
End Using

using var store = clsPersonalStorage.Open("mail.pst");
var folder = ...;                                       // the folder the user clicked

// The list: one table read, no message opened.
var rows = store.Views.MailIn(folder).ToList();

// The selection: everything needed to display ONE item, in a single pass.
var d = store.Views.Detail(folder, rows[0].Nid);
Console.WriteLine($"{d.Subject} - from {d.SenderName} <{d.SenderEmail}> to {d.DisplayTo}");
RenderBody(d.HasHtml ? d.BodyHtml : d.BodyPlain, asHtml: d.HasHtml);

// Inline images belong in the body, not the paperclip list.
foreach (var a in d.Attachments.Where(x => !x.IsInline))
{
    var bytes = store.Views.AttachmentBytes(folder, d.Nid, a.Index);        // on demand
    File.WriteAllBytes(Path.Combine(saveDir, a.FileName), bytes);
}

// The folders that make up a section, so the host can offer them as a list.
foreach (var sf in store.Views.SectionFolders(enmSection.Calendar))
    Console.WriteLine($"{sf.FullPath}  [{sf.ItemCount:N0}]");

28. Filter before an item is opened

A LINQ predicate over items can only run once each item has been read, so “mail from Chris in 2011” expressed as a Where opens all 108,892 messages in a large archive and discards almost every one. A folder's contents table already holds the columns a list shows — subject, sender, dates, class, size, flags — so a clsItemQuery is matched against the table row first, and only rows that survive cause the item to be opened.

Anything the table cannot answer (a body search, a contact's phone number) still needs the item and is expressed with Where(…) or BodyContains(…), which run after opening. Order matters: cheap criteria in the query, expensive ones after.

' Answered entirely by the contents table - nothing is opened to reject a row.
Dim cheap = New clsItemQuery().
    SenderContains("chris").
    DateFrom(#2011-01-01#).DateBefore(#2012-01-01#).
    WithAttachments().
    LargerThan(64 * 1024).
    Unread().
    Take(200)
For Each m In store.Views.Mail(cheap) : Console.WriteLine(m.Display) : Next

' Needs the item - but only for rows the cheap pass already let through.
Dim expensive = New clsItemQuery().SubjectContains("invoice").BodyContains("overdue")

' Confine the walk to part of the tree.
Dim sent = store.Views.Mail(New clsItemQuery().InFolder("Sent Items"))
Dim archives = store.Views.Mail(New clsItemQuery().InFolders(Function(p) p.Contains("Archive")))

// Answered entirely by the contents table - nothing is opened to reject a row.
var cheap = new clsItemQuery()
    .SenderContains("chris")
    .DateFrom(new DateTime(2011, 1, 1)).DateBefore(new DateTime(2012, 1, 1))
    .WithAttachments()
    .LargerThan(64 * 1024)
    .Unread()
    .Take(200);
foreach (var m in store.Views.Mail(cheap)) Console.WriteLine(m.Display);

// Needs the item - but only for rows the cheap pass already let through.
var expensive = new clsItemQuery().SubjectContains("invoice").BodyContains("overdue");

// Confine the walk to part of the tree.
var sent     = store.Views.Mail(new clsItemQuery().InFolder("Sent Items"));
var archives = store.Views.Mail(new clsItemQuery().InFolders(p => p.Contains("Archive")));

29. One card per person — folding duplicate contacts

An archive stores the same person over and over: once per source mailbox, plus a stub every time a field was added. In a real 9.4 GB archive 852 stored contacts were 307 people — the same name five times, one entry holding the phone, another the e-mail, another the company. clsContactMerger folds them together for display: nothing is written and nothing is thrown away. Fields come from whichever entry has them, values that genuinely disagree are kept as alternates, and each row records how many entries it came from and which folders they were in.

Outlook's hidden address-book folders (Recipient Cache, Suggested Contacts, PersonMetadata…) carry a contacts container class but hold plumbing rather than people — in one archive they outnumbered the genuine contacts ten to one — so they are excluded unless you ask for them.

A contacts folder also holds groups (distribution lists), which have none of a person's fields. A row for one carries IsDistributionList, its Members (name and address apiece, decoded from the one-off EntryIDs) and a ready-made MembershipSummary; Combine never folds a group into a person. A host that ignores the flag draws a card with every line blank, which is exactly what the property model used to give it.

foreach (var row in store.Views.Contacts())
{
    if (row.IsDistributionList)
        Console.WriteLine($"{row.Display}  ({row.MembershipSummary}): {row.MemberNames}");
    else
        Console.WriteLine($"{row.Display}  {row.Email}  {row.Phone}");
}

Using store = clsPersonalStorage.Open("mail.pst")
    store.Views.IncludeHiddenFolders = False            ' the default: no Recipient Cache et al.

    Dim stored = store.Views.Contacts().ToList()
    Dim people = clsContactMerger.Combine(stored)       ' or CombineByEmail(...) to key on address
    Console.WriteLine($"{stored.Count:N0} entries -> {people.Count:N0} cards")

    For Each p In people
        Console.WriteLine($"{p.Display}  {p.Email}  {p.Phone}")
        If p.MergedFrom > 1 Then
            Console.WriteLine($"   built from {p.MergedFrom} entries in {String.Join(", ", p.SourceFolders)}")
            For Each alt In p.AlternateEmails : Console.WriteLine("   also: " & alt) : Next
        End If
        If p.Photo IsNot Nothing Then IO.File.WriteAllBytes($"{p.Display}.jpg", p.Photo)
    Next
End Using

using var store = clsPersonalStorage.Open("mail.pst");
store.Views.IncludeHiddenFolders = false;               // the default: no Recipient Cache et al.

var stored = store.Views.Contacts().ToList();
var people = clsContactMerger.Combine(stored);          // or CombineByEmail(...) to key on address
Console.WriteLine($"{stored.Count:N0} entries -> {people.Count:N0} cards");

foreach (var p in people)
{
    Console.WriteLine($"{p.Display}  {p.Email}  {p.Phone}");
    if (p.MergedFrom > 1)
    {
        Console.WriteLine($"   built from {p.MergedFrom} entries in {string.Join(", ", p.SourceFolders)}");
        foreach (var alt in p.AlternateEmails) Console.WriteLine("   also: " + alt);
    }
    if (p.Photo != null) File.WriteAllBytes($"{p.Display}.jpg", p.Photo);
}

30. Watch what the library is doing (progress, without polling)

Subscribe once to clsPstEvents.Default and you are told when a store opens, how far a folder read has got, when a folder's items have been counted, when a store closes and when something goes wrong — from anywhere in the library, with no callback threaded through every call. The read event carries a real total, known the moment the contents table is open, so a host can show a percentage rather than an indeterminate bar: the point is to reassure the user that a six-figure folder is loading, not that the application has hung.

Threading: events are raised on whatever thread does the work — often a background reader — so a UI host must marshal (Control.BeginInvoke) before touching controls.

AddHandler clsPstEvents.Default.PstOpen,
    Sub(s, e) Log($"opened {e.Path}")
AddHandler clsPstEvents.Default.PstFolderSelected,
    Sub(s, e) ShowLoading($"{e.Folder}: {e.ItemCount:N0} items")
AddHandler clsPstEvents.Default.PstRead,
    Sub(s, e) UiThread(Sub() bar.Value = e.Percent)         ' Current / Total / Percent
AddHandler clsPstEvents.Default.PstError,
    Sub(s, e) Log($"{e.ErrorCode}: {e.Message} ({e.Path})")
AddHandler clsPstEvents.Default.PstClose,
    Sub(s, e) HideLoading()

clsPstEvents.Default.PstOpen           += (s, e) => Log($"opened {e.Path}");
clsPstEvents.Default.PstFolderSelected += (s, e) => ShowLoading($"{e.Folder}: {e.ItemCount:N0} items");
clsPstEvents.Default.PstRead           += (s, e) => UiThread(() => bar.Value = e.Percent);
clsPstEvents.Default.PstError          += (s, e) => Log($"{e.ErrorCode}: {e.Message} ({e.Path})");
clsPstEvents.Default.PstClose          += (s, e) => HideLoading();

31. Save, copy, move, delete and import — the verbs a host application needs

clsItemOps is the operation layer an application would otherwise write itself, and get subtly wrong: it knows how to copy a contact as well as a message, how to save a .vcf as well as a .msg, and it answers “can this store be written to?” in one place. Two rules hold throughout:

• Nothing is ever written to a source. A copy exports from the source read-only and imports into the target; a move is a copy followed by a delete on the target's own rewrite. Each operation names the file to write, which the caller then swaps in.
• A read-only store never accepts data. Legacy ANSI files are read-only because writing to one silently converts it to the modern format and stops older Outlook versions opening it — so the guard lives here rather than at each call site.

' Ask the library why, rather than inventing your own wording for the user.
If Not clsItemOps.IsWritable(target) Then MessageBox.Show(clsItemOps.WhyNotWritable(target)) : Return

' Save to disk in a format other applications open: mail/.msg, contacts/.vcf, appointments/.ics,
' notes/.txt - or force one format for the lot. Cancellable, and it reports progress.
Dim rep = clsItemOps.SaveItems(storePath, folderPath, nids, "C:\out",
                               enmSaveFormat.Native, cts.Token, Sub(n) bar.Value = n)
Console.WriteLine(If(rep.Ok, $"saved {rep.Saved} file(s)", rep.Error))

' Copy into another data file. Every kind copies with full fidelity - recipients, attachments,
' MAPI properties - because each item goes out as a native .msg and back in.
Dim c = clsItemOps.CopyItems(sourcePath, sourceFolder, nids, targetPath, targetOut, "Inbox", diag)

' Move and delete are the same shape.
Dim m = clsItemOps.MoveItems(storePath, outPath, "Inbox", "Archive", nids, diag)
Dim d = clsItemOps.DeleteItems(storePath, outPath, "Inbox", nids, diag)

' Import .msg .eml .ics .vcf .mbox into a folder.
Dim i = clsItemOps.ImportFiles(storePath, outPath, "Inbox", files, diag)

// Ask the library why, rather than inventing your own wording for the user.
if (!clsItemOps.IsWritable(target)) { MessageBox.Show(clsItemOps.WhyNotWritable(target)); return; }

// Save to disk in a format other applications open: mail/.msg, contacts/.vcf, appointments/.ics,
// notes/.txt - or force one format for the lot. Cancellable, and it reports progress.
var rep = clsItemOps.SaveItems(storePath, folderPath, nids, @"C:\out",
                               enmSaveFormat.Native, cts.Token, n => bar.Value = n);
Console.WriteLine(rep.Ok ? $"saved {rep.Saved} file(s)" : rep.Error);

// Copy into another data file. Every kind copies with full fidelity - recipients, attachments,
// MAPI properties - because each item goes out as a native .msg and back in.
var c = clsItemOps.CopyItems(sourcePath, sourceFolder, nids, targetPath, targetOut, "Inbox", diag);

// Move and delete are the same shape.
var m = clsItemOps.MoveItems(storePath, outPath, "Inbox", "Archive", nids, diag);
var d = clsItemOps.DeleteItems(storePath, outPath, "Inbox", nids, diag);

// Import .msg .eml .ics .vcf .mbox into a folder.
var i = clsItemOps.ImportFiles(storePath, outPath, "Inbox", files, diag);

Every write is an atomic rewrite through the authoring pipeline: the new file is built, verified and swapped in, so an interrupted operation leaves the original untouched.

32. Build a whole mailbox — attendees, photos, feed posts, and many folders in one pass

The builders cover the parts of a mailbox that are easy to get wrong by hand: a meeting's organiser and attendee list, a recurring series with one instance moved and another cancelled, a contact photo, read state and importance, and RSS posts filed where Outlook files them. Exception dates must land on an occurrence of the series — the library refuses one that does not, rather than writing a calendar Outlook would silently misread.

Then fill the store in one pass. Because every write is a whole-file rewrite, an import call per folder is O(S·k) I/O where one call that groups by folder is O(S) — the difference between minutes and hours on a large store.

Dim items As New List(Of clsImportedMessage)()

Dim mail = clsItemBuilder.Mail().
    Subject("Q3 numbers").From("Dana Ruiz", "dana@example.com").To("You", "you@example.com").
    BodyHtml("<p>Attached.</p>").SentOn(Date.Now.AddDays(-2)).
    Read(False).Importance(2).Build()                       ' arrives unread, flagged high
mail.SourceFolder = "Inbox" : items.Add(mail)

Dim first = NextTuesday(Date.Today).AddHours(10)
Dim meeting = clsItemBuilder.Appointment().
    Subject("Design review").Location("Room 2").
    StartsAt(first).EndsAt(first.AddHours(1)).
    Organiser("Dana Ruiz", "dana@example.com").
    Attendee("You", "you@example.com").OptionalAttendee("Sam Okafor", "sam@example.com").
    Reminder(15).
    RecurWeekly(enmRecurDays.Tuesday, occurrences:=8).
    ModifyOccurrence(first.AddDays(7), newStart:=first.AddDays(7).AddHours(4)).   ' moved to 14:00
    ExcludeOccurrences(first.AddDays(14)).                                        ' cancelled
    Build()
meeting.SourceFolder = "Calendar" : items.Add(meeting)

Dim contact = clsItemBuilder.Contact().
    Name("Sam", "Okafor").Company("Example Ltd").JobTitle("Architect").
    Email("sam@example.com").Phone(business:="+44 20 7946 0000", mobile:="+44 7700 900000").
    Photo(IO.File.ReadAllBytes("sam.jpg")).Build()          ' the picture on the card
contact.SourceFolder = "Contacts" : items.Add(contact)

Dim post = clsItemBuilder.Rss().
    Subject("Release 3.1 is out").Channel("Example Blog", "https://example.com/feed").
    Article("https://example.com/3-1").PostedOn(Date.Now.AddDays(-1)).Read(False).Build()
post.SourceFolder = "RSS Feeds\Example Blog" : items.Add(post)

' ONE pass over the store for every folder; extraFolders are created empty, ready for the user.
Dim rep = clsStoreImporter.ImportMessagesByFolder(Nothing, "new-mailbox.pst", items,
              defaultFolder:="Inbox", extraFolders:={"Tasks", "Notes"},
              diag:=New clsDiagnostics(), overwrite:=True, storeName:="Authored Mailbox")

var items = new List<clsImportedMessage>();

var mail = clsItemBuilder.Mail()
    .Subject("Q3 numbers").From("Dana Ruiz", "dana@example.com").To("You", "you@example.com")
    .BodyHtml("<p>Attached.</p>").SentOn(DateTime.Now.AddDays(-2))
    .Read(false).Importance(2).Build();                     // arrives unread, flagged high
mail.SourceFolder = "Inbox"; items.Add(mail);

var first = NextTuesday(DateTime.Today).AddHours(10);
var meeting = clsItemBuilder.Appointment()
    .Subject("Design review").Location("Room 2")
    .StartsAt(first).EndsAt(first.AddHours(1))
    .Organiser("Dana Ruiz", "dana@example.com")
    .Attendee("You", "you@example.com").OptionalAttendee("Sam Okafor", "sam@example.com")
    .Reminder(15)
    .RecurWeekly(enmRecurDays.Tuesday, occurrences: 8)
    .ModifyOccurrence(first.AddDays(7), newStart: first.AddDays(7).AddHours(4))    // moved to 14:00
    .ExcludeOccurrences(first.AddDays(14))                                         // cancelled
    .Build();
meeting.SourceFolder = "Calendar"; items.Add(meeting);

var contact = clsItemBuilder.Contact()
    .Name("Sam", "Okafor").Company("Example Ltd").JobTitle("Architect")
    .Email("sam@example.com").Phone(business: "+44 20 7946 0000", mobile: "+44 7700 900000")
    .Photo(File.ReadAllBytes("sam.jpg")).Build();           // the picture on the card
contact.SourceFolder = "Contacts"; items.Add(contact);

var post = clsItemBuilder.Rss()
    .Subject("Release 3.1 is out").Channel("Example Blog", "https://example.com/feed")
    .Article("https://example.com/3-1").PostedOn(DateTime.Now.AddDays(-1)).Read(false).Build();
post.SourceFolder = @"RSS Feeds\Example Blog"; items.Add(post);

// ONE pass over the store for every folder; extraFolders are created empty, ready for the user.
var rep = clsStoreImporter.ImportMessagesByFolder(null, "new-mailbox.pst", items,
              defaultFolder: "Inbox", extraFolders: new[] { "Tasks", "Notes" },
              diag: new clsDiagnostics(), overwrite: true, storeName: "Authored Mailbox");

32. Drive Bastion PST SDK from PowerShell

Bastion PST SDK is an ordinary .NET assembly, so PowerShell can drive all of it with Add-Type and no COM, no Outlook and no MAPI — which makes it a practical tool for the jobs administrators actually have: auditing a directory full of archives, pulling a mailbox out to files, merging a decade of PSTs, or checking a hundred files for corruption overnight. The distribution ships a ready-made module, samples/PowerShell/Bastion.Pst.psm1, with fourteen worked tasks beside it in Examples.ps1.

Import-Module .\Bastion.Pst.psm1

# What is in this file?
Get-PstInfo C:\mail.pst

# The ten fullest folders.
Get-PstFolder C:\mail.pst | Sort-Object Items -Descending | Select-Object -First 10

# Big unread mail with attachments, as a spreadsheet.
Get-PstMail C:\mail.pst -Unread -WithAttachments -Since '2024-01-01' -LargerThanKB 256 |
    Export-Csv unread.csv -NoTypeInformation

# The address book, one card per person, photographs written out beside it.
Get-PstContact C:\mail.pst -PhotoDir C:\photos | Export-Csv contacts.csv -NoTypeInformation

# Audit a whole directory of archives; then merge them.
Get-ChildItem C:\Archives\*.pst | Test-PstHealth | Where-Object Corrupted
Get-ChildItem C:\Archives\*.pst | Merge-Pst -Destination C:\merged.pst -Layout Unified

# Rebuild a damaged file into a new copy (the original is never touched).
Repair-Pst C:\damaged.pst -Destination C:\repaired.pst

# Everything out as .msg, with the library's own progress bar.
Register-PstProgress
Export-PstItem C:\mail.pst -Destination C:\out -Format Msg
Unregister-PstProgress

Three things catch everybody out once.

• Load the build that matches your PowerShell. Windows PowerShell 5.1 runs on .NET Framework and must load lib\net48; PowerShell 7+ runs on modern .NET and must load lib\net8.0. Loading the wrong one fails with a “Bad IL format” that looks like a corrupt download and is not.
• PowerShell cannot skip .NET optional parameters. Optional arguments are a compiler feature; PowerShell binds positionally, so to reach the fifth parameter you must pass the first four. Pass $null where the .NET default is Nothing.
• Filter with the query, not with Where-Object. A Where-Object runs after each item has been read, so filtering a hundred-thousand-message archive that way opens a hundred thousand messages. The module's parameters map onto clsItemQuery, which is matched against the folder's contents table before an item is opened (see example 27).

# Loading, and calling the raw API without the module.
$tfm = if ($PSVersionTable.PSEdition -eq 'Core') { 'net8.0' } else { 'net48' }
Add-Type -Path "C:\BastionPstSdk\lib\$tfm\Bastion.Pst.dll"

$diag = New-Object Bastion.Pst.Diagnostics.clsDiagnostics
$diag.RecoverFromCorruption = $true

# Merge(sources, out, dedup, keepKinds, diag, overwrite, extraDrops, maxBytes, layout, rootName)
# - every argument supplied, because PowerShell binds positionally.
$sources = New-Object 'System.Collections.Generic.List[string]'
Get-ChildItem C:\Archives\*.pst | ForEach-Object { $sources.Add($_.FullName) }
$rep = [Bastion.Pst.Convert.clsStoreMerger]::Merge(
           $sources, 'C:\merged.pst',
           (New-Object Bastion.Pst.Convert.clsDedup), $null, $diag, $true, $null, 0,
           [Bastion.Pst.Convert.enmMergeLayout]::Unified, $null)

# The library never throws into your script - check the code.
if ($rep.ErrorCode -ne 0) { Write-Warning $rep.ErrorDescription }
else { "merged {0:N0} item(s), {1:N0} duplicate(s) removed" -f $rep.MessagesMerged, $rep.DuplicatesRemoved }

# Progress and errors from anywhere in the library, in one subscription.
$hub = [Bastion.Pst.clsPstEvents]::Default
Register-ObjectEvent -InputObject $hub -EventName PstRead -SourceIdentifier Bastion.Pst.Read -Action {
    $e = $Event.SourceEventArgs
    Write-Progress -Activity "Reading $($e.Folder)" -Status "$($e.Current) of $($e.Total)" -PercentComplete $e.Percent
} | Out-Null

Samples

The distribution ships ready-to-open sample projects under the samples/ folder. Each references the library from dist/lib and can be opened directly in Visual Studio. Build one, point it at a PST, and step through the API.

Every sample writes a log

Each sample writes a log file for every run, whether or not anything goes wrong, to %TEMP%\BastionPstSdk-Samples\. When something fails you get one plain sentence on screen and the offer to open the log; the exception type and stack go to the file, not the console. The WinForms sample also has a View Log File button.

The samples are written the way we suggest you write your own code against the library: every call is checked by ErrorCode rather than wrapped in a catch, because the library reports failure in its result and does not throw into your application. The SampleLog file in each sample is self-contained — copy it into your own project if it is useful.

One limit worth knowing: a managed try/catch only sees managed exceptions. If a process is killed by a native fault (heap corruption, an access violation, a stack overflow) no handler runs at all, because Windows terminates it without unwinding. The log still helps, because the last line written tells you how far it got — which is why every line is flushed as it happens rather than buffered.

Building a sample

• WinForms: open samples/WinForms/Sample.sln (VS 2012+) and press F5. It references dist/lib/net472/Bastion.Pst.dll. To target a different runtime, change the reference's HintPath (see the FAQ).
• Console samples: dotnet build (or open in VS 2022) — they reference dist/lib/net8.0/Bastion.Pst.dll. Run them with no arguments to see usage.
• PowerShell: nothing to build. Import-Module .\Bastion.Pst.psm1 loads the assembly that matches your PowerShell edition, then .\Examples.ps1 -Pst C:\mail.pst runs the worked tasks.

All samples follow the house rule demonstrated throughout this document: check each call's ErrorCode (0 = Ok) rather than catching exceptions — the library never throws into your application.

Frequently asked questions

Which build do I reference, and how do I switch the sample between them?

The distribution ships the library built for every current .NET. Reference the one that matches your project (the API is identical across all of them):

Eighteen builds, one per framework — there is no netstandard build. Pick the folder matching your target exactly. A WinForms app on net8.0-windows uses lib/net8.0: the library is portable and needs no Windows-specific build.

The shipped WinForms sample (samples/WinForms) references lib/net472 so it opens in Visual Studio 2012 — the oldest supported IDE. To point the same sample at a different build, change one line and (for modern targets) the target framework:

To use a different .NET Framework build — edit the <HintPath> in the .vbproj. The Include is the assembly name, Bastion.Pst, not the product name:

<Reference Include="Bastion.Pst">
  <HintPath>..\..\lib\net462\Bastion.Pst.dll</HintPath>
</Reference>

Off .NET Framework, add the companion package: System.Text.Encoding.CodePages (needed for correct ANSI→Unicode transcoding; it is built into .NET Framework, so you only need it on .NET Core / .NET 5+).

To use net8.0 — convert the project to the SDK style and set the framework and reference:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows</TargetFramework>
    <UseWindowsForms>true</UseWindowsForms>
  </PropertyGroup>
  <ItemGroup>
    <Reference Include="Bastion.Pst">
      <HintPath>..\..\lib\net8.0\Bastion.Pst.dll</HintPath>
    </Reference>
  </ItemGroup>
</Project>

The same pattern works for net48, net9.0 or net10.0 — point the <HintPath> at that folder (and, for the modern runtimes, set the matching <TargetFramework>, e.g. net10.0-windows). The library API is identical across every build, so the sample source does not change — only the reference and target framework do. (The shipped sample deliberately uses VB 11 syntax so it also compiles on the oldest toolchains; newer language features are fine on newer targets.)

A folder shows a message count, but opens empty — or a message opens blank

Almost always this is Outlook’s view/filter state, not missing data. The folder count comes from the PST’s stored count; Outlook then applies the active View (filter / group / sort) to decide what to show. A stray filter can hide a full folder.

• In Outlook: View › Change View › Reset View (or View Settings › Reset Current View).
• If a single message opens blank, toggle the Reading Pane or double-click to open it in its own window.

To prove the data is present independent of the view, call clsPstHealth.Check — it compares each folder’s stored count (and the folder-tree’s cached count) against the real messages. Zero mismatches means every message is there and the display is the only variable.

Why did some folders disappear or lose messages after a merge?

By design a merge removes provably-empty messages (no subject, no body in any form, no attachments — typically old spam remnants that open to nothing) and prunes empty folders. Every removal is itemised in the user log when CreateUserLog is on, with folder, source, sender and date. To keep everything verbatim, set dropBlankMessages:=False and pruneEmpty:=False (see Quick Start example 4).

How do I check whether an operation succeeded?

Every operation returns an object derived from clsOperationResult. Check ErrorCode (an enmErrorCode; 0 = Ok). For display use ErrorDescription (human text) or ToString() ("code: description"); Detail carries the full technical text for a support ticket, and Succeeded is a boolean shortcut. The library never throws into your application, so you never need a try/catch for control flow.

What do the error numbers mean?

The authoritative list is the enmErrorCode reference below.

Can I set the name Outlook shows for the merged store? Any character limits?

Yes — pass rootName. Any printable Unicode is accepted (CJK, emoji, right-to-left scripts, symbols such as \ / : * ? < > | & %). Control characters are stripped and whitespace trimmed. The length limit is 200 UTF-16 code units (a safety cap, not a PST limit): 200 CJK characters fit; emoji count as two units each. Defaults are “Stacked Merge” / “Unified Merge” for multi-source merges, and the original store name is preserved for a single-source rewrite.

My merge fails with FileLocked (3) but the file exists

The PST is almost certainly mounted in Outlook, which holds it open with no read sharing. Close Outlook (or remove the store from the profile) and retry. The library pre-checks this before writing and reports it as code 3 with a message that names the likely cause.

Can I use Bastion PST SDK from PowerShell?

Yes — it is an ordinary managed assembly, so Add-Type -Path Bastion.Pst.dll is all it takes; no COM, no Outlook, no MAPI. samples/PowerShell ships a module wrapping the whole library as cmdlet-shaped functions (Get-PstInfo, Get-PstMail, Merge-Pst, Test-PstHealth, Repair-Pst…) that emit objects, so results pipe into Export-Csv and the rest. Load lib\net48 from Windows PowerShell 5.1 and lib\net8.0 from PowerShell 7+; the wrong one fails with a misleading “Bad IL format”. And remember PowerShell cannot skip .NET optional arguments — pass the whole list, with $null for the defaults. See example 32.

Non-ASCII text looks wrong on .NET Core / .NET 5+

On .NET Core / .NET 5+ you must register the code-page provider once at startup so ANSI PSTs transcode correctly — add the System.Text.Encoding.CodePages package and call Encoding.RegisterProvider(CodePagesEncodingProvider.Instance). This is built into .NET Framework, so the net46–net481 consumers need nothing.

Will the merged/converted PST open in my version of Outlook?

Yes, for Outlook 2003 and every later version (2007, 2010, 2013, 2016, 2019, 2021, 2024 and Microsoft 365). Bastion PST SDK always writes the modern Unicode PST format. It will not open in Outlook 2002/XP or earlier, which only support the legacy ANSI PST format — there is no ANSI-write mode. Bastion PST SDK can, however, read those old ANSI files and convert them to Unicode. See the Outlook compatibility table in the Introduction.

Because of this, adding to or editing an existing ANSI store would rewrite it as Unicode and make it unopenable in Outlook 2002 and earlier. To protect users on legacy Outlook, Bastion PST SDK refuses that upgrade by default (the operation returns enmErrorCode.AnsiUpgradeRequired and writes nothing). Authorise it explicitly with clsDiagnostics.AllowAnsiToUnicodeUpgrade = True or by handling the AnsiUpgradeRequired event. Detect the format up front with the cheap, header-only clsPersonalStorage.IsAnsi / PeekFormat.

How do I prove a merged/repaired PST is complete and valid before shipping it to a user?

• Counts — clsPstHealth.Check compares stored vs actual message counts for every folder, at both the folder-property and folder-tree-cache levels.
• Structure — strict, Outlook-style validation flags anything Outlook would reject, without opening (and crashing) Outlook.
• User log — with CreateUserLog, every duplicate removed, blank dropped and folder pruned is itemised, so input-vs-output always reconciles.

How do I get messages out of a PST (export to individual files)?

Use clsStoreExporter.ExportToFolder(pstPath, outDir, enmExportFormat.Eml, diag) to write every message to its own .eml file under a folder tree that mirrors the store (attachments included, RFC 5322 / MIME). For a single message you hold, call clsMessageExporter.ExportEml(msg, path) or ExportMsg(msg, path). Six formats ship: EML (RFC 5322 / MIME), MSG (Outlook [MS-OXMSG]), ICS, VCF, MHTML and MBOX. If you are saving a user's selection rather than a whole store, use clsItemOps.SaveItems instead: it picks the right format per item kind (mail .msg, contact .vcf, appointment .ics, note .txt), is cancellable and reports progress. The command-line Export tool and the WinForms sample's “Export messages to EML/MSG files” batch operations both drive the store exporter.

How do I show a mailbox in my own application?

Bind to store.Views rather than writing the projection yourself: Mail(), Contacts(), Appointments(), Tasks(), Notes() and Rss() return flat, bindable rows, and MailIn(folder) is what a message list binds to when the user clicks a folder. Read one item with Views.Detail(folder, nid) when it is selected, and fetch attachment bytes with Views.AttachmentBytes only when the user saves or opens one. Editing verbs — save, copy, move, delete, import — are on clsItemOps. See examples 25–31.

Listing a big folder is slow, or the UI looks frozen

Two causes, both avoidable.

• You are opening every message to filter it. A LINQ Where over items can only run after each item has been read. Express the filter as a clsItemQuery instead: subject, sender, dates, size, unread and has-attachments are all answered by the folder's contents table, so a rejected row never causes a message to be opened. Keep only what the table cannot answer (body text, contact fields) in Where / BodyContains.
• You are not telling the user anything. Subscribe to clsPstEvents.Default.PstRead: it carries Current, Total and Percent, with the total known from the moment the contents table is open, so you can show a real percentage rather than an indeterminate bar. Events are raised on the working thread — marshal to the UI thread before touching controls.

Do the logs or support reports contain private data?

No. Diagnostic logs and support reports contain structural metadata only — never message content, subjects, addresses or attachments. They are safe for a user to email to your support (or to support@bastionsoftwaresolutions.com).

Visual Studio 2012 won’t load the sample (“these files could not be found”)

Delete any bin\, obj\, *.suo next to the project and re-open, and start Visual Studio from the Start menu (not from a Git Bash / MSYS shell, whose environment variables can redirect MSBuild imports). The shipped project has no such reference.

API reference

Public types and members only. Grouped by namespace below.

Class clsFileOpResult

Bastion.Pst

Result of a file-producing call (e.g. SaveSupportReport): the path plus the error contract.

Properties

Class clsGenericResult

Bastion.Pst

Result for operations with no extra payload (e.g. ConvertToUnicode).

Class clsOperationResult

Bastion.Pst

Base of every operation result: error code + descriptions + ToString "code: description".

Properties

Methods

Class clsPstCloseEventArgs

Bastion.Pst

Properties

Class clsPstErrorEventArgs

Bastion.Pst

Properties

Class clsPstEvents

Bastion.Pst

Subscribe to Default to observe PST activity across the whole library.

Properties

Class clsPstFolderSelectedEventArgs

Bastion.Pst

Properties

Class clsPstOpenEventArgs

Bastion.Pst

Properties

Class clsPstReadEventArgs

Bastion.Pst

Properties

Enum enmErrorCode

Bastion.Pst

Failure classes returned by every Bastion PST SDK operation. 0 = success.

Class clsAppointmentBuilder

Bastion.Pst.Authoring

Methods

Class clsAuthor

Bastion.Pst.Authoring

Creates and populates PST stores without Outlook: build typed items with the clsItemBuilder factories, then add them to a new or existing store. Every write is an atomic rewrite validated by reopening — the store is never mutated in place.

Methods

Class clsAuthoringSession

Bastion.Pst.Authoring

Accumulates rename / move / delete / remove-attachment edits and applies them in a single atomic, reopen-validated rewrite. Fluent: chain the queue methods, then Commit.

Properties

Methods

Class clsContactBuilder

Bastion.Pst.Authoring

Methods

Class clsDistListBuilder

Bastion.Pst.Authoring

Methods

Class clsItemBuilder

Bastion.Pst.Authoring

Entry point for building typed items: clsItemBuilder.Mail(), .Appointment(), .Contact(), .Task(), .Note().

Methods

Class clsItemBuilderBase

Bastion.Pst.Authoring

Shared surface: subject/body/attachments and the terminal Build.

Methods

Class clsJournalBuilder

Bastion.Pst.Authoring

Methods

Class clsMailBuilder

Bastion.Pst.Authoring

Methods

Class clsNoteBuilder

Bastion.Pst.Authoring

Methods

Class clsRssBuilder

Bastion.Pst.Authoring

An RSS feed item (IPM.Post.Rss).

Methods

Class clsTaskBuilder

Bastion.Pst.Authoring

Methods

Class clsDedup

Bastion.Pst.Convert

Properties

Class clsDestinationExistsException

Bastion.Pst.Convert

Thrown at the start of a write operation when the destination already exists and overwrite was not requested. The host application can catch this and prompt the user.

Properties

Class clsEditReport

Bastion.Pst.Convert

Result of a store edit: the standard error contract plus how many items/folders changed.

Properties

Class clsItemEdit

Bastion.Pst.Convert

Property changes to apply to matching items (any field left Nothing is unchanged).

Properties

Class clsMergePreflight

Bastion.Pst.Convert

Scans merge sources for corruption before the merge begins, and repairs the ones the caller agrees to repair. See Scan.

Methods

Class clsMergeReport

Bastion.Pst.Convert

Outcome of a merge. ErrorCode 0 = success; on failure ErrorDescription says why (ToString() renders "code: description").

Properties

Class clsPasswordChangeReport

Bastion.Pst.Convert

Outcome of clsStorePassword.SetPassword / clsStorePassword.RemovePassword: what was written, the structural validation of the output, and the password state read back from the output as evidence.

Properties

Class clsPasswordStatus

Bastion.Pst.Convert

Result of clsStorePassword.GetStatus: whether the file has an open password and the stored CRC value.

Properties

Class clsPreflightReport

Bastion.Pst.Convert

Outcome of a pre-merge scan (and repair, when one was run).

Properties

Methods

Class clsSourceHealth

Bastion.Pst.Convert

One source file's pre-merge verdict.

Properties

Class clsSplitPart

Bastion.Pst.Convert

Properties

Class clsSplitReport

Bastion.Pst.Convert

Outcome of a split. ErrorCode 0 = success.

Properties

Class clsStoreConverter

Bastion.Pst.Convert

Methods

Class clsStoreMerger

Bastion.Pst.Convert

Properties

Methods

Class clsStorePassword

Bastion.Pst.Convert

Read, set or remove the password of a PST file. A PST password is a stored CRC hash, not encryption — it controls Outlook's open prompt only; the data itself is never encrypted by it. SetPassword/RemovePassword write a new file (atomic, validated): pass the same path as source and output with overwrite:=True to change in place.

Methods

Class clsStoreSplitter

Bastion.Pst.Convert

Methods

Class clsVolumeInfo

Bastion.Pst.Convert

One output volume produced by a capped merge.

Properties

Class clsVolumeReport

Bastion.Pst.Convert

Outcome of a capped (volume-split) merge. ErrorCode 0 = success.

Properties

Enum enmMergeLayout

Bastion.Pst.Convert

How a merge lays out the sources in the output store.

Enum enmRepairChoice

Bastion.Pst.Convert

What the caller wants done about one corrupt source. The "…ToAll" answers apply to every remaining corrupt file so the user is not asked again; Cancel abandons the whole operation.

Class clsAnsiUpgradeEventArgs

Bastion.Pst.Diagnostics

Payload for clsDiagnostics.AnsiUpgradeRequired: the ANSI source about to be upgraded to Unicode. Set Proceed to make the hard choice — True upgrades to Unicode (unopenable in Outlook 2002 and earlier), False aborts with the source PST untouched.

Properties

Class clsCorruptionEventArgs

Bastion.Pst.Diagnostics

Payload for clsDiagnostics.SourceCorruptionDetected: which file, how bad, and (when auto-generated) where the developer support report was written.

Properties

Class clsDiagEventArgs

Bastion.Pst.Diagnostics

Payload for clsDiagnostics.Started / clsDiagnostics.Completed.

Properties

Class clsDiagnostics

Bastion.Pst.Diagnostics

Opt-in diagnostics surface for read/export operations: switches plus public events the host application can subscribe to. Pass an instance into Merge/Split/ConvertToUnicode.

Properties

Class clsErrorEventArgs

Bastion.Pst.Diagnostics

Payload for clsDiagnostics.ErrorOccurred: the failing phase, the error type and message, the item that failed, and whether the run recovered (skipped and continued).

Properties

Class clsModeEventArgs

Bastion.Pst.Diagnostics

Payload for clsDiagnostics.ModeChosen: which mode an input was processed in.

Properties

Class clsProgressEventArgs

Bastion.Pst.Diagnostics

Payload for clsDiagnostics.ReadProgress / clsDiagnostics.WriteProgress.

Properties

Enum enmDiagPhase

Bastion.Pst.Diagnostics

Which side of an operation an event refers to.

Enum enmProcessingMode

Bastion.Pst.Diagnostics

How a single input store is processed.

Class clsExportReport

Bastion.Pst.Export

Result of a bulk export (a whole PST to a folder of files): the standard error contract plus how many items were written and how many were skipped.

Properties

Class clsItemExporter

Bastion.Pst.Export

Exports non-mail items to their standard interchange formats: appointments to iCalendar (.ics, RFC 5545) and contacts to vCard (.vcf, RFC 6350). Clean-room from the public RFCs; never throws.

Methods

Class clsMessageExporter

Bastion.Pst.Export

Exports a single message to an interchange format. First format: EML (RFC 5322 / MIME). Clean-room from the public RFCs; never throws — returns a clsFileOpResult.

Methods

Class clsStoreBuilder

Bastion.Pst.Export

Creates new, empty Outlook data files. CreateEmpty writes a fresh, structurally-valid PST that mounts in Outlook — ready for a developer to merge other stores into. Never throws.

Methods

Class clsStoreExporter

Bastion.Pst.Export

Bulk export: walk a PST/OST and write every message to its own interchange file, mirroring the folder tree on disk. Never throws — returns a clsExportReport.

Methods

Enum enmExportFormat

Bastion.Pst.Export

Interchange formats Bastion PST SDK can export an item to. More are added per the export roadmap (MSG, MHTML, ICS, VCF, MBOX, OFT); EML is the first.

Class clsEmlReader

Bastion.Pst.Import

Parses an RFC 5322 / MIME message (.eml) into a clsImportedMessage. Clean-room from the public RFCs; validates the input and never throws.

Methods

Class clsIcsReader

Bastion.Pst.Import

Reads an iCalendar (.ics) file: yields each VEVENT as an appointment-kind clsImportedMessage. Malformed events are skipped; never throws on content.

Methods

Class clsImportedAddress

Bastion.Pst.Import

A name/email pair parsed from an address header.

Properties

Methods

Class clsImportedAppointment

Bastion.Pst.Import

Appointment fields parsed from an iCalendar VEVENT (RFC 5545). Attendees ride in the owning message's To list; SUMMARY/DESCRIPTION in Subject/BodyText.

Properties

Class clsImportedAttachment

Bastion.Pst.Import

An attachment parsed from an imported message.

Properties

Class clsImportedContact

Bastion.Pst.Import

Contact fields parsed from a vCard (RFC 6350 / 2425; 2.1–4.0 tolerated).

Properties

Class clsImportedDistList

Bastion.Pst.Import

Distribution-list fields ([MS-OXOABK]): the list name and its one-off members.

Properties

Class clsImportedDistListMember

Bastion.Pst.Import

A distribution-list member (a one-off recipient: display name + SMTP address).

Properties

Class clsImportedJournal

Bastion.Pst.Import

Journal-entry fields ([MS-OXOJRNL]).

Properties

Class clsImportedMessage

Bastion.Pst.Import

A message read from an interchange file (EML, MSG, MBOX). This is the neutral, fully-materialised model the import readers produce — inspect it, or hand it to an exporter to convert between formats.

Properties

Methods

Class clsImportedNote

Bastion.Pst.Import

Sticky-note fields ([MS-OXONOTE]). The note text is the message BodyText. Color: 0 blue,1 green,2 pink,3 yellow (default),4 white.

Properties

Class clsImportedOccurrenceOverride

Bastion.Pst.Import

An override of ONE occurrence of a recurring series ([MS-OXOCAL] ExceptionInfo / ExtendedException): the occurrence generated on OriginalDate is moved and/or re-titled. Members left unset inherit the series value.

Properties

Class clsImportedRecurrence

Bastion.Pst.Import

Recurrence pattern for an authored appointment ([MS-OXOCAL]). Supports daily (every N days), weekly (on selected weekdays) and monthly (on a day-of-month) series, ending after a count, on a date, or never.

Properties

Class clsImportedRss

Bastion.Pst.Import

RSS post fields ([MS-OXOPOST] / PSETID_PostRss). The article body is the message BodyText/BodyHtml; the channel is the feed the item arrived from.

Properties

Class clsImportedTask

Bastion.Pst.Import

Task fields ([MS-OXOTASK]). Status 0=not started,1=in progress,2=complete, 3=waiting,4=deferred; PercentComplete is 0..1.

Properties

Class clsImportReport

Bastion.Pst.Import

Result of an import run: the standard error contract plus counts. A per-file parse failure does not fail the run — it is recorded in Failures and the remaining files import normally; the run fails only when NO message could be imported.

Properties

Methods

Class clsImportResult

Bastion.Pst.Import

Result of importing a single message: the standard error contract plus the message.

Properties

Class clsMboxReader

Bastion.Pst.Import

Reads a Unix mbox file: yields each message as a clsImportedMessage by splitting on "From " separator lines and parsing each block as MIME. Never throws.

Methods

Class clsMsgReader

Bastion.Pst.Import

Parses an Outlook .msg file ([MS-OXMSG] over [MS-CFB]) into a clsImportedMessage. Clean-room; validates the container and never throws.

Methods

Class clsOlmReader

Bastion.Pst.Import

Reads Outlook-for-Mac .olm archives (mail items, with folder placement) into the neutral import model. Contacts/calendar/etc. live in separate consolidated XML files and are a later increment; this reads the per-message mail (message_NNNNN.xml).

Methods

Class clsStoreImporter

Bastion.Pst.Import

Imports EML / MSG / MBOX / ICS / VCF files into a folder of a PST. pstPath is the store to import into (its content is preserved); pass Nothing/empty to start from a new, empty store. The result is always written to outPath — the input store is never modified. Never throws.

Methods

Class clsTnefReader

Bastion.Pst.Import

Decodes TNEF (winmail.dat) streams into real attachments ([MS-OXTNEF]). Tolerant of damage; never throws into the caller.

Methods

Fields

Class clsTnefResult

Bastion.Pst.Import

Result of decoding a TNEF stream: the standard error contract, the recovered attachments and bodies, plus damage counters (bad checksums / truncated attributes).

Properties

Methods

Class clsVcfReader

Bastion.Pst.Import

Reads a vCard (.vcf) file: yields each card as a contact-kind clsImportedMessage. Malformed cards are skipped; never throws on content.

Methods

Enum enmImportedItemKind

Bastion.Pst.Import

What kind of Outlook item an imported file parsed into. Mail is the default; Appointment/Contact are produced by the ICS and VCF readers (Import Phase 4); Task/Note are produced by the authoring API (Phase 2.3) — no interchange reader emits them.

Enum enmRecurDays

Bastion.Pst.Import

Days-of-week bitmask for a weekly recurrence (matches [MS-OXOCAL] PatternTypeWeek).

Enum enmRecurFrequency

Bastion.Pst.Import

Recurrence frequency for an authored appointment.

Class clsAppointmentItem

Bastion.Pst.Messaging

Properties

Class clsAttachment

Bastion.Pst.Messaging

Properties

Methods

Class clsContactItem

Bastion.Pst.Messaging

Properties

Class clsDistListMember

Bastion.Pst.Messaging

One member of a distribution list: who they are, and where mail to them goes.

Properties

Methods

Class clsDistributionListItem

Bastion.Pst.Messaging

Properties

Class clsFolder

Bastion.Pst.Messaging

Properties

Methods

Class clsFolderClass

Bastion.Pst.Messaging

The standard PidTagContainerClass values — what tells a host application that a folder holds appointments rather than mail. Pass one of these to clsAuthor.SetFolderClass, or compare against clsFolder.ContainerClass.

Fields

Class clsItem

Bastion.Pst.Messaging

Properties

Methods

Class clsJournalItem

Bastion.Pst.Messaging

Properties

Class clsMailItem

Bastion.Pst.Messaging

Properties

Class clsMessage

Bastion.Pst.Messaging

Properties

Methods

Class clsMessageQuery

Bastion.Pst.Messaging

Methods

Class clsNoteItem

Bastion.Pst.Messaging

Properties

Class clsOpenResult

Bastion.Pst.Messaging

Result of clsPersonalStorage.TryOpen: ErrorCode 0 = opened, Store usable.

Properties

Class clsPersonalStorage

Bastion.Pst.Messaging

Properties

Methods

Class clsRecipient

Bastion.Pst.Messaging

Properties

Methods

Class clsSearch

Bastion.Pst.Messaging

Walks a folder subtree applying a clsMessageQuery.

Methods

Class clsSearchHit

Bastion.Pst.Messaging

A search result: the message and the folder path it was found in.

Properties

Class clsTaskItem

Bastion.Pst.Messaging

Properties

Enum enmAttachMethod

Bastion.Pst.Messaging

PidTagAttachMethod (0x3705) — how an attachment's data is stored.

Enum enmBusyStatus

Bastion.Pst.Messaging

PidLidBusyStatus (PSETID_Appointment 0x8205) — free/busy for an appointment.

Enum enmImportance

Bastion.Pst.Messaging

PidTagImportance (0x0017).

Enum enmItemKind

Bastion.Pst.Messaging

The kind of MAPI item, derived from PidTagMessageClass.

Enum enmRecipientType

Bastion.Pst.Messaging

PidTagRecipientType (0x0C15) — the role of a recipient on a message.

Enum enmSensitivity

Bastion.Pst.Messaging

PidTagSensitivity (0x0036).

Enum enmTaskStatus

Bastion.Pst.Messaging

PidLidTaskStatus (PSETID_Task 0x8101).

Interface itfAppointmentItem

Bastion.Pst.Messaging

Appointment / meeting — [MS-OXOCAL].

Properties

Interface itfContactItem

Bastion.Pst.Messaging

Contact — [MS-OXOCNTC].

Properties

Interface itfDistributionListItem

Bastion.Pst.Messaging

Distribution list — [MS-OXOABK] / [MS-OXODLGT].

Properties

Interface itfItem

Bastion.Pst.Messaging

Common projection shared by every typed item.

Properties

Interface itfJournalItem

Bastion.Pst.Messaging

Journal entry — [MS-OXOJRNL].

Properties

Interface itfMailItem

Bastion.Pst.Messaging

Mail message — [MS-OXOMSG].

Properties

Interface itfNoteItem

Bastion.Pst.Messaging

Sticky note — [MS-OXONOTE]. The note text is itfItem.Body.

Properties

Interface itfTaskItem

Bastion.Pst.Messaging

Task — [MS-OXOTASK].

Properties

Enum enmPstFormat

Bastion.Pst.Ndb

On-disk PST/OST format variant. The NDB layer is the only layer that distinguishes these; everything above it is format-agnostic ([MS-PST] 2.2.2.6).

Class clsPstRepair

Bastion.Pst.Repair

Methods

Class clsRepairReport

Bastion.Pst.Repair

Outcome of a clsPstRepair.Repair: the node count plus the strict validation of the source (before) and the rebuilt output (after).

Properties

Class clsHealthResult

Bastion.Pst.Validation

Outcome of clsPstHealth.Check. ErrorCode is 0 when the check itself ran — a corrupt-but-examinable file is ErrorCode 0 with IsCorrupted=True; ErrorCode is non-zero only when the file could not be examined at all.

Properties

Methods

Class clsPstHealth

Bastion.Pst.Validation

One-call health check for a PST/OST: full structural validation surfaced as a simple corrupted/clean verdict, plus support-report generation and a repair shortcut.

Methods

Class clsPstValidator

Bastion.Pst.Validation

Methods

Class clsValidationIssue

Bastion.Pst.Validation

One structural problem found by clsPstValidator.

Properties

Methods

Class clsValidationReport

Bastion.Pst.Validation

Result of validating a PST: the issues found and how much was checked.

Properties

Enum enmValidationSeverity

Bastion.Pst.Validation

Class clsAppointmentView

Bastion.Pst.Views

An appointment as a calendar shows it.

Properties

Class clsAttachmentView

Bastion.Pst.Views

One attachment, as a reading pane lists it.

Properties

Class clsContactMerger

Bastion.Pst.Views

Methods

Class clsContactView

Bastion.Pst.Views

A contact as a card view shows it.

Properties

Methods

Class clsItemDetail

Bastion.Pst.Views

The full detail of one item, for a reading pane or an item window.

Properties

Class clsItemOps

Bastion.Pst.Views

Methods