imbox: reading IMAP mailboxes as machine-readable data for agent workflows

What imbox solves, and who it is actually for

Most Python mail code is written for a human at the end of the pipe: connect, list folders, print subjects, read a body. imbox takes the same IMAP connection and treats the mailbox as a data source. The README describes it as a "Python library for reading IMAP mailboxes and converting email content to machine readable data", and the CLI section says the JSON output is "particularly useful for agentic workflows".

The audience follows from that. If you are building a script that watches an inbox for a specific sender, pulls attachments, or feeds recent messages into an agent loop, imbox gives you a filter vocabulary (folder, unread, flagged, sender, recipient, subject, date comparisons, UID range) and a message object with named fields. If you want a mail client, a sending library, or a full synchronisation engine, this is the wrong layer. The library reads. The README documents no send path.

How the library works: connection, filters, message objects

The mechanism is thin on purpose. You construct an Imbox context manager with a host, username, password and SSL or STARTTLS settings, and the connection is opened and closed by the with block. Every query is a method on that object. The README shows the shape: imbox.folders() returns a status plus folder information, and imbox.messages() returns an iterable of (uid, message) pairs.

Filters map onto IMAP search criteria. unread, flagged and unflagged are booleans. sent_from, sent_to and subject take strings. date__lt, date__gt and date__on take datetime.date values, and uid__range takes a string such as '1050:*'. Two Gmail extensions are exposed through label and raw; the README marks both as Gmail-specific, with raw accepting a Gmail search string like 'from:martin@amon.cx has:attachment'.

Each message object carries sent_from, sent_to, subject, headers, message_id, date, and body.plain. That field list is the contract you build on, and it is deliberately flat: there is no threading model, no attachment enumeration in the documented keys, and no incremental state. If your workflow needs those, imbox is a starting point rather than a complete answer.

Installing imbox and fetching your first mailbox as JSON

The library installs from PyPI with a single command. The README gives no build step and no system dependencies beyond Python itself, which the requirements section lists as 3.11, 3.12 and 3.13; pyproject.toml sets requires-python to ">=3.11" and declares one runtime dependency, chardet.

pip install imbox

The CLI is the fastest way to see what imbox produces. The README recommends running it with uv, and the entry point is registered in pyproject.toml as imbox = "imbox.cli:cli".

uv run imbox messages

That command needs credentials. They come from environment variables, and the repository ships a .env.example that lists them with Gmail defaults. Copy it, fill in your address and an app password, and export the values before running.

IMBOX_IMAP_URL=imap.gmail.com
IMBOX_USERNAME=your-email@gmail.com
IMBOX_PASSWORD=your-app-password
IMBOX_SSL=true
IMBOX_PORT=993

With credentials in place, filters can be combined. This fetches unread messages from one sender in the INBOX. The output is written to a JSON file when OUTPUT is enabled, and the filename defaults to imbox_results.json.

uv run imbox messages --folder "INBOX" --unread --sent-from "newsletter@example.com"

Listing folders is a separate command and is the right first check against a new server, because folder names are provider-specific.

uv run imbox folders

If a run returns nothing or fails silently, the README's debugging section turns on verbose logging. Expect a much larger log volume, since it covers the IMAP conversation.

DEBUG=true LOG_LEVEL=DEBUG uv run imbox messages --unread

The CLI contract: environment variables and output shape

The CLI is configuration-driven rather than flag-driven for connection settings, and that is a deliberate fit for agent workflows: an agent can be handed a set of environment variables without learning a command line. The documented variables cover the server URL (IMBOX_IMAP_URL, default imap.gmail.com), credentials, transport (IMBOX_SSL default true, IMBOX_STARTTLS default false, IMBOX_PORT default 993), logging (DEBUG, LOG_LEVEL default INFO), and output.

The output side is where the CLI makes a choice worth understanding. LOG_OUTPUT_TYPE accepts default or clean; clean "displays only email fields" while default "includes imbox metadata". OUTPUT is a boolean that enables file output, OUTPUT_FOLDER defaults to output, and OUTPUT_FILENAME defaults to imbox_results.json. The .env.example also shows OUTPUT_FIELDS with a value like "subject, date", which suggests field selection is configurable, though the README's variable table does not describe that key. Treat OUTPUT_FIELDS as present in the example file but undocumented in the table, and confirm its behaviour against the code before depending on it.

The defaults are Gmail-shaped. If you point imbox at a different provider, IMBOX_IMAP_URL and IMBOX_PORT are the first two values to change, and IMBOX_STARTTLS exists precisely for servers that want it.

Where imbox stops: read-only, stateless, and provider-shaped

The clearest limitation is scope. imbox reads mailboxes. There is no documented send, move, delete or flag-setting operation, so any workflow that needs to act on a message rather than consume it has to reach for another library.

The second limitation is state. Every call to messages() is a query against the live server. There is no local index, no cursor, and no deduplication. A polling loop that fetches unread messages will re-fetch the same messages until something else marks them read, because imbox itself does not. If you want incremental processing, you own the bookkeeping, and uid__range is the documented primitive for it: you persist the highest UID you have handled and ask for '1051:*' next time. That works, but it is your code, not the library's.

The third limitation is provider coupling. The label and raw filters are documented as Gmail-only, and the default IMAP URL is Gmail. Running against a generic IMAP server is supported through the connection settings, but the filter set you can use shrinks.

Finally, the Python floor is 3.11. Projects pinned to 3.10 or older cannot use the current release at all.

imbox against Python's built-in imaplib and email

The obvious alternative is the standard library: imaplib for the connection and search, email for parsing. The difference is not capability, since imbox is built on the same protocol, but the amount of glue you write. With imaplib you construct search strings yourself, handle the response tuples, decode charsets, and walk MIME parts to find a plain body. imbox packages that into named filters and a message object with body.plain already resolved, and adds chardet for charset detection.

The trade-off runs the other way too. imaplib has no dependency and no version floor beyond your interpreter, and it exposes the full IMAP command set, including the mutating operations imbox does not document. If your workflow only needs to mark messages read or move them between folders, the standard library is the shorter path. imbox earns its place when the parsing and the filter vocabulary are the bulk of the work, which is the common case for an agent that consumes mail. The CLI is the second differentiator: imaplib gives you nothing to run from a shell, while imbox ships a console script that writes JSON.

Maintenance, licensing, and what an upgrade costs you

The repository is not archived, and the last push was on 2026-06-23, so the project is being touched. The release history is more uneven than that suggests: 0.9.6 in 2018, 0.9.9 in 2022, then 0.10.0 in March 2026, with pyproject.toml already at 0.10.1. The long gaps mean you should read the CHANGELOG before upgrading rather than assume semantic versioning will protect you.

The dependency surface is small, which keeps upgrade risk low: one runtime dependency, chardet, plus an optional dev extra that pulls in pytest, mypy, black, ruff, pre-commit and pytest-recording. The recorded-test setup matters for contributors, because it means the test suite can replay IMAP interactions without live credentials.

The licence is MIT, which permits commercial and closed-source use and requires only that the copyright notice and permission notice are preserved. That is a permissive arrangement, but it is not legal advice; if you redistribute imbox inside a product, have your own counsel confirm the notice requirements.

Editorial conclusion

Adopt imbox if you need a small dependency that reads a mailbox and hands structured messages to a script or an agent, and if Python 3.11 or newer is acceptable. Do not adopt it if you need to send mail, maintain a persistent sync state, or run on Python 3.10 or earlier. Before committing, verify two things against your own server: that the CLI flags you plan to use are accepted by your provider (the Gmail-only label and raw options are called out as Gmail-specific in the README), and that your credential is an app password where the provider requires one, since IMBOX_PASSWORD is documented as accepting either a password or an app password.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. martinrusev/imbox on GitHub
4. README
5. Releases