mailbox-service

Beta, version 0.4.0. 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.

The service of Mailbox, on PyPI as benethos-mailbox-service: one REST API (OpenAPI 3.1) for several mail providers and accounts, with a configuration UI in the browser. It runs permanently, holds the connections to the accounts, keeps their credentials encrypted and syncs in the background. It keeps a feed of what changed in the mailboxes and posts it to webhooks. Scripts and apps, through the Python client mailbox-client, and the MCP server mailbox-mcp reach mail only through it, each with a token of its own.

What the project is for: the repository's README.

Install

From PyPI, with uv or pip:

uv tool install benethos-mailbox-service      # or: pipx install benethos-mailbox-service
benethos-mailbox-service --version

uvx benethos-mailbox-service ... runs it without installing. In a clone of the repository, every command below also works as uv run benethos-mailbox-service ....

The container image is ghcr.io/benethos-hub/benethos-mailbox-service. See Container.

First start

benethos-mailbox-service keys init              # once: the keys; prints the recovery key
benethos-mailbox-service users create-admin     # once: a user with every right; prints a one-time password
benethos-mailbox-service serve

• keys init creates the master key in the operating system's credential store and the data key in the database. It prints a recovery key once. Keep it apart from the machine and its backups. Without it, a database cannot be opened on another machine.
• users create-admin creates the user admin and prints a one-time password once. Sign in to the UI with it. The UI then asks for a password of your own, 15 characters at least. Tokens for the API are made in the UI, on a user's page.
• Further users are API users unless their UI sign-in is switched on: they work with tokens only, e.g. a script or an MCP server.
• A forgotten password: users set-password <name> on the host gives that user a new one-time password, and switches its UI sign-in on.
• Both write the secret alone to standard output and everything else to standard error, so it can be piped straight into a password manager. Printed to a terminal, it stays in its scrollback, and in a container or CI job, in the log of that run. Clear these afterwards.
• A lost second factor without a recovery code: users reset-second-factor <name> on the host removes it (AUTHENTICATION.md).
• serve listens on http://127.0.0.1:8080:
  • /ui: the configuration UI (sign in with the user name and password)
  • /docs: the interactive API documentation
  • /health: open, for health checks

Then connect accounts in the UI (Accounts, Connect an account) or with POST /v1/accounts. An IMAP account needs its address and an app password. The service looks up the servers from the address. A JMAP account, at Fastmail, Stalwart or any JMAP server, signs in with an API token or a password and sends through JMAP. A POP3 account, for a mailbox without IMAP, works the same way: the inbox only, without folders, read state or search. Microsoft accounts sign in with OAuth, in the browser or with a code, through the project's app or one of your own. Away from localhost the project's app signs in with a code only. For the browser there, register an app of your own: docs/MICROSOFT.md. Gmail accounts sign in with Google in the browser, through a Google client of your own, or connect over IMAP with an app password: docs/GOOGLE.md.

Where things live

Installed with pip or uv tool, the service keeps its settings and data in the folders of the operating system for the user:

Started in a folder that has config/benethos-mailbox-service/ or data/benethos-mailbox-service/, as the repository does, it works from there instead, as before. The command names what applies, never a value of the settings:

benethos-mailbox-service paths

The keyring is the default and the safest place. A key file is for a server without one, or a container. It never lies in the data folder, which a backup or a copy takes along. The service refuses it there. paths suggests master.key in the settings folder.

A template for the settings file with every option: config/benethos-mailbox-service/.env.example.

To keep the settings somewhere else, name the file. Every command takes --env-file PATH, before or after the command, or reads MAILBOX_SERVICE_ENV_FILE:

benethos-mailbox-service --env-file /etc/mailbox/service.env users create-admin
benethos-mailbox-service serve --env-file /etc/mailbox/service.env

A file named this way must exist. A relative path in the settings then counts from its folder, not from the folder the service is started in: MAILBOX_SERVICE_DATA_DIR=data puts the database in /etc/mailbox/data/. So every command finds the same data wherever it is started. serve names the settings file it read and the database at start.

Settings

Logs

serve writes one log to stderr: the terminal, docker compose logs, or the journal under systemd. There is no log file: whoever runs the service keeps the log and bounds it. The compose file keeps 5 files of 10 MB per container, the journal follows its own limits. Each line has the time, the level, where it comes from and the message. The time is the same in every line, on the log page and in the MCP server's log: ISO 8601, the local time of the machine, to the millisecond, with its offset from UTC.

2026-09-28T10:14:03.412+02:00 INFO     benethos_mailbox_service.activity.auth.signed_in: admin (usr_...) signed in to the UI from 127.0.0.1
2026-09-28T10:14:03.418+02:00 INFO     uvicorn.access: 127.0.0.1:52344 - "POST /ui/login HTTP/1.1" 303

At a terminal the lines are shorter and in colour: the time dim, the level in colour, the source without the package name (http for the access log), and a request as method, path and status with its name:

2026-09-28T10:14:03.412+02:00 INFO     activity.auth.signed_in          admin (usr_...) signed in to the UI from 127.0.0.1
2026-09-28T10:14:03.418+02:00 INFO     http                             POST /ui/login 303 See Other 127.0.0.1:52344

NO_COLOR set to any value keeps the plain lines at a terminal too.

MAILBOX_SERVICE_LOG_LEVEL sets the level of the service and of uvicorn. Libraries write from warning on at any level, so debug shows the service without the commands a library sends to a mail server. What people and the service do is one sentence per activity under activity.<area>.<name>, such as activity.users.token_revoked: who, what, to which record, from which address, and why. Sign-ins, users, roles, tokens, accounts, webhooks, sends, and each limit when it engages. docs/LOGGING.md lists them by name. A level for one name alone quiets it. The log page names the source as the console does, without the package's name. A request is logged by its path, without its query. A mail's content, its recipients and search terms are never written. A password, token or secret the service holds is written as ***, should a message or a traceback carry one.

Commands

A backup holds accounts, users, rights, token hashes and the encrypted credentials, never mail. It is encrypted as a whole and opens only with the master key or the recovery key, which are not in it. restore keeps the previous database beside the restored one. It refuses while a service runs on the database: a running service holds the lock file mailbox.db.lock beside it. With --recovery-key it asks for the recovery key, at a hidden prompt or from stdin when piped, for a new machine. When the key provider holds another master key there, restore refuses: the database kept beside the restored one opens with that key alone. Note its recovery key, then pass --replace-master-key.

Users, rights and tokens

Every route under /v1 needs Authorization: Bearer <token>. Only /health is open. A token belongs to a user. The user's grants decide what it may do, per account and per operation: for example read mail, write drafts, send, manage accounts. Grants can limit sending to certain recipients and to a number of mails per day. Every send is recorded in an audit. GET /v1/me shows what a token may do.

Users, roles and tokens are managed in the UI (Users, Roles) or under /v1/users and /v1/roles. A token is shown once, when it is created, and so is a one-time password from POST /v1/users/{user_id}/password. Give each script and each assistant its own user with only the rights it needs. Until users create-admin has made the first user, the API answers 503 setup_required. Every call is made by a user, so the audit names one.

Changes and webhooks

GET /v1/changes names each message created, updated or deleted since the state of an earlier answer, across the accounts the token may read. GET /v1/accounts/{account_id}/changes does the same for one account. Both need mail.read. A state older than MAILBOX_SERVICE_CHANGES_DAYS answers 410 changes_expired, and the client starts again without since.

POST /v1/webhooks registers a URL, with the right webhooks.manage. The service posts the events there as JSON, signed in X-Mailbox-Signature, and tries a failed post again as the MAILBOX_SERVICE_WEBHOOK_* settings say. The signing secret is in the answer to POST, the only time it is shown. A host in the local network is allowed. The format of a post is in CONCEPT.md, section 6.5.

Container

The image ghcr.io/benethos-hub/benethos-mailbox-service runs as an unprivileged user, and the commands below run it on a read-only root file system. It takes its settings from the environment only and sets MAILBOX_SERVICE_HOST=0.0.0.0, MAILBOX_SERVICE_DATA_DIR=/data, MAILBOX_SERVICE_KEY_PROVIDER=file and MAILBOX_SERVICE_KEY_FILE=/run/secrets/master_key. The database lives in the volume at /data. The master key is a file mounted at /run/secrets/master_key. Tags: the version (0.4.0), the minor version (0.4) and latest.

With docker run

IMAGE=ghcr.io/benethos-hub/benethos-mailbox-service:0.4.0

# once: a master key file, the keys in the database, the first user
docker run --rm "$IMAGE" keys generate > master_key
chmod 400 master_key
sudo chown 10001 master_key  # Linux: the container user (uid 10001) reads it
docker volume create mailbox-data
docker run --rm -v mailbox-data:/data -v "$PWD/master_key:/run/secrets/master_key:ro" "$IMAGE" keys init
docker run --rm -v mailbox-data:/data -v "$PWD/master_key:/run/secrets/master_key:ro" "$IMAGE" users create-admin

# the service, on the loopback address of the host only
docker run -d --name mailbox-service --restart unless-stopped \
  -p 127.0.0.1:8080:8080 --read-only --tmpfs /tmp \
  -v mailbox-data:/data -v "$PWD/master_key:/run/secrets/master_key:ro" \
  "$IMAGE"

The file master_key holds the recovery key. Whoever has it and a backup has the credentials. Keep a copy apart from the host.

With compose

containers/production/ runs the published images with compose, without a clone of the repository: the service, and with the profile https Caddy in front with a certificate from Let's Encrypt, from its own CA or of your own. The service listens on 127.0.0.1 only. Each client has an MCP server of its own, with its own token: started by the client, or as an instance beside the service with the profile mcp. setup.sh there does the first start in one run:

sh setup.sh

The version runs as named in its .env, MAILBOX_VERSION=0.4.0. Its README has the same steps by hand, the update, backup and restore, HTTPS with Caddy or a proxy of your own, and the MCP server instances.