Notes and limits

Worth knowing before you rely on it.

IMAP search is server-side and fairly basic

It matches substrings, not fuzzy relevance, and there is no "has attachment" criterion in IMAP itself — the has_attachments field on results comes from the message structure, not from the search.

The upside is that it runs on the server: searching a 200,000-message archive downloads nothing.

Bodies are truncated

At 20,000 characters by default, to keep long newsletters from flooding the context. Raise max_chars on read_message when you need more — it accepts up to 200,000. The returned truncated flag tells you whether it bit.

Only the text parts are downloaded

read_message locates the text parts via BODYSTRUCTURE and fetches only those, so reading a mail with a 20 MB attachment still costs a few kilobytes.

It prefers text/plain but falls through to text/html when the plain part is missing or empty — the shape many newsletters take. body_format says which one you got (text, html-converted or none).

HTML is converted to Markdown with reference-style links, so a newsletter that repeats the same tracking URL on every headline lists it once at the foot instead of inline on every line.

Microsoft is actively tightening third-party mail access

IMAP + OAuth is documented and working, but if it were ever withdrawn for consumer accounts, the fix is a Graph backend behind the existing MailBackend protocol — the tool layer would not change. The endpoint overrides already let you correct a changed host or scope without waiting for a release.

There is no macOS installer

Linux and Windows installers are published per release. On macOS, run it from source — it is one pip install -e ..