benethos-hub/mailbox

One REST API for all your mailboxes, whichever provider they are at, a
Python client for it and an MCP server on top. Scripts, tools and AI
agents work with your mail through one door you control.
> **Status: beta, version 0.4.1.** Usable with real accounts. A breaking
> change of the API or the configuration is announced in the changelog.
> Stored data is carried forward by migrations.
**Contents**
- What it is for
- Working with an AI agent in your mail
- More uses
- What it can do today
- Providers
- The four packages
- Getting started
- Documentation
- Development
- Licence
What it is for
Most people and small companies have more than one mail account: a
personal address at GMX or web.de, a company mailbox at Microsoft 365, an
info@ address at some hoster, maybe a Gmail account. Each speaks its own
dialect: IMAP here, Microsoft Graph there. Every tool that wants to work
with mail has to learn all of them and has to be given the passwords.
Mailbox turns that around. It has four packages. mailbox-service runs on
your own machine or server and holds the connections to all accounts.
Everything else talks to that service only, through one REST API that
looks the same for every provider. mailbox-client is the Python
client of that API, for scripts and apps. mailbox-mcp, the MCP
server, builds on the client and opens the service to AI agents.
mailbox-common holds what the service and the MCP server share. The
service decides who may do what. A script, an app or an AI agent gets
a token of its own. That token opens exactly the accounts and
operations it was given, nothing more.
That makes a few things simple that are hard otherwise.
Working with an AI agent in your mail
Through the MCP server, Claude or another AI agent works with every
account you gave it. A few requests it handles today:
- "What came in since last night?"
- "Move every invoice from Company XY to the folder Accounting."
- "Forward today's invoices to our tax advisor."
- "Show me all mail from Company XY between the 1st and the 15th of
September."
- "Which mails with attachments came this week? Read the invoice and tell
me the amount and the due date."
- "Sum up the mails about the offer and write a draft reply."
- "Mark last week's newsletters as read and move them to the archive."
Its rights decide whether it may send on its own or only leave drafts
for a person to send. A grant can also name the recipients it may write
to, such as the tax advisor's address alone, and how many mails it may
send a day. A mail to anyone else is refused. It can keep the agent to
some folders, such as the invoices, and end after a week.
More uses
- **Controlled access.** A bookkeeping tool reads the invoice folder of
one account and nothing else. It may neither send nor delete, and it
never sees a mail password, only its own token.
- **Automation across accounts.** A script files invoices, archives
newsletters and forwards order confirmations. It works the same way for
GMX, Microsoft 365 and your own mail server.
- **Sending with guard rails.** A newsletter job sends from info@, to a
fixed list of recipients, at most a few times a day.
- **React instead of polling.** Signed webhooks tell your own system
about new mail, a ticket tool or an internal dashboard for example.
- **Traceable.** Every send is recorded in the audit: by whom, when and
under which grant. So is every sign-in and every change to users,
tokens, roles, accounts and webhooks.
- **One inbox for your own tools.** A dashboard or a small internal app
lists, searches and answers mail from every account with one client.
- **Self-hosted.** The service stores the credentials encrypted. Mail
goes straight from the provider to you, never through a third party's
cloud.