How to Export Your Gmail to Files You Can Read

If you want to keep Gmail messages as files on your computer, choose a format that suits how you plan to read them. Google Takeout saves Gmail in MBOX, a mailbox format designed to hold many messages. A mail program can open it, but it is less convenient to browse than ordinary documents. For a readable local archive, mailmd is the best fit: it copies messages into Markdown files, a plain-text format that people can read and edit.

mailmd saves each message as a separate file and puts its attachments alongside it. The steps below show how to connect Gmail and create that archive, while noting when a Google export or a single-message download makes more sense.

Choose files for a mailbox or a few messages #

Use mailmd when you want a folder of readable files for many messages. Use Google Takeout when you need Google’s own mailbox archive: it exports messages and attachments in MBOX, which you then open with compatible mail software. Google’s Gmail export information describes the data included in that export.

For one message, Gmail’s More > Download message command saves an EML file containing that email. For a document you can share or print, Gmail’s print command can save a message or conversation as a PDF. Google documents both options for downloading messages and printing Gmail.

Export Gmail with mailmd #

mailmd is a free, open-source command-line tool licensed under the MIT license. You run it by typing commands in a text-based terminal. It connects to Gmail through either the Gmail API or IMAP, a standard that lets mail programs access email. Its project instructions describe the supported connection options.

On Linux, macOS, or Windows in Git Bash, install mailmd and connect an account:

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

For Gmail through IMAP, use an app password if your provider requires one; mailmd tells you when you need one. You can instead connect through the Gmail API with mailmd connect gmail --client-secret client_secret.json. That option requires setting up your own OAuth app in Google Cloud. OAuth lets you sign in and grant an app specific access without giving it your account password.

After mailmd syncs your account, it saves mail under ~/mail/<account>. Each message becomes a Markdown file with email headers, such as sender and date, at the top. HTML messages are converted into readable Markdown; links and tables are kept, while tracking images and hidden preview text are dropped. Attachments sit next to the message, and mail folders and years become folders on your computer. Add --keep-raw to save the original EML file too.

mailmd requests read access and opens mail folders read-only. It does not mark messages as read or send mail. It also does not change, move, or delete messages in Gmail. Spam and Trash are skipped unless requested. For Gmail over IMAP, mailmd syncs All Mail, which includes archived messages. Use --folder, --exclude, or --since to choose what to copy.

Keep the archive useful and protected #

Run mailmd sync again to add new mail and update read and starred marks in the local files. If you interrupt a sync with Ctrl-C, mail already saved stays in place, and the next run continues. To keep the archive current, schedule mailmd sync --quiet with a scheduler on your computer.

You can read the Markdown files in an editor or note-taking app. You can search them with rg or grep. Use jq to filter index.jsonl, a file that lists messages. mailmd has no built-in search engine. It also does not delete Gmail messages or free mailbox storage; delete messages from Gmail yourself only after checking that the local copy is complete.

The archive contains private email. mailmd stores login details outside the archive, where only your computer user can read them. The details are not encrypted. There is no mailmd server or telemetry. If you give a coding assistant access to the archive, it sends any content it reads to its model provider. Consider this before granting access.