psyb0t/mailbox repository overview

Source⁠ | Project page⁠

⁠mailbox

Read, organize, draft and send mail across multiple IMAP/SMTP accounts through one HTTP API and an MCP endpoint at /mcp, on the same port. Each bearer token controls which operations and mailboxes a client can access.

For agent access, configure tokens with explicit permissions:

• Scoped tokens. A token that holds read, draft and organize cannot send or permanently delete. Over MCP it does not even see the send tools or the permanent flag.
• Deletion defaults to Trash. Deleting moves a message to Trash. Permanent erasure needs the delete scope and only works from the Trash folder. The service never issues a folder-wide EXPUNGE.
• Drafts in two steps. An agent can prepare a reply; a human (or a token with send) sends it.
• Send guard. Hourly rate limit, dry-run mode, and a sender address authorized by your configured exact identities or opt-in domain patterns.
• Message analysis. Inspect SPF/DKIM/DMARC verdicts, header mismatches, hidden text and deceptive links. Verdicts are trusted only when the receiving server matches your configuration. Request sanitized HTML when needed.
• Audit log. Writes are recorded, including those refused for a missing scope or rejected by the mail server. Message bodies never are.

Mail bodies and drafts stay on IMAP. A shared SQLite database stores audit records, send counters, checkpoints, draft send claims and webhook delivery metadata. API requests close their mail-server connections after use; the watcher keeps an IMAP connection open for notifications.

The service uses Python's imaplib and smtplib, FastAPI, the official MCP Python SDK and nh3 for HTML sanitizing. Dependency updates enforce a seven-day release-age cutoff through uv's exclude-newer setting.

⁠Contents

• Quick start⁠
• Capabilities⁠
• Documentation⁠
• Development⁠
• Sponsor⁠
• License⁠

⁠Quick start

1. Copy config.example.yaml to config.yaml and .env.example to .env. Configure your accounts and replace every placeholder in .env with its password or a fresh token from openssl rand -hex 32. Restrict both files with chmod 600.
2. Start the container. The named volume preserves operational state across restarts:

docker run --rm \
  -p 127.0.0.1:8000:8000 \
  --env-file .env \
  -v "$PWD/config.yaml:/etc/mailboxd/config.yaml:ro" \
  -v mailboxd-state:/var/lib/mailboxd \
  psyb0t/mailbox:latest

1. Check health and list mail:

TOKEN="paste-the-token-here"

# Health is always open, no token needed.
curl -s http://localhost:8000/health | jq

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/mailboxes | jq

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  'http://localhost:8000/inbox?limit=5' | jq

⁠Docker Compose

The checked-in docker-compose.yml publishes on 127.0.0.1:${PORT:-8000}, mounts ./config.yaml (or $MAILBOXD_CONFIG) read-only and creates the mailboxd-state volume:

services:
  mailboxd:
    image: psyb0t/mailbox:latest
    ports: ["127.0.0.1:8000:8000"]
    volumes:
      # Keep config.yaml out of Git and restrict access to its credentials.
      - ./config.yaml:/etc/mailboxd/config.yaml:ro
      - mailboxd-state:/var/lib/mailboxd
volumes:
  mailboxd-state:

The optional webhook watcher is a second service in the same file, off by default: docker compose --profile watch up -d.

⁠Capabilities

Mount /var/lib/mailboxd for persistent operational state. HTTP workers and the optional watcher share one SQLite database on a local filesystem. Read the upgrade notes⁠ before replacing a stateless deployment.

⁠Documentation

The full documentation lives at psyb0t.github.io/docker-mailbox⁠.

⁠Development

make lint           # flake8 and mypy
make test-coverage  # full suite, production container and coverage floor
make audit          # frozen runtime and dev dependency advisories
make build          # production image
make help           # all available targets

All project tools run inside the development image. Tests use socket-level IMAP/SMTP fixtures, a local HTTP receiver, real SQLite files and a production-container smoke test. See development⁠ for details.

⁠Sponsor

⁠License

WTFPL. See LICENSE⁠ and third-party components⁠.