benethos-mailbox-service

Pre-alpha, version 0.1.0. Not ready for production use: the API, the stored data and the configuration may change without notice.

The 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. Scripts, apps and the MCP server benethos-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 its token
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 prints an API token once. Use it to sign in to the UI, and send it as Authorization: Bearer <token> to the API.
• serve listens on http://127.0.0.1:8080:
  • /ui: the configuration UI (sign in with the token)
  • /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. Microsoft accounts sign in with OAuth and need an app registration first: docs/microsoft.md.

Where things live

The service works from the folder it is started in:

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

Settings

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. With --recovery-key it reads the recovery key from stdin, for a new machine.

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. Give each script and each assistant its own user with only the rights it needs. With neither a user nor MAILBOX_SERVICE_KEY, the API answers 503 setup_required.

Container

The image ghcr.io/benethos-hub/benethos-mailbox-service runs as an unprivileged user 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.1.0), the minor version (0.1) and latest.

With docker run

IMAGE=ghcr.io/benethos-hub/benethos-mailbox-service:0.1.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

The repository's containers/compose.yaml runs the service. With the profile mcp it also runs the MCP server over HTTP. Both listen on 127.0.0.1 only. From the folder that holds the file:

export MAILBOX_SERVICE_IMAGE=ghcr.io/benethos-hub/benethos-mailbox-service:0.1.0

mkdir -p secrets
docker run --rm "$MAILBOX_SERVICE_IMAGE" keys generate > secrets/master_key
chmod 400 secrets/master_key
sudo chown 10001 secrets/master_key          # Linux: the container user reads it

docker compose run --rm mailbox-service keys init
docker compose run --rm mailbox-service users create-admin
docker compose up -d
curl http://127.0.0.1:8080/health

Without MAILBOX_SERVICE_IMAGE, compose builds the image from a clone of the repository. Settings go into the environment of the service in the compose file.

Operation:

docker compose logs -f mailbox-service
docker compose pull && docker compose up -d                        # update
docker compose exec mailbox-service benethos-mailbox-service backup /data/backup.mbx
docker compose cp mailbox-service:/data/backup.mbx .

# restore, into a stopped service
docker compose stop mailbox-service
docker compose cp backup.mbx mailbox-service:/data/backup.mbx
docker compose run --rm mailbox-service restore /data/backup.mbx
docker compose up -d

Beyond your own machine, put a TLS reverse proxy in front and set MAILBOX_SERVICE_PUBLIC_URL to the address it serves.