list_emailsLABSCO SUMMARY
The local cache is what makes agent use of it bearable — listing reads from disk, not IMAP.
Bulk mark and delete by sender or subject is the feature that turns inbox cleanup into one instruction instead of a loop over message IDs. Destructive actions default to a dry-run preview and require a confirm flag, which is the right posture for handing an agent access to real mail.
What it is
A CLI-first, multi-account email tool with a local sync cache, shipping an optional MCP server so an agent can list, read, mark and delete mail.
What you get
- List and read mail across accounts, filtering by sender or subject against the local cache
- Mark read and delete, with a dry-run to validate before it touches the mailbox
- Bulk actions by sender or subject, so you do not need a list of message IDs
- Built-in providers for 163, QQ Mail, Gmail and Outlook/Hotmail, plus custom IMAP servers
- A local sync cache so listing does not hit IMAP every time; --live forces a fresh fetch
Requirements
The mailbox binary — installed via the GitHub Releases install script (macOS arm64/x64, Linux x64), no Node required for end users. Account credentials go in ~/.config/mailbox/auth.json. The MCP server is generated with mailbox mcp config --json, which prints a paste-ready client entry. Deletes require a confirm flag.
Setup effort
One command plus credentials — curl -fsSL https://raw.githubusercontent.com/leeguooooo/Mailbox/main/install.sh | sh, then supply credentials
USE CASES
01
Clearing out newsletters in bulk
Delete everything from a sender at once — preview first with a dry run, then confirm.
02
Triaging unread mail across accounts
List unread messages filtered by sender, working from the cache rather than a live fetch each time.
03
Reading one message in full
Show a message by ID, including the unsubscribe link when the header is set.
04
Marking a batch read without IDs
Mark everything from a given sender as read in a single call.
20 tools
Listed in project docs. Your client may show a different list.
get_email_detailmark_emailsmark_email_readmark_email_unreadbatch_mark_readdelete_emailsdelete_emailbatch_delete_emailssearch_emailssend_emailreply_emailforward_emaillist_foldersmove_emails_to_folderflag_emailget_email_attachmentscheck_connectionlist_accountssync_emailsBEFORE YOU INSTALL
What to know first
Tools you get
20 tools named in the project's documentation.
INSTALLATION
Connect your client
Server setup
Install the CLI: curl -fsSL https://raw.githubusercontent.com/leeguooooo/Mailbox/main/install.sh | sh (downloads the prebuilt binary for macOS arm64/x64 or Linux x64, verifies its checksum, installs to ~/.local/bin)
Verify:
TERMINAL
mailbox --helpConfigure accounts: mkdir -p ~/.config/mailbox then curl -fsSL https://raw.githubusercontent.com/leeguooooo/Mailbox/main/examples/accounts.example.json -o ~/.config/mailbox/auth.json and edit it: for each account set email, password (the app password or IMAP authorization code) and provider (163, qq, gmail, outlook), delete the example accounts you do not use, and set default_account
Generate the MCP client entry: mailbox mcp config --json (prints a paste-ready mcpServers entry)
Optional deprecated alternative:
TERMINAL
npm install -g @leeguoo/mailbox-cliMCP Clients
Claude Desktop, Claude Code, Cursor
TERMINAL
mailbox mcp config --json # prints a paste-ready mcpServers entry
