inbox-export

---
name: inbox-export
description: Turns a mailbox export into dated, searchable files you keep on your own machine, with one index that answers questions without opening your mail client, and a list of what would not export.
---

# A year of email turned into a searchable file you own

You point it at the export file your mail provider gives you. You get back a folder of one file per message, one index you can search in a second, and a report saying exactly what came out, what did not, and what personal information is now sitting in that folder.

Run the whole thing in one pass:

```
codex exec -C "the folder" - < the-prompt.md
```

## What it does

1. **Gets the mail out the read only way, and says so before starting.** For a Google account that is Takeout, which produces the messages in mbox format. It does not connect a live mail tool for this. The Gmail plugin published in openai/plugins asks for the scopes https://mail.google.com/ and gmail.modify, which allow changing, labelling and trashing your mail; an export needs none of that, and nothing in this skill should ever hold a permission it does not use.
2. **Tells you which export options to pick, with the real numbers.** Choose zip over tgz on Windows: Google's own guidance is that zip files "can be opened on almost any computer", while for tgz "you may need additional software to open these files on Windows". Choose a 2GB or 4GB split rather than 50GB, because a broken download of a 50GB part starts again from zero. Then download it promptly: "Your archive expires in about 7 days" and "We only allow each archive to be downloaded 5 times".
3. **Unpacks into a folder you name, and never opens the mailbox itself.** Everything after this point reads one file, the .mbox, and writes only into new folders. There is no step in this skill that deletes, moves, marks as read or re-labels anything, in the export or in the live account.
4. **Reads the mbox with Python's standard library, opened read only.** `mailbox.mbox` is in the standard library, needs nothing installed, and understands the format: "All messages in an mbox mailbox are stored in a single file with the beginning of each message indicated by a line whose first five characters are 'From '". The library's own warning is why the file is never written to: "Failing to lock the mailbox runs the risk of losing messages or corrupting the entire mailbox."
5. **Writes one file per message into year and month folders.** Named date, sender, subject, with anything unsafe for a filename stripped and the name capped so long subjects cannot break the path. The real key is the Message-ID header, kept in every file and in the index, so the same message appearing twice (in All Mail and in a label) collapses to one entry instead of two.
6. **Builds the index, which is the thing that actually answers questions.** One CSV or one JSON line per message holding date, from, to, cc, subject, the labels read from the X-Gmail-Labels header that Google adds to the download, attachment filenames, word count, and the path to the message file. A question like "what did the accountant say about the van in March" is answered by searching this one file, with the mail client shut.
7. **Saves each attachment once, by content hash, and links it from the index.** Identical files sent five times take the space of one. Anything that fails to decode is not skipped silently: it gets a row in failures.csv with the Message-ID, the filename and the reason.
8. **Records the two things mbox quietly does to text, rather than guessing.** A body line beginning ">From " may be an escape the format added, since implementations escape lines starting with "From " to stop parsers mistaking them for a new message, "with 'From ' becoming '>From '", and Python's reader does not turn them back. Encrypted messages stay encrypted: Google states "encrypted messages remain encrypted. Messages aren't decrypted in the download." Both are noted in the report, not silently rewritten.
9. **Writes EXPORT-REPORT.md in plain English.** Messages found, messages written, failures, the date range actually covered, the largest gap in that range with no mail at all (usually a sign of a partial export), and one paragraph naming what personal information the folder now contains: your correspondents' names and email addresses, anything they sent you, and, if it is in there, bank details, home addresses, health information or staff and customer records.

## Then it checks

1. Messages read, message files written, and rows in failures.csv are all printed, and the first equals the sum of the other two. Anything else means messages vanished quietly and the run is reported as failed.
2. The size and last modified time of the original .mbox are printed before and after and must be identical. If they differ, the run wrote to the mailbox, which it must never do, and it stops rather than trying again.
3. Five messages are picked at random and compared field by field against their index rows: date, sender, subject, attachment names.
4. Three words are taken from three random message bodies and searched for through the exported files. All three must be found, which proves the index and the files are actually searchable rather than merely present.
5. The report names a date range, and that range is checked against the oldest and newest message actually written, not against what the mail provider claimed to send.
6. No password, app password, token or account credential appears in any output file, including the report.

Any check fails: name it, redo that step once. Failed twice: say what is wrong and stop.

## Rules
- Public information only leaves this machine. The mailbox, the exported files and the index stay in the folder the owner named. Nothing is uploaded, pasted into a website or sent to any service.
- Never invent a fact, a number or a quote. If 412 messages could not be parsed, the report says 412, not "a few".
- Never delete, move, mark as read or re-label anything, in the export or in the live mailbox. This skill reads a copy and writes new files. It has no delete step and must never be given one.
- Say plainly, in the report, what personal data the export now holds and where the folder is, because an unencrypted copy of a year of email is one of the most sensitive things on a home computer. Recommend that it lives on an encrypted drive or in an encrypted archive.
- If the mailbox holds other people's personal data, such as customers, staff or patients, this skill only prepares the export and describes what is in it. It is not data protection advice. How long that copy may be kept, and where, is a question for a professional to check.

## Built from
- openai/plugins, https://github.com/openai/plugins, 5,467 stars read from api.github.com on 7 September 2026: the gmail plugin's .mcp.json requests https://mail.google.com/, gmail.modify, gmail.compose, gmail.readonly and gmail.metadata, and its plugin.json declares the "Write" capability. Reading that is what set step 1: an export is a read job and must not run through a connector that can also change and trash mail.
- Download your Google data, Google Account Help, https://support.google.com/accounts/answer/3024190: zip versus tgz and the note that tgz "may need additional software" on Windows, the 1GB, 2GB, 4GB, 10GB and 50GB split choices, the roughly 7 day expiry, the 5 download limit, and the X-Gmail-Labels header that carries your labels into the download. All of step 2 and the label column in step 6 come from this page.
- Export your data from Gmail, Gmail Help, https://support.google.com/mail/answer/10016932: confirms the export carries message content, message headers, attachments, labels, user defined labels and IMAP keywords, plus settings such as signatures, filters and forwarding addresses, and warns that "encrypted messages remain encrypted. Messages aren't decrypted in the download." That warning is why step 8 reports encrypted messages instead of counting them as failures.
- RFC 4155, The application/mbox Media Type, https://www.rfc-editor.org/rfc/rfc4155.txt, published September 2005: each message begins with a separator line of the exact sequence "From" plus a space, an address and a timestamp, and implementations escape body lines starting with "From " so that "'From ' becomes '>From '". That is the escaping behaviour reported in step 8.
- mailbox, Python standard library documentation, https://docs.python.org/3/library/mailbox.html: the mailbox.mbox class, the definition of the format used in step 4, the note that the reader implements the original mboxo behaviour and does not convert ">From " back when reading, and the locking warning quoted in step 4.