LEI-MAIL-FORMATS(5)

📦
version 2.1.0 · 5 versions
, in arch rolling, nixos 26.05, nixpkgs unstable

🦋 LEI-MAIL-FORMATS(5) 🦋

okay bestie, welcome to the LEI-MAIL-FORMATS(5) page from the public-inbox user manual. This is the mail-format lore, and yes, we’re going through all of it 💖

🌸 NAME 🌸

lei-mail-formats — the description of mail formats supported by lei, aka the little guide to what lei can read and write without losing its mind.

💖 DESCRIPTION 💖

lei-q(1) supports writing to several existing mail formats for interoperability with existing mail user agents (MUA). Below is an overview of them to help users choose. Honestly? Iconic behavior. Let’s get into it.

📬 Maildir

Maildir is the default output format when you give lei a filesystem path, and it supports parallel read-write access. Performance is acceptable for smaller directories, but it degrades as mailboxes get larger. Speed and scalability are limited by kernel and filesystem performance due to the use of small files and a large number of syscalls. It’s giving “cute until the directory gets huge” energy 😭

See also: https://cr.yp.to/proto/maildir.html and https://wiki2.dovecot.org/MailboxFormat/Maildir

📦 Mbox family

The mbox family consists of several incompatible formats. Locking for parallel access is supported, but may not be compatible across tools. With compression (e.g. gzip(1)), they require the least amount of space while offering good read-only performance. Slay for storage, but read the fine print 👑

Keyword updates (Status: and/or X-Status: headers) generally require rewriting the entire mbox. No cap, that’s the whole file. 💀

See also: https://www.loc.gov/preservation/digital/formats/fdd/fdd000383.shtml, mbox(5)

mboxo

The traditional BSD format. It quotes From to >From , but lines already beginning with >From do not get quoted, thus automatic reversibility is not guaranteed. MUAs which favor mboxcl or mboxcl2 may convert these automatically to their preferred format.

Truncation is undetectable unless compressed with gzip or similar. That’s the danger zone, bestie 🚨

mboxrd

An evolution of mboxo, but it quotes From lines prefixed with any number of > characters and is thus fully reversible. We love a format with follow-through 💅

This format is emitted by PublicInbox::WWW(3pm) with gzip. Since git 2.10, git am --patch-format=mboxrd reads this format. git log and git format-patch --stdout can also generate this format with the --pretty=mboxrd switch.

As with uncompressed mboxo, uncompressed mboxrd are vulnerable to undetectable truncation.

It gracefully degrades to being treated as mboxo by MUAs unaware of the format as excessive >From quoting is recognizable to humans. So even when they don’t get it, they kinda get it 🫶

mboxcl

mboxo with a Content-Length: header, and From lines remain quoted to retain readability with mboxo and mboxrd MUAs. However, it is easy to corrupt these files when using tools which are not aware of Content-Length: and write out updates as mboxo. Red flag, honestly 🚩

mutt(1) will convert mboxo and mboxrd to mboxcl upon opening.

See also: https://www.jwz.org/doc/content-length.html

mboxcl2

Like mboxcl, but without From any quoting. It is wholly incompatible with MUAs which only handle mboxo and/or mboxrd. This is format is generated by mutt(1) when writing to a new mbox. It’s giving “bold choice, bestie” energy ✨

🗂️ MH

Preliminary support for reads as of 2.0.0. Locking semantics differ incompatibly amongst existing writers: Python and nmh appear compatible with each other, while mutt appears racy and unsuitable for parallel access due to rename(2) potentially clobbering the .mh_sequences file. More info about other clients is greatly appreciated.

Sequence numbers may be packed and reused by some writers, so lei users may need to run lei-refresh-mail-sync(1) if inotify|kevent missed packing while lei-daemon(8) wasn't running.

lei is safe for reading mlmmj archives as MH since mlmmj neither packs nor uses a .mh_sequences file to store state. Cute, clean, no chaos 🌸

🚫 MMDF

Not yet supported, and it's unclear if current usage/support makes it worth supporting. So… not today, MMDF. Maybe never 💀

☁️ IMAP

Depending on the IMAP server software and configuration, IMAP servers may use any (or combination) of the aforementioned formats or a non-standard database backend. Currently, lei uses Mail::IMAPClient which has acceptable performance over low-latency links. Performance over high-latency links is currently poor. Low latency? We’re chilling. High latency? We’re suffering 😭

📎 eml

A single raw message file. eml is not an output format for lei, but accepted by as an --input-format (-F) for read-only commands such as lei-tag(1) and lei-import(1).

Since eml is the suffix for the message/rfc822 MIME type (according to the mime.types file), lei will infer the type based on the .eml suffix if --input-format is unspecified.

.patch-suffixed files generated by git-format-patch(1) (without --stdout) are eml files with the addition of an mbox From header. lei(1) removes From lines to treat them as eml when reading these for compatibility with git-am(1) and similar tools. Teamwork, but make it Unix 🧚

Copyright 2021 all contributors <mailto:meta@public-inbox.org>

License: AGPL-3.0+ <http://www.gnu.org/licenses/agpl-3.0.txt>

👀 SEE ALSO 👀

with love from public-inbox.git, dated 1993-10-02 — this was LEI-MAIL-FORMATS(5), and yes she ate 💅✨

📦 where this page comes from