// the find
asweigart/ezgmail
A Pythonic interface to the Gmail API.
ezgmail wraps the Gmail API into a flat module-level interface — send, search, read, trash, handle attachments — without the boilerplate of google-api-python-client. It's aimed at beginners and automation scripters who want to send email from Python in under ten lines. Al Sweigart wrote it as a companion to his 'Automate the Boring Stuff' books.
The API surface is genuinely minimal: `ezgmail.send()` and `ezgmail.search()` cover 90% of what people actually need. The README is unusually complete for this type of library — it walks through the entire Google Cloud OAuth setup with screenshots, which is the part everyone gets stuck on. The GmailThread/GmailMessage model maps cleanly to how Gmail actually works. Attachment download is handled without making you touch the raw API response.
The Limitations section in the README is embarrassingly out of date — it says the library can't do cc/bcc or mark emails as read, but those features were added years ago and are documented right above it in the same README. The token.json flow ties credentials to the working directory, which means you can't easily run this in a server context or with multiple accounts without manual file shuffling. There are no async APIs at all, so anything doing bulk email processing blocks the event loop. Test coverage is minimal — `tests/how-to-run-this-test.txt` is a file that exists, which tells you everything about the state of the test suite.