onemailDocs
onemail docs
Everything about OneMail: getting started, the one-line reading path, MIME and mailboxes, the Outlook formats, conversion, calendars and contacts, and how each is checked. OneMail is a preview: 0.2.0-preview.2.
Start
Getting startedInstall OneMail 0.2.0-preview.2 for .NET 10, parse an email, and open an mbox, an Outlook MSG file and a PST store with the same call. Pure C#, with no Outlook, COM or native library.OverviewAn email library for .NET with no dependency beyond the .NET base class library and its sibling libraries (OneArchive, OneHtml, OneRender). It reads and writes the formats mail lives in, keeps what it reads lossless, and says what it repaired instead of throwing.Mail.Open and the read viewEvery item OneMail reads (a MIME message, an MSG, a PST/OST message; calendar items and others as their readers arrive) implements one read-only interface, IMailItem, in the root namespace RecursiveAI.OneMail. It is a projection: it copies nothing from the model underneath…
Internet mail
Reading and writing MIMEThis is the behaviour of MimeReader (RecursiveAI.OneMail.Mime.Reading) and the entity tree built on it (RecursiveAI.OneMail.Mime). It is written to be implemented the same way in another language.Charsets and encoded wordsNormative behaviour of the text layer (RecursiveAI.OneMail.Text). It sits under the MIME code and knows nothing about messages: it turns bytes into text and text into bytes, and says what it had to repair.Reports and MHTMLTyped views over the MIME entity tree (RecursiveAI.OneMail.Mime.Reports, .Mhtml, .Authentication). The tree stays the lossless store: a view reads it, never changes it, so an untouched message still writes back byte for byte. Every repair is a typed defect with the byte…Mailboxes (mbox, Maildir, EMLX, DBX)How OneMail enumerates and writes mbox files, Maildir folders and Apple Mail (EMLX) stores, and reads Outlook Express (DBX) stores. The code is in RecursiveAI.OneMail.Stores (shared types, file-system abstraction, content sniffing) and its .Mbox, .Maildir, .Emlx and .Dbx…
Outlook formats
MSG and OFTRecursiveAI.OneMail.Msg reads Outlook message files (.msg) and templates (.oft) into the MAPI model (docs/mapi.md). The container is MS-CFB, read through OneArchive's compound file reader; the content is MS-OXMSG. An OFT is an MSG whose message class is a template; the same…PST and OST messagesWhat RecursiveAI.OneMail.Pst.Messaging reads, how it treats damage, and what was checked. The structures are MS-PST 2.4 (store, folders, messages, attachments, recipients, named properties) on the lists-tables-properties layer (docs/pst-ltp.md). The same code reads ANSI…PST tables and propertiesWhat RecursiveAI.OneMail.Pst.Ltp reads, how it treats damage, and what was settled by looking at real files. The structures are MS-PST 2.3 (heap-on-node, BTree-on-Heap, property context, table context). The layer sits directly on the node database layer (docs/pst-ndb.md) and…PST node databaseWhat RecursiveAI.OneMail.Pst.Ndb reads, how it treats damage, and what was settled by looking at real files. The structures are MS-PST 2.2.2 (the NDB layer); where MS-PST is silent (4 KiB pages) the facts below come from a real Outlook 2013 OST and from the libyal PFF format…MAPI propertiesWhat RecursiveAI.OneMail.Mapi is: the in-memory form of an Outlook item (message, recipient, attachment), independent of the file it came from. MSG files fill it today (docs/msg.md); the PST/OST messaging layer fills the same types (docs/pst-messaging.md). Types and tags are…TNEF (winmail.dat)Normative notes for RecursiveAI.OneMail.Tnef, written from MS-OXTNEF (v20250520) and checked against public files. Layers:Compressed RTFRecursiveAI.OneMail.Rtf reads and writes what Outlook stores in PidTagRtfCompressed and recovers the HTML or plain text that Outlook wraps inside an RTF body. The namespace uses only the .NET base class library: it does not reference any other part of OneMail, so it can be…MAPI and MIME conversionA conversion turns an item of one model into an item of another and says what it could not carry. Nothing converts behind the caller's back: a conversion is a call, and its result has two parts.
Calendars and contacts
ICS and vCardNormative notes for RecursiveAI.OneMail.Calendar (BCL only). Behaviour on ambiguous input is in ambiguities.md, calendar section.Recurrence and time zonesNormative notes for RecursiveAI.OneMail.Calendar.Recurrence and .TimeZones. The entry points are CalendarRecurrence.Expand(calendar, window, options, report) (a VCALENDAR with its events, VTIMEZONEs and overrides) and RecurrenceSet (one master component plus its overrides).…jCal, jCard, xCal, xCardNormative notes for RecursiveAI.OneMail.Calendar.Forms (BCL only). The standards are RFC 7265 (jCal), RFC 7095 (jCard), RFC 6321 (xCal) and RFC 6351 (xCard). Choices the standards leave open are the J rows in ambiguities.md, calendar section.ContactsThree pieces, each usable alone:
How it is checked
Fidelity and known gapsWhat OneMail reads and writes today, how each format is checked, and the gaps we know about. This table is updated with every preview; a gap is listed here, never hidden.Benchmarksbench/OneMail.Benchmarks compares OneMail with MimeKit 4.18.2 (a released NuGet package, referenced only from bench/) on the same bytes, in memory, with BenchmarkDotNet 0.15.8. bench/run-mime-rows.sh OUTDIR builds, runs every row (3 launches, 3 warm-up and 10 measured…AmbiguitiesReal mail is full of messages that the RFCs call invalid or leave open, and the established libraries each pick their own answer. OneMail picks one documented answer per case, reports it as a typed defect, and keeps the original bytes so nothing is lost whichever answer a…