Crate mailbox_formats 

Read and write classic local-mail storage formats.

Covered:

• mbox (RFC 4155) — all four variants: Mboxo, Mboxrd, Mboxcl, Mboxcl2. Streaming reader and writer.
• Maildir (DJB spec) — atomic delivery, flag parsing, basic cur//new//tmp/ iteration.
• Locking for mbox concurrent access: LockStrategy::{Dotlock, Flock, Fcntl, FcntlThenDotlock} plus the explicit None. Unix first-class; Windows degradation is documented.

Quickstart

use std::io::Cursor;
use mailbox_formats::{MboxReader, MboxVariant, RawMessage};

let bytes = b"From alice@example.com Tue Mar 17 09:30:00 2026\r\n\
              From: Alice <alice@example.com>\r\n\
              Subject: Hello\r\n\r\n\
              Hi there.\r\n\r\n";
let mut reader = MboxReader::new(Cursor::new(&bytes[..]), MboxVariant::Mboxrd);
let msg: RawMessage = reader.next().expect("one message")?;
assert_eq!(msg.header("Subject"), Some(&b"Hello"[..]));

Design choices

• Byte-preserving: RawMessage holds headers as Vec<(String, Vec<u8>)> and the body as Vec<u8>. No MIME decoding, no charset assumptions. Pair with mail-parser if you need decoded headers.
• Streaming: the mbox reader is BufRead-based with bounded memory; a 10GB mbox streams without loading into memory.
• Honest variants: MboxVariant::Auto sniffs the first few messages for Content-Length: headers and >From escaping. If it can’t tell, it returns Error::UndetectedMboxVariant rather than guessing.
• Locking is explicit: callers pick a LockStrategy; the default is LockStrategy::None (caller responsibility).

Out of scope (v0.1.0)

• MH format: rare in modern environments; add only if users file an issue.
• Maildir++ subfolders (.foo.bar/): basic Maildir only.
• MIME parsing or header decoding: keep mailbox-formats focused on file-format semantics.

Structs

Flags

IMAP-style flags shared across mbox (when reading Status: / X-Status: headers) and Maildir (filename suffix encoding).

Lock

RAII guard that releases the lock on drop.

Maildir

Handle to a Maildir directory.

MaildirEntry

One Maildir entry. Path is the on-disk location; unique_id is the portion before the separator; flags is parsed from the suffix.

MboxReader

Streaming reader. Yields one RawMessage per call to next.

MboxWriter

Writes RawMessage values to an underlying Write in the requested mbox variant.

RawMessage

One message as it lives in an mbox file or a Maildir folder.

Enums

Error

Errors returned by the mailbox-formats crate.

LockStrategy

Locking policy. Default is LockStrategy::None — the caller takes responsibility.

MboxVariant

Which mbox dialect the reader/writer should use.

Type Aliases

Result

Crate-local result alias.