Mail.dat.Abstractions 10.2.2

Open Mail.dat

Open Mail.dat is an open-source .NET library ecosystem for managing Mail.dat files — the standardized postal format used by the United States Postal Service for tracking mail processing, postage, components, and postal services. The project provides NuGet libraries, a command-line tool, and utilities to read, write, and process Mail.dat data, with SQLite as the backing store.

Table of Contents

• What Is Mail.dat?
• Projects & NuGet Packages
• Architecture Overview
• Repository Structure
• Getting Started
  • Installation via NuGet
  • Building from Source
• Usage
  • Command-Line Tool (MaildatCmd)
  • Programmatic Usage
    • Registering Services with Dependency Injection
    • Importing a Mail.dat File
    • Exporting a Mail.dat File
• Key Components
  • Mail.dat.Abstractions
  • Mail.dat.Models
  • Mail.dat.Io
  • Mail.dat.Hosting
  • Mail.dat.BulkProcessor
  • Mail.dat.Json.Specification
• USPS Spec Versions Supported
• Key Technologies
• License
• Attribution
• Author

What Is Mail.dat?

Mail.dat is a file format standard developed and maintained by the United States Postal Service (USPS). It is the industry standard for the electronic exchange of mailing job information between mail owners, mail preparers, and the USPS. A Mail.dat job consists of a collection of fixed-width record files (.hdr, .seg, .mpu, .pdr, .pbc, etc.) that together describe every aspect of a mailing, including:

• Postage and rate information
• Container and tray planning
• Piece-level barcode tracking
• Postal routing and sorting details
• Certificate of mailing data

Open Mail.dat provides a complete .NET solution for reading, writing, importing, and exporting these files.

Projects & NuGet Packages

The solution consists of nine NuGet library packages and one command-line application, all targeting .NET 10 at version 10.2.1.

All packages are published with symbol packages (.snupkg) for source-level debugging.

Architecture Overview

The project follows a layered, modular, async-first architecture:

┌──────────────────────────────────────────────────┐
│  MaildatCmd  (CLI Entry Point)                    │
├──────────────────────────────────────────────────┤
│  ImportCommand / ExportCommand / BuildCommand     │  ← Command handlers (Spectre.Console progress UI)
├──────────────────────────────────────────────────┤
│  Mail.dat.Io                                      │  ← Core I/O (MaildatImport, MaildatExport)
├──────────────────────────────────────────────────┤
│  Mail.dat.Models                                  │  ← EF Core entities + 155 USPS lookup value classes
│  Mail.dat.BulkProcessor                           │  ← High-performance bulk insert/update
├──────────────────────────────────────────────────┤
│  Mail.dat.Json.Specification                      │  ← USPS spec schemas (versions 23-1 → 26-1)
├──────────────────────────────────────────────────┤
│  Mail.dat.Abstractions                            │  ← Interfaces: IMaildatFile, IImportOptions, …
│  Mail.dat.Hosting                                 │  ← DI registration helpers
└──────────────────────────────────────────────────┘

Design Patterns:

Repository Structure

Open-Mail.dat/
├── Src/
│   ├── Mail.dat.Abstractions/         # Core interfaces & contracts
│   ├── Mail.dat.Models/               # EF Core entity models + lookup values
│   ├── Mail.dat.Io/                   # Import/export implementation
│   ├── Mail.dat.Json.Specification/   # JSON schema models (USPS spec versions)
│   ├── Mail.dat.ImportCommand/        # CLI import command handler
│   ├── Mail.dat.ExportCommand/        # CLI export command handler
│   ├── Mail.dat.BuildCommand/         # CLI code generation command
│   ├── Mail.dat.BulkProcessor/        # High-speed bulk EF Core operations
│   ├── Mail.dat.Hosting/              # DI and hosting configuration
│   └── MaildatCmd/                    # Main CLI application entry point
├── ARCHITECTURE.md                    # Detailed architecture documentation
├── LICENSE.md                         # LGPL-3.0 license
├── LICENSE-ADDENDUM.md                # Attribution and modification addendum
└── README.md

Three Visual Studio solution files are included:

• Open Mail.dat Solution.sln — Standard solution
• Open Mail.dat Solution ALL.sln — All projects
• Open Mail.dat Solution - BUILD ONLY.sln — Code generation focused

Getting Started

Installation via NuGet

For library integration in your own .NET project, add the packages that fit your needs:

# Core I/O (import and export Mail.dat files)
dotnet add package "Open Mail.dat IO"

# Entity models for accessing imported data
dotnet add package "Open Mail.dat Models"

# Hosting/DI helpers for ASP.NET Core or Worker Service applications
dotnet add package "Open Mail.dat Hosting"

# Bulk operations for large datasets
dotnet add package "Open Mail.dat Bulk Processor"

All packages target net10.0 and require .NET 10 or later.

Building from Source

1. Clone the repository:

   git clone https://github.com/porrey/Open-Mail.dat.git
   cd Open-Mail.dat
   

2. Open one of the solution files in Visual Studio 2022 (or later), or build from the command line:

   dotnet build "Open Mail.dat Solution.sln"
   

3. NuGet packages are automatically generated on build (GeneratePackageOnBuild=True). Symbol packages (.snupkg) are also produced.

4. To publish packages manually, run Src/NuGet.Publish.cmd from a Visual Studio Developer Command Prompt. The script prompts for your NuGet API key and publishes all .nupkg and .snupkg files to nuget.org.

Usage

Command-Line Tool (MaildatCmd)

MaildatCmd is a standalone .NET console application that exposes three commands.

import — Import a Mail.dat file into a SQLite database

MaildatCmd import --source-file-path <path-to-maildat-or-zip> --target-file-path <path-to-sqlite-db>

Example:

MaildatCmd import -s "C:\mail\job12345.zip" -t "C:\databases\job12345.db"

A rich progress display (progress bar, percentage, elapsed time, line counter) is shown during import. Any validation errors are grouped by file and reported at the end.

export — Export a Mail.dat file from a SQLite database

MaildatCmd export --source-file-path <path-to-sqlite-db> --target-file-path <path-to-maildat-or-zip>

If the target file has a .zip extension, the output is automatically compressed.

Example:

MaildatCmd export -s "C:\databases\job12345.db" -t "C:\mail\job12345-out.zip"

build — Generate model code from a USPS JSON specification

MaildatCmd build --specification-files <comma-delimited-paths> --models-directory <path> --hosting-directory <path>

This command reads the USPS Mail.dat JSON specifications and auto-generates all EF Core entity classes, interface definitions, repository classes, the MaildatContext DbContext, and DI registration code.

Programmatic Usage

Registering Services with Dependency Injection

Use the AddOpenMaildat<TDatabaseContext>() extension method in your service configuration:

using Mail.dat.Hosting;
using Mail.dat.Models;

// In your IServiceCollection setup (e.g., in a Worker Service or ASP.NET Core app):
services.AddOpenMaildat<MaildatContext>();

This single call registers:

• All 29 entity repositories and factories (IRepository<IHdr>, IRepository<ISeg>, etc.)
• IMaildatImport<TDatabaseContext> → MaildatImport<TDatabaseContext>
• IMaildatExport → MaildatExport
• IBulkProcessorFactory → BulkProcessorFactory

Importing a Mail.dat File

using Mail.dat.Io;
using Mail.dat.Models;

// Create the import options
ImportOptions options = new()
{
    SourceFile          = MaildatFile.Create("/path/to/job.zip"),
    TargetFile          = MaildatFile.Create("/path/to/output.db"),
    TemporaryDirectory  = Path.GetTempPath(),
    CancellationToken   = CancellationToken.None
};

// Create an import instance (with optional progress callback)
IMaildatImport<MaildatContext> importer = MaildatImport<MaildatContext>.Create(
    new DefaultDbContextFactory(),
    async (message) => Console.WriteLine(message.StatusMessage)
);

// Run the import
(bool success, MaildatContext context) = await importer.ImportAsync(options);

Exporting a Mail.dat File

using Mail.dat.Io;

// Create the export options
ExportOptions options = new()
{
    SourceFile      = MaildatFile.Create("/path/to/output.db"),
    TargetFile      = MaildatFile.Create("/path/to/export.zip"),
    TaregtVersion   = "25-1",  // Note: property name has a typo in the interface
    Encoding        = System.Text.Encoding.UTF8,
    LineTerminator  = Environment.NewLine
};

// Create an export instance (with optional progress callback)
IMaildatExport exporter = MaildatExport.Create(
    async (message) => Console.WriteLine(message.StatusMessage)
);

// Run the export
bool success = await exporter.ExportAsync(options.TargetFile, options);

Key Components

Mail.dat.Abstractions

Defines the core interfaces and shared types used across all libraries.

Key Interfaces:

Attributes:

Mail.dat.Models

Contains the 29 EF Core entity classes (auto-generated from USPS JSON specifications) and over 155 USPS lookup value classes.

Entity Classes:

All entities inherit from MaildatEntity and are stored in a [Maildat] schema within the SQLite database.

Mail.dat.Io

Provides the core import and export engine.

MaildatImport<TDatabaseContext>
Reads Mail.dat files (or ZIP archives) and imports all records into a SQLite database in parallel, using transactions for consistency and EFCore.BulkExtensions for throughput.

MaildatExport
Reads records from a SQLite database and writes them as fixed-width Mail.dat files, optionally compressing the output into a ZIP archive.

IMaildatFile / MaildatFile
Represents a Mail.dat file path (ZIP or unzipped). Provides UnzipAsync, ZipAsync, and GetFile(extension) helpers.

Key interfaces in this project:

Mail.dat.Hosting

Provides the AddOpenMaildat<TDatabaseContext>() extension method for IServiceCollection. This is a convenience wrapper that chains three registration calls:

• AddOpenMaildatModels() — registers all entity repositories and factories
• AddOpenMaildatIo<TDatabaseContext>() — registers import/export services
• AddOpenMaildatBulkProcessor<TDatabaseContext>() — registers the bulk processor factory

Mail.dat.BulkProcessor

Wraps EFCore.BulkExtensions.Sqlite to provide high-performance bulk insert and update operations. Used internally by MaildatImport when importing large Mail.dat files to dramatically reduce database write time compared to standard EF Core SaveChanges.

Mail.dat.Json.Specification

Contains the official USPS Mail.dat JSON specification files and the C# models for deserializing them. These specifications define every file type, record layout, and field definition for each supported version. The build command uses these specifications to auto-generate all entity models and repository code.

USPS Spec Versions Supported

Versions are detected automatically during import from the Mail.dat header record. Entity models and field attributes are version-aware — a single entity class can support multiple spec versions with different field layouts via [MaildatVersions] attributes.

Key Technologies

Logging

MaildatCmd uses Serilog with a rolling-file sink. Logs are written to:

%TEMP%/MaildatCmd/Logs/MaildatCmd-Log.txt

Configuration is in MaildatCmd/appsettings.json. Separate appsettings.Development.json and appsettings.Production.json files allow environment-specific overrides.

License

This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0), with an additional Attribution and Public Use Addendum.

By using this library you agree to both the LGPL-3.0 terms and the addendum, which requires:

1. Public Attribution — Applications using this library in any public or commercial product must include a visible acknowledgment:

   "This software uses Open Mail.dat, available under the LGPL-3.0 license with additional terms. See https://github.com/Open-Mail-dat for details."

2. Modification Disclosure — Any modifications to the library itself must be published in a public code repository and include a prominent notice of the change date and author.

See LICENSE.md and LICENSE-ADDENDUM.md for the full license text.

Attribution

This software uses Open Mail.dat, available under the LGPL-3.0 license with additional terms.
See LICENSE-ADDENDUM.md for details.

Author

Daniel M Porrey
Copyright © 2025–2026 Daniel Porrey, Open Mail.dat. All rights reserved.
GitHub: https://github.com/porrey