The shared read view and Mail.*

Every 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, parses only what the caller asks for, and never throws on malformed content. Code that only needs to read mail depends on the view; code that needs every byte and every defect goes to the model (for MIME, MimeMailItem.Entity).

The view

Offsets in a mime defect are relative to the item's own first byte (what the MIME reader sees), not to the container file; add Provenance.Offset for a file position (for an mboxrd store whose body lines were unquoted, positions after the first unquoted line shift by the removed > bytes).

Bodies and attachments for MIME

• Text/HTML: multipart/alternative: the last matching child (RFC 2046 5.1.4); multipart/related and multipart/signed: the first child only; any other multipart: the first matching child in order; a message/* part is not searched. A text part with Content-Disposition: attachment is never a body. Text decoding: the stated charset; if absent or unknown, UTF-8 when valid, else Windows-1252.
• Attachments: every leaf part and message/* part that is not the chosen text/HTML body, in document order, except a text part directly in a multipart/alternative that is not marked attachment (that is another rendering of the body). A message that is one leaf part is its own attachment. IsInline is true for a part that is not marked attachment and has a Content-ID. The resolutions are V1–V8 in ambiguities.md.
• An embedded message/rfc822 is an IMailItem with the same view, parsed from the same bytes.
• A TNEF part (application/ms-tnef, winmail.dat, found by content) that qualifies under MS-OXCMAIL 2.2.3.8 (conversion.md, TNEF parts) is shown the way Outlook shows it, not as a file (V9): the part is not listed as an attachment; the attachments the TNEF holds (embedded messages included, each an item with its own view) take its place in document order; RtfBody is the TNEF's compressed RTF decompressed; TextBody and HtmlBody are the TNEF's (an HTML property, or the HTML or text de-encapsulated from its RTF) when the MIME side has none of that kind. The MIME parts always win. A part that does not qualify (damaged stream, correlation key mismatch) stays one ordinary attachment. MimeMailItem.TnefParts lists the unpacked parts (the raw bytes are part.GetDecodedContent(); the tree is untouched) and TnefMessages their MAPI messages. A stream ending in CR LF is unpacked and the item reports the defect AmbiguousTnefTrailingCrLf (family tnef). Header fields are never taken from a TNEF: the view of a MIME item reads its headers only.

MAPI items (MSG, PST, OST)

MapiMailItem projects a MapiMessage (docs/mapi.md) onto the same view. Nothing is looked up outside the item.

PST/OST enumeration through Mail.Open yields ordinary messages of non-search folders in folder order (docs/pst-messaging.md).

Opening things: Mail.*

Each Mail.* method is one call into the layer that does the work; the options are those layers' own option types.

MailContainer lifetime: the container owns the file it opened from a path (a stream or source passed in stays the caller's). Items read their bytes when first used, so they are valid until the container is disposed, after which reading an unread item throws ObjectDisposedException. Enumeration holds one message's state at a time. A source without synchronous reads is handled by the async enumeration (mbox messages are loaded before the item is yielded).

Sniffing

MailFormatSniffer.Sniff(source) and .SniffDirectory(path) decide by content; the file name is never read.

A message with no header block (starts with a blank line or with text that is not a header field) cannot be told from any text file and is Unknown; Mail.Parse still reads it. A recognised format whose reader is not in the library yet (Ics, VCard, CompoundFile) makes Open throw UnsupportedMailFormatException with its Format; Unknown throws the same exception with Format == Unknown. DBX files and DBX store folders are recognised and opened (Dbx, DbxStore, since 0.2.0-preview.2); OLM is not yet recognised.

The CLI: onemail inspect

onemail inspect [--json] [--sizes] [--defects] <file-or-directory>... prints the format and every item. A directory that is not a store is walked and each file inspected on its own (a tree of loose messages); a file that is not readable is reported, not fatal. Text: one line per item (date, first sender, subject, attachment names, defect count). --json: one object per line, a container record then an item record per message with the whole view and provenance. --sizes decodes attachments to measure them. It streams: one item is held at a time.

How it is checked

• tools/oracles/viewcheck.sh: runs onemail inspect --json, cuts each item's bytes out of its container, runs the OneMail oracle driver (built on the tree API, not the view) and compares subject, addresses, date, Message-ID/In-Reply-To/References and attachment lists per item; then compares attachment names and counts with Python email, grouping differences by signature, each tied to a V entry or an N entry.
• Allocation: enumerating an mbox of small messages creates one ~150-byte item per message and reads nothing; reading subject, from and date of each costs about 5.4 KB per message, almost all of it the MIME tree (~2.7 KB) and the address and date parsers, not the view.