@finopsbricks/fob-email connects to any mailbox that speaks IMAP, and to SMTP for sending. One npm package gives you two ways in:
| You want to… | Use | Start here |
|---|---|---|
| Find, read, download and file mail from a terminal, or let an AI agent do it | The CLI, fob-email | Install the CLI |
| Read or send mail from your own scripts and workers | The library, import { fobEmail } | Use the library |
Both need the same thing first: your mailbox's IMAP server and an app password. Connect a mailbox walks you through it in about five minutes.
fob-email works with Gmail, Google Workspace, Yahoo, iCloud, Fastmail and other IMAP servers that accept a password. It does not work with Outlook.com or Microsoft 365, which require OAuth sign-in. See Beta limits.
How it works#
fob-email runs on your machine, or in your worker, and talks directly to your mail provider over IMAP and SMTP. No FinOpsBricks server sits in between, and your mail and passwords are never sent to us.
- Credentials live in
~/.fob/fob-email/config.yml(file mode 0600) for the CLI, or in theFOB_EMAIL_ACCOUNTSenvironment variable for workers and CI. - Reads are live. Every command asks your mail server directly, unless you opt into the local mirror with
--cached. - Reading doesn't change anything. Opening a message with
emails showdoes not mark it as read.
What you can do#
| Resource | Read | Change |
|---|---|---|
emails | List a folder, search it, show a message, download its attachments | Mark read or unread, move, delete, send |
threads | List conversations, show a whole conversation | — |
drafts | List drafts | Create, replace, delete and send drafts |
folders | List folders | Create, rename and delete folders |
sync | Show what is mirrored locally | Mirror folders into a local database, clear the mirror |
config profiles | List accounts | Add, switch, remove and re-check accounts |
Every read has --json for scripts. The command reference lists every command and option.
Beta limits#
- Password sign-in only. There is no OAuth, so Outlook.com, Hotmail, Microsoft 365, and Google Workspace domains that block app passwords cannot connect.
- Search is IMAP search: keywords, sender, subject and date. There is no semantic search.
- No paging. Lists return the newest messages up to
--limit(default 50). - Message IDs belong to a folder. An ID from
INBOXmeans nothing in another folder, and a message gets a new ID when it moves. - No replies or forwards with threading headers yet.
drafts editreplaces the whole draft. - The local mirror is manual, stores headers and flags but not message bodies, and needs Node.js 22.13 or later.
- Passwords are stored in a plain YAML file protected by file permissions, not in your system keychain.
Missing something? Open an issue on GitHub.
fob-email is not affiliated with or endorsed by Google, Yahoo, Apple, Fastmail or Microsoft. Product names are trademarks of their owners.