Mailbox

mailbox

複数の IMAP/SMTP アカウントのメールを、単一の HTTP API と同じポート上の /mcp にある MCP エンドポイント経由で、閲覧、整理、下書きの作成、送信ができます。各ベアラートークンによって、クライアントがアクセスできる操作とメールボックスが制御されます。

エージェントからアクセスする場合は、明示的な権限を持つトークンを設定してください。

• スコープ付きトークン。 read、draft、organize を持つトークンでは、送信も削除もできず、それらのツールは表示されません。
• 削除すると、デフォルトでゴミ箱に移動します。 メッセージを削除すると、ゴミ箱に移動します。完全に消去するには delete スコープが必要で、ゴミ箱フォルダーからのみ実行できます。このサービスがフォルダー全体に対して EXPUNGE を発行することはありません。
• 下書きは2段階で作成します。 エージェントが返信を準備し、人間（または send 権限を持つトークン）が送信します。
• 送信ガード。 1時間あたりのレート制限、ドライランモード、設定済みの完全一致する ID またはオプトインのドメインパターンによって認可された送信者アドレスを使用します。
• メッセージ分析。 SPF/DKIM/DMARC の判定、ヘッダーの不一致、隠しテキスト、偽装リンクを調べます。判定を信頼するのは、受信サーバーが設定と一致する場合に限られます。必要に応じてサニタイズ済み HTML をリクエストできます。
• 監査ログ。 すべての書き込みと、拒否されたすべての書き込みを記録します（メッセージ本文は記録しません）。

メール本文と下書きは IMAP 上に保持されます。共有 SQLite データベースには、監査記録、送信カウンター、チェックポイント、下書き送信要求の記録、Webhook 配信メタデータが保存されます。API リクエストは使用後にメールサーバーへの接続を閉じます。通知を受け取るため、ウォッチャーは IMAP 接続を開いたままにします。

このサービスでは、Python の imaplib と smtplib、FastAPI、公式の MCP Python SDK、HTML のサニタイズに nh3 を使用します。依存関係の更新では、uv の exclude-newer 設定により、リリースから7日間の猶予期間を設けています。

目次

• クイックスタート
• 設定
• HTTP API、MCP、安全性、Webhook
• エージェントとの連携
• アーキテクチャと開発
• 運用、バックアップ、移行

クイックスタート

1. config.example.yaml を config.yaml に、.env.example を .env にコピーします。アカウントを設定し、.env のすべてのプレースホルダーをパスワード、または openssl rand -hex 32 で生成した新しいトークンに置き換えます。両方のファイルのアクセス権を chmod 600 で制限します。
2. コンテナーを起動します。名前付きボリュームにより、再起動後も運用状態が保持されます。

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

3. ヘルス状態を確認し、メールを一覧表示します。

TOKEN="paste-the-token-here"

curl -s http://localhost:8000/health | jq                                               # health is always open
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

リポジトリに含まれる docker-compose.yml は、127.0.0.1:${PORT:-8000} で公開し、./config.yaml（または $MAILBOXD_CONFIG）を読み取り専用でマウントし、mailboxd-state ボリュームを作成します。

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:

オプションの Webhook ウォッチャーは、同じファイル内の2つ目のサービスとして用意されており、デフォルトでは無効です。docker compose --profile watch up -d で起動できます。

機能

領域	操作
閲覧	統合受信トレイ、構造化検索、ソースの生データ、ヘッダー、添付ファイル、スレッド
整理	既読フラグ、ラベル、移動、メールボックスの作成、ゴミ箱
送信	設定済みの ID、署名、返信、IMAP の下書き、送信済みメールのコピー
アクセス	REST と MCP で共有される、トークンごとのスコープとメールボックスの許可リスト
運用	SQLite 監査記録、共有送信制限、チェックポイント、永続的な署名付き Webhook

永続的な運用状態を保存するには、/var/lib/mailboxd をマウントします。HTTP ワーカーとオプションのウォッチャーは、ローカルファイルシステム上の1つの SQLite データベースを共有します。ステートレスなデプロイを置き換える前に、移行に関する注意事項をお読みください。

開発

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

すべてのプロジェクトツールは開発イメージ内で実行されます。テストでは、ソケットレベルのIMAP／SMTPフィクスチャー、ローカルHTTPレシーバー、実際のSQLiteファイル、本番コンテナーのスモークテストを使用します。詳細は開発をご覧ください。

ライセンス

WTFPL。LICENSEとサードパーティコンポーネントをご覧ください。