# Mail

How the Mail export works, from connecting to fixing problems.

## Connect

Press "Connect" beside Mail on Exporter's home (it is under "More Apps" until you connect it), then "Open Mail Folder". The panel opens on `~/Library/Mail`: select that folder itself. Then choose where the files go and press "Use This Folder".

Exporter reads the mail Mail keeps on your Mac through the folder you granted. It asks for no mail permission, no account and no Full Disk Access.

## Choose emails

The pick page has two tabs, and an email syncs when both tick it.

- Kinds: Mail's own tabs. Primary, Transactions, Updates, Promotions, and Not Sorted by Mail for the rest. Updates and Promotions start unticked.
- Accounts: each account by its address, with its mailboxes inside. Drafts and Trash start unticked.

Deleted mail, Spam and Junk never sync, whatever is ticked. The count above the list is what the two tabs leave together.

## Where the files go

One Markdown file per email, named by its day, its subject and a number: `2026-09-28 Your order has shipped 491560.md`. A folder right in your home folder, like `~/Documents`, gets a `mail-export` folder inside it; a deeper one is used as it is.

Organize, in "Options…" on the card, sets the folders:

- By Date: `2026/09/`, a folder per year and month
- By Account: a folder per account, then the year
- By Kind: `primary/`, `transactions/`, `updates/`, `promotions/`, `unsorted/`, then the year

Changing Organize moves every file at the next sync. Nothing is left at the old place.

## The file

The front matter carries `from`, `to`, the `mailbox`, `read`, `flagged` when it is, the `account` and the `kind`, with `source_url` opening the email in Mail. Then the subject as the title and the body as Markdown: headings, lists, tables and links. Attachments stay in Mail. An email whose body Mail never downloaded says so in its file.

## Free and unlocked

Your newest 1,000 emails export and keep syncing free. "Unlock Mail" is a one-time purchase: after it, press "Sync Now" and the rest of what is ticked syncs. A first sync of a large mailbox that you quit carries on where it stopped.

## Sync

While Exporter runs, it watches Mail's index, and new mail becomes files on its own. "Sync Now" runs it by hand; "Full Resync" writes every file again.

## Command line

`exporter sync --source mail` syncs Mail like the card's "Sync Now". `exporter export --source mail --dest <folder>` writes the emails into a folder granted on the Command Line card and leaves the card's own sync alone. See [the command line](https://exporter.dev/docs/cli).

## Problems and fixes

- The pick page says no mail: select `~/Library/Mail` itself in the panel, not a folder inside it. Disconnect and connect again to get the panel back.
- An account is missing: an account with no email to write (an empty Outbox, say) is not listed.
- A file says the body was not downloaded: Mail has only the headers. Open the email in Mail once and the next sync writes the body.

## Related

- [Mail](https://exporter.dev/mail): Every email as a Markdown file
- [Messages](https://exporter.dev/docs/messages): Conversations, media, fields and fixes
- [MCP server](https://exporter.dev/docs/mcp): Connect Claude and other agents

---

human version: https://exporter.dev/docs/mail
every page: https://exporter.dev/llms.txt