Quickstart #

On this page you install mailmd, connect your mailbox and copy your mail into Markdown files.

Install #

On Linux and macOS, and on Windows in Git Bash:

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

The script downloads the binary for your system from the latest GitHub release and checks its SHA-256 checksum. Then it puts the binary in ~/.local/bin. If that folder is not on your PATH yet, the script prints the line to add. Two environment variables change what the script does:

You can also download a binary from the releases page and compare it with checksums.txt, or build it with Go:

go install github.com/vincentsch/mailmd/cmd/mailmd@latest

Check that it works:

mailmd --version

See the files first #

mailmd demo

This writes eight sample messages to ./mailmd-demo/demo. The mail is built into mailmd, so you need no account, and mailmd makes no network connections. Look at a few of the files to see what your own mail will look like.

Connect a mailbox #

The quickest way is IMAP with your email address:

mailmd connect imap --email you@example.com

mailmd fills in the server for known providers. Then it asks for the password in a hidden prompt, which doesn't show what you type. If your provider needs an app password, mailmd says so and tells you where to create one. The IMAP guide lists the settings and links for common providers.

When the login works, mailmd shows how many folders it found and where the mail will go:

Connected fastmail (you@fastmail.com).
The mailbox has 5 folders. A sync copies 3 of them and leaves out Spam and Trash.
Mail goes to ~/mail/fastmail.

Next: mailmd sync fastmail

The account name comes from the provider or your address. You can pick your own with --account, like --account work. It is also the name of the archive folder.

Other ways to connect:

• Gmail through the Gmail API, with your own Google Cloud OAuth client.
• Outlook.com and Microsoft 365 through Microsoft Graph, with your own app registration. Use this for Microsoft mailboxes, because most of them no longer accept passwords over IMAP.

To test a login without saving anything, add --dry-run.

Choose where the mail goes #

By default each account gets its own folder in ~/mail. To use another folder, give --out when you connect:

mailmd connect imap --email you@example.com --out ~/Documents/mail

--out is the folder that holds the account folders. mailmd puts each account in a folder of its own inside it, so the mail of an account named work goes to ~/Documents/mail/work. mailmd saves the folder for that account. For a single sync into another folder, use mailmd sync --out <folder>.

Moving the archive #

mailmd doesn't move any files when you change --out later. You move the account's folder yourself, then tell mailmd the new place. Say your archive is in ~/mail/work, and you want it in ~/Documents/mail/work:

1. Make sure no sync runs. If you sync on a schedule, pause the job.

2. Move the account's folder. A normal move takes the hidden .mailmd folder with it, which holds the position of the last sync:

   mkdir -p ~/Documents/mail
   mv ~/mail/work ~/Documents/mail/

   On Windows, move the folder in Explorer, or with Move-Item in PowerShell.

3. Save the new place. --out is the folder that holds the account folders, so mailmd adds work itself:

   mailmd connect imap --account work --out ~/Documents/mail

   mailmd keeps the saved password and your other settings. For Gmail and Outlook, use mailmd connect gmail or mailmd connect outlook with the account name. They keep the saved login and don't sign in again.

4. Run mailmd sync work. It says that work is up to date, or it fetches only the mail that is new since the last sync.

If you change --out first, mailmd says that the archived mail stays in the old folder, and you move it before the next sync. A sync that runs before the move starts a new archive in the new place and downloads the mail again. Nothing is lost then, but you have two copies.

The config folder isn't part of the archive, so it stays where it is. The same goes for a CA file that you gave with --ca-file. If you move that file, connect again with --ca-file and the new path. Also change the path in your scheduled job and in your agent instructions, if they name the folder. The next section shows how to move the config folder.

Moving the config folder #

The config folder holds the account list and the saved logins. It also has the result of each account's last sync. Finding the files says where it is.

mailmd finds the files in the config folder by their place inside it, so you can move the whole folder. Two settings point outside it, and mailmd saves them as full paths. These are the archive folder from --out and the CA file from --ca-file. Moving the config folder doesn't change them. Say you set MAILMD_CONFIG_ROOT=~/work/mailmd-config, and you want the settings in ~/Documents/mailmd-config:

1. Make sure no sync runs. If you sync on a schedule, pause the job.

2. Move the folder with everything in it:

   mv ~/work/mailmd-config ~/Documents/mailmd-config

3. Set MAILMD_CONFIG_ROOT to the new folder, like export MAILMD_CONFIG_ROOT=~/Documents/mailmd-config. Also change it in your scheduled job and in your agent instructions.

4. If you moved the CA file, give mailmd its new path. mailmd keeps the saved password:

   mailmd connect imap --account work --ca-file ~/Documents/company-ca.pem

   Run this after step 3, so that it changes the settings in the moved folder.

5. Run mailmd sync work. It says that work is up to date, or it fetches only the new mail.

If the archive moves as well, follow Moving the archive for it before step 5.

Without MAILMD_CONFIG_ROOT, mailmd's files are in a folder named mailmd, like ~/.config/mailmd. To move it, keep that name, like mv ~/.config/mailmd ~/Documents/mailmd. Then set MAILMD_CONFIG_ROOT to the new folder, ~/Documents/mailmd.

Sync #

mailmd sync

Without a name, mailmd syncs every connected account. In a terminal it shows each folder and how many messages it has fetched so far. At the end it prints one line per account:

Syncing fastmail to ~/mail/fastmail
  Archive                  94 new
  INBOX                    412 new
  Sent                     118 new
  Left out: Spam and Trash. To copy one of them, give it to mailmd connect with --include.
mailmd checked 3 folders and saved 624 new messages to ~/mail/fastmail in 12 s.

The first sync of a large mailbox can take a while. You can stop it with Ctrl-C at any time. The files saved so far stay, and the next sync continues from there.

Later syncs fetch only new mail. They also update the flags of a message that you read or starred since the last run. When a message was deleted on the server, your file stays. mailmd marks it with deleted_on_server and tells you about it.

Sync only part of your mail #

Give these flags to mailmd connect to save them for the account. You can do that when you first connect, or later with the account name. mailmd then keeps the saved password or login, so it doesn't ask for it:

mailmd connect imap --account fastmail --include Spam

Changed the settings of fastmail (you@fastmail.com) and kept its saved password.
The mailbox has 5 folders. A sync copies 4 of them and leaves out Trash.
Mail goes to ~/mail/fastmail.

mailmd sync takes the same flags, except --include, for one run. mailmd doesn't save them. On sync, --folder and --exclude replace the folder settings saved with the account for that run. So mailmd sync fastmail --folder Spam copies only the spam folder, once, and the next normal sync leaves it out again. Add --dry-run to see first how many new messages a sync would save. A dry run writes nothing.

To see the folders on the server, run mailmd list folders fastmail. It shows how many messages each folder has and whether a sync copies it. For a folder that a sync leaves out, it also says why.

--since goes by the day the server received a message. That can be later than the date in the message. If you moved to a new provider and copied your old mail over, that mail can count as received on the day of the move.

How the folder flags work together #

Without folder settings, a sync copies every folder except spam and trash. For a Gmail address over IMAP, mailmd syncs only [Gmail]/All Mail. That gives you one copy of every message, but no separate Inbox or Sent folder. The IMAP guide shows how to sync chosen labels instead.

The three folder flags change that:

• --include Junk copies Junk in addition to the folders a sync copies anyway. Use it when you want one more folder.
• --folder INBOX copies only the folders you name, and the ones that --include adds. On mailmd connect this means that from now on a sync copies only these folders, and folders you create later on the server are left out. A folder you name is copied even when it is left out by default, like Junk.
• --exclude Newsletters leaves out a folder. It wins over --folder and --include.

You can repeat each flag for more folders. On mailmd connect, each flag replaces the list that is saved for it and keeps the others. So --include Junk keeps a saved --exclude Newsletters. To clear a saved list, give the flag an empty value, like --folder ''. With --folder '' --include '' --exclude '', a sync copies the default folders again.

This is how mailmd matches folder names:

• A name matches the folder and all its subfolders. So --exclude Work also leaves out Work/Clients. Names are not case sensitive.
• * stands for any part of a name, but not for the / between a folder and its subfolder. So 'Work/*' matches Work/Clients and its subfolders, but not Work itself. --folder Work copies Work and all its subfolders.
• '*' matches every folder. --folder '*' --exclude Trash copies all folders except Trash, also Junk and folders you create later.
• Put a name with * in single quotes, so that your shell doesn't change it.

If a --folder or --include matches no folder, mailmd stops with an error that lists the folders the server has. On connect, it saves nothing then.

Which folders count as spam and trash #

mailmd goes by what a folder is for, and the name comes second:

• Most IMAP servers mark their special folders with a special-use flag, which says what a folder is for. A folder with the flag \Junk is spam, and a folder with \Trash is trash, whatever its name. A folder with another special-use flag, like \Archive or \Sent, is never spam or trash.

• For a folder without a special-use flag, mailmd goes by the last part of its name, in any case. So Work/Trash counts as trash. These names count:

  Folder	Names
  Spam	Spam, Junk, Junk E-mail, Junk Email, Junk-E-Mail, Bulk Mail, Spamverdacht
  Trash	Trash, Deleted Items, Deleted Messages, Bin, Papierkorb, Gelöschte Elemente

• With the Gmail API, spam and trash are Gmail's own Spam and Trash labels.

• With Outlook, they are the mailbox's Junk Email and Deleted Items folders. Microsoft says which folders these are, so their names in your language don't matter.

mailmd list folders shows the result. Spam and trash have "no, left out by default" in the SYNC column. To copy such a folder, add it with --include. If your spam folder has another name and no flag, leave it out with --exclude.

See what is in your archive #

mailmd status
mailmd list accounts

status shows how many messages each archive has and when the last sync ran. With an account name, like mailmd status fastmail, it also lists the folders and the messages mailmd couldn't save in full. list accounts shows each account and its archive folder. Neither command connects to your provider. mailmd list folders fastmail does, to show the folders as the server has them.

Remove an account #

mailmd disconnect fastmail --dry-run
mailmd disconnect fastmail

disconnect removes the account from mailmd and deletes its saved login. The archive stays as it is. With --dry-run, mailmd shows the files it would delete and changes nothing.

For Gmail and Outlook, your Google or Microsoft account still lists the app you signed in with. mailmd prints the page where you can remove it. The Gmail guide and the Outlook guide have the details.

Next steps #

• Using mailmd with an agent has prompts for Claude Code and Codex.
• Scheduling shows how to sync every few minutes.
• The file format explains each field and file.
• Troubleshooting covers login and connection problems.