How to Download Your Emails from Any Mail Provider

To keep a copy of email from Gmail, Outlook, iCloud, or another provider, you need to download the messages or export them into files. Another app may only keep email synchronized with the server, meaning it keeps the same messages and changes in both places. If you delete a message there, the deletion can appear in the app too, as Thunderbird’s IMAP guidance explains.

For a local archive that works across providers, mailmd copies messages into Markdown files on your computer. It connects to any mailbox that supports IMAP, and uses provider APIs for Gmail and Outlook.com or Microsoft 365. The right connection method depends on your provider and account settings.

Choose a download method #

A provider’s own export is a good fit for a one-time copy when it includes the folders and messages you need. Gmail offers a bulk export through Google Takeout, while Outlook supports exporting mail to a PST file, an Outlook data file used to store email and other Outlook information. Outlook’s export steps vary by version, and Microsoft notes that some PST contents are not supported in new Outlook. See Google’s export details and Microsoft’s Outlook export instructions.

For a copy that is easy to browse and search as ordinary files, use mailmd. Many providers allow a connection through IMAP, a standard way for email programs to access and synchronize mailbox folders. Some require an app password, which is a separate password for an email connection. Others restrict IMAP by account type or subscription, so check your provider’s settings if access is denied. For example, iCloud’s connection instructions require an app-specific password for manual setup, and Yahoo’s POP settings describe access that can be limited to the Inbox.

Download messages with mailmd #

mailmd is a free, open-source command-line tool. A command-line tool runs by typing instructions in a terminal. It saves one Markdown file per message, with message headers, such as the sender and date, at the top. The tool turns HTML email into readable Markdown. It stores attachments beside the message files and organizes folders and years as directories. Add --keep-raw to save each original message as an .eml file too.

On Linux, macOS, or Windows in Git Bash, install and connect mailmd from a terminal:

curl -fsSL https://raw.githubusercontent.com/vincentsch/mailmd/main/install.sh | sh
mailmd connect imap --email you@example.com
mailmd sync

Use mailmd connect imap for an IMAP mailbox. If the provider requires an app password, mailmd will tell you. For Gmail, choose either IMAP with an app password or the Gmail API. For the API connection, create your own OAuth app in Google Cloud, then run mailmd connect gmail --client-secret client_secret.json. OAuth lets mailmd request read access through Google’s sign-in flow. Google explains its supported connection options in its email-client settings.

Outlook.com and Microsoft 365 connect through Microsoft Graph, Microsoft’s service for accessing account data. Create an OAuth app in Microsoft Entra, then run mailmd connect outlook --client-id <id>. These API sign-ins request read access. For other providers, use IMAP if the account permits it.

After the first sync, mail is stored in ~/mail/<account>. Run mailmd sync again to add new messages and update read and starred marks. If you interrupt a sync with Ctrl-C, mailmd keeps what it has already saved and continues on the next run. It leaves spam and trash out unless asked for; Gmail over IMAP includes archived mail through All Mail. Use --folder, --exclude, or --since to choose what to copy.

mailmd only reads the mailbox: it does not mark messages as read, move or delete them, or send email. It also never deletes files from the archive. A message later deleted from the server stays in the archive and is marked as deleted on the server. The files are searchable with an editor or tools such as rg or grep; index.jsonl lists messages for scripts. To keep the copy current, schedule mailmd sync --quiet with your computer’s scheduler.

mailmd stores your sign-in details outside the archive. Only your user account can read them, but they are not encrypted. The archive itself contains your email, so protect it as sensitive data and keep a separate backup. mailmd does not free mailbox space by itself. Delete messages from the provider only after checking that the downloaded copy is complete. It is an archive tool, not a mail client, and it does not import mail back into a mailbox or convert it to PST or PDF.

Check the archive before relying on it #

Open several files, including recent and older messages, messages from sent mail or custom folders, and messages with attachments. Check that the folders you expected are present. With IMAP, a list of message subjects alone does not prove that full messages have downloaded; the bodies and attachments need to be available in the local copy.

To find a message later, search the Markdown files in an editor or use rg or grep in a terminal. For ongoing protection, schedule a sync and back up the archive separately. mailmd does not provide its own search engine or backup storage.