MBOX vs. Maildir: How Email Gets Stored as Files

When an email program saves messages to disk, it can put all the messages in a folder into one file or save each message in a separate file. MBOX uses one file per folder; Maildir uses one file per message. This choice affects how the program finds messages and handles changes made at the same time.

MBOX is easy to copy as one file, but programs that change it need compatible locking methods to prevent simultaneous edits. They also need to agree on where each message begins and ends. Maildir stores each message separately, which keeps many changes to one message from affecting others. Mail programs still need to coordinate some changes to a folder. For a readable personal archive from a hosted mailbox, mailmd is a practical option: it copies messages into individual Markdown files on your computer, rather than creating an MBOX or Maildir archive.

How MBOX stores messages #

An MBOX mailbox is a single file containing zero or more email messages. Mail software treats the file as a folder and uses a special separator line beginning with From , often called the “From_” line, to find each message boundary. That line records an envelope sender and delivery time; it is separate from the message’s ordinary From: header. The qmail MBOX description and Oracle’s mbox(5) documentation describe this layout.

Because a message body might itself contain a line beginning with From , MBOX writers modify such lines so readers do not mistake them for message boundaries. The exact rules vary. In the mboxrd variant, for example, writers add a > to lines that begin with one or more > characters followed by From . MBOX has no single standard that all implementations follow, so a reader written for one variant can misread a file written in another. The format overview describes these variations.

The single-file layout makes copying a mailbox simple, but it also means multiple programs may read or update the same file. They need to use compatible locking methods, which prevent programs from changing the file at the same time. If one program writes while another reads or edits the file without coordinating, the second program can see damaged or missing message data. Oracle’s documentation warns that inconsistent locking can lose email; Dovecot also explains the locking methods its MBOX implementation uses in its MBOX locking documentation.

How Maildir stores messages #

Maildir gives each message its own file inside a directory. A typical folder has three subdirectories: tmp for messages being delivered, new for delivered messages that have not yet been seen by a mail application, and cur for messages that have been seen. The original Maildir description explains how delivery writes a message to tmp before moving it to new.

Separate files let software add or remove one message without rewriting the contents of a whole mailbox file. Maildir also records some message state in filenames. When software moves a message from new to cur, it can add flags, short markers in the filename, to show whether the message was read or flagged. Dovecot’s Maildir documentation describes the filename conventions and additional Dovecot-specific index files.

Because Maildir stores messages in separate files, programs need less coordination to change a mailbox. Some Maildir implementations still use locks. Dovecot locks Maildir folders during some changes and warns that different mail programs may not honor the same locking method. If multiple programs modify the same Maildir, use software designed to work together and check its documentation.

Choosing between MBOX and Maildir #

Choose MBOX when a single file per folder suits your backup or transfer needs and the programs that access it use compatible locking and MBOX conventions. Before moving an MBOX file between programs, check which variant the writer and reader expect. A boundary-quoting mismatch can make a reader split messages incorrectly.

Choose Maildir when you want separate files for individual messages and your mail software supports the format. Each message can be handled on its own, but the directory layout and any program-specific index files matter. Dovecot, for example, notes that its Maildir support has limits around stored keywords and uses an additional control file to map IMAP message identifiers to filenames; these identifiers are numbers IMAP uses to refer to messages.

Neither layout describes how every hosted mail service stores its server-side mail. Gmail, Outlook, and other providers expose mail through their own services; the file format applies when software saves messages to local or server storage. If the goal is a personal archive that is easy to inspect and search, Markdown files are another option.

Create a local email archive with mailmd #

mailmd is a free, open-source command-line tool that copies mail into a folder of Markdown files on your computer, with one file per message. It does not produce MBOX or Maildir. Instead, it creates a readable archive with message headers in frontmatter, attachments saved beside messages, directories for folders and years, and an index.jsonl file that scripts can use to list messages.

To install it on Linux, macOS, or Windows in Git Bash, run:

curl -fsSL https://raw.githubusercontent.com/vincentsch/mailmd/main/install.sh | sh

Connect the mailbox using the command that matches its access method, then sync the messages:

# IMAP mailbox, including Gmail with an app password
mailmd connect imap --email you@example.com

# Gmail API; requires your OAuth app's client-secret file
mailmd connect gmail --client-secret client_secret.json

# Outlook.com or Microsoft 365; requires a Microsoft Entra app
mailmd connect outlook --client-id <id>

mailmd sync

Many IMAP providers require an app password; mailmd indicates when one is needed. Gmail API and Microsoft Graph logins require an OAuth app created in Google Cloud or Microsoft Entra. The archive goes under ~/mail/<account>. For Gmail over IMAP, mailmd syncs All Mail so archived messages are included; spam and trash are excluded unless requested.

mailmd opens mailbox folders read-only and requests read access. It does not mark messages as read, move or delete them, or send mail. Later syncs add new mail and update read and starred marks; mail deleted from the server remains in the archive, marked as deleted on the server. If a sync stops, saved files remain and the next run continues. Use --folder, --exclude, or --since to choose which messages to copy, and --keep-raw to save the original .eml file beside each Markdown message.

You can search the files in an editor or note-taking app, use rg or grep for text searches, and filter index.jsonl with jq. A scheduled mailmd sync --quiet command can keep the archive current. mailmd does not delete mail from the hosted mailbox to free storage, import archived messages back into a mailbox, or convert them to PST or PDF. Its login data is stored outside the archive, is not encrypted, and is readable only by your user.