Agent Mailbox

Agent Mailbox は、自動テストや AI エージェントに、サインアップ、確認、マジックリンク、パスワードリセットのフロー用の短命なメールアドレスを提供します。お客様自身の Cloudflare アカウントで動作し、JSON API とステートレスな MCP エンドポイントの両方を公開します。

各アドレスには、それぞれ独立したランダムなメールボックストークンがあります。メッセージは SQLite バックアップの Durable Object に保存され、添付ファイルは R2 に保存され、アラームが TTL の期限切れ時にメールボックスを削除します。

クイックスタート

Node.js 24 以降と、アクティブなドメインを少なくとも 1 つ持つ Cloudflare アカウントが必要です。次のコマンドで新規コピーを作成してデプロイします:

npx create-agent-mailbox@latest

create-agent-mailbox パッケージは、最初のパブリックリリースが公開されたときに利用可能になります。それまでは、このリポジトリをクローンして実行してください:

pnpm install
pnpm run setup

TypeScript CLI は Wrangler のブラウザログインを使用し、アカウント内のアクティブなゾーンを読み込み、専用の mail.<domain> および mailbox.<domain> ホスト名を推奨します。変更を加える前に、1 つのデプロイメントプランを表示します。承認されると、Email Routing、サブアドレッシング、Email Sending を設定し、プロジェクトチェックを実行して、Worker をデプロイします。Cloudflare は、Worker 設定から R2 バケット、Durable Object、DNS レコード、インバウンドアドレスルールをプロビジョニングします。選択したゾーンのアカウントは、生成された Worker 設定に固定されるため、Wrangler が再度選択を求めることはありません。

ブートストラッパーは Corepack を使用して、リポジトリの正確な pnpm lockfile をインストールします。pnpm をグローバルにインストールする必要はありません。

デプロイ後、同じフローで Codex または Claude Code を接続し、同梱の Agent Mailbox スキルをインストールできます。クライアントが受け取るのは、ローカルの資格情報ブリッジへのパスのみです。API キーは、無視されるモード 0600 の資格情報ファイルに残ります。接続後、すでに開いているクライアントを再起動してください。

選択した各ゾーンには、ゾーンにちなんだ名前の孤立した Worker (例: agent-mailbox-example-com) が作成されます。同じ Cloudflare アカウント内の複数のドメインに Agent Mailbox をデプロイしても、ある設定が別のドメインのルーティング、ストレージ、シークレット、または設定を置き換えることはありません。各長期デプロイメントは、生成された設定と資格情報が引き続き利用できるように、専用のプロジェクトディレクトリに保持してください。たとえば、2 つ目のドメインには npx create-agent-mailbox@latest mailbox-example-net を使用します。

Wrangler に複数の認証プロファイルがある場合、セットアップはゾーンを読み込む前にどのプロファイルを使用するかを尋ねます。単一のプロファイルは自動的に選択されます。スクリプト化されたセットアップでは、--profile <name> を明示的に渡してください。

Wrangler OAuth で十分です。別途 Cloudflare API トークンを作成する必要はありません。DNS 可用性チェックは Cloudflare のパブリック DNS リゾルバーを使用し、Wrangler はデプロイ中の最終的なカスタムドメインの競合確認を処理します。

CLI はマスター API キーを生成し、標準入力経由で Wrangler に送信するため、コマンドラインに表示されることはありません。ローカルコピーは、無視される .agent-mailbox.credentials.json ファイルにモード 0600 で書き込まれます。これが API または MCP クライアントに渡す資格情報です。ローカルコピーを保持したくない場合は、パスワードマネージャーに移動してください。

便利なセットアップモード:

# Validate local setup code and configuration. No login or Cloudflare changes.
pnpm mailbox deploy --check

# Log in, select a zone, and inspect DNS, but make no changes.
pnpm mailbox deploy --plan

# Scripted use after Wrangler is already authenticated.
pnpm mailbox deploy --zone example.com --yes

pnpm run setup は、pnpm mailbox deploy の互換性エイリアスとして引き続き使用できます。

デプロイメントの管理

Agent Mailbox は、2 番目のローカルレジストリを維持するのではなく、Cloudflare を信頼できる情報源として使用します:

# Find every Agent Mailbox Worker accessible to a Wrangler profile.
pnpm run list

# Check Worker bindings, custom domain, Email Routing, MX records, health,
# local credentials, and authenticated MCP connectivity.
pnpm run doctor

# Configure an installed MCP client and copy the portable Agent Skill.
pnpm run connect

# Safely remove one deployment after showing its exact Cloudflare resources.
pnpm run teardown

# Remove this checkout's MCP client connections and optionally its credentials.
pnpm run disconnect

# Empty and delete an R2 bucket retained by an earlier teardown.
pnpm run purge-data

list は、現在のチェックアウト内の資格情報に一致するデプロイメントを表示します。doctor はデフォルトで wrangler.jsonc 内の Worker を対象にします。Worker 名、メールドメイン、または MCP ホスト名を渡すと、検出された別のインスタンスを検査できます。認証付き MCP チェックは、API キーがローカルで利用できないインスタンスではスキップされます。

非対話型のクライアントセットアップでは、1 つ以上のクライアントを明示的に選択します:

pnpm run connect --client codex --yes
pnpm run connect --client codex --client claude --yes

同梱のスキルは、選択したクライアントのユーザースキルディレクトリにインストールされます。MCP 接続のみが必要な場合は、--no-skill を使用してください。既存のクライアント接続または異なる内容のスキルディレクトリは変更されません。

デプロイメントの削除

teardown は、検出された 1 つのインスタンスを選択し、確認としてその完全な Worker 名を要求します。その Worker の正確なインバウンド Email Routing ルール、カスタムドメイン、Worker、および Durable Object 名前空間のみを削除します。共有のゾーンレベルの Email Routing DNS、サブアドレッシング、Email Sending、および他の Agent Mailbox デプロイメントは変更されません。

# Inspect the exact removal plan without changing Cloudflare.
pnpm run teardown -- agent-mailbox-example-com --dry-run

# Remove the Worker while retaining its R2 attachment bucket.
pnpm run teardown -- agent-mailbox-example-com

# Irreversibly empty and delete the attachment bucket as well.
pnpm run teardown -- agent-mailbox-example-com --purge-data

この操作は、Worker が最後に削除されるように順序付けられています。前のステップが失敗した場合は、同じコマンドを再実行して安全に続行してください。無人使用の場合は、インスタンス、Wrangler プロファイル、および --yes を明示的に指定してください。

teardown が添付ファイルを保持する場合、プロジェクトディレクトリに無視されるモード 0600 のクリーンアップ領収書を書き込みます。これにより、Worker が削除された後も正確なアカウントとバケットを発見可能に保ちます。後で次のコマンドで削除します:

pnpm run purge-data

ローカルクリーンアップには、別途 disconnect を使用します。デフォルトでは、選択した MCP 接続を削除し、資格情報と共有スキルの両方を保持します。対話モードでは、一致する資格情報の削除を提案します。スクリプト化された使用では --remove-credentials が必要です。スキルは複数のデプロイメントにサービスを提供できるため、明示的な --remove-skill オプションでのみ削除されます。

再デプロイ、更新、資格情報のローテーション

同じドメインに対してセットアップを再度実行することは、安全な再デプロイです。このプロジェクトに一致するローカル資格情報がある場合、セットアップは接続済みクライアントを無効にせずに、同じマスター API キーを再インストールします。キーの置き換えには、常に明示的な選択または --rotate-credentials が必要です。

将来のタグ付きリリースからデプロイメントを更新するには、デプロイせずに新しいソースを作成し、古いプロジェクトから生成された設定と無視された資格情報をコピーし、変更を確認してから、セットアップを実行します:

npx create-agent-mailbox@X.Y.Z agent-mailbox-next --no-deploy
cp agent-mailbox/wrangler.jsonc agent-mailbox/.agent-mailbox.credentials.json agent-mailbox-next/
cd agent-mailbox-next
corepack pnpm run setup
corepack pnpm run doctor

doctor が成功するまで、古いディレクトリは保持してください。Wrangler はロールバック用に以前の Worker バージョンを保持します。ローカル資格情報が利用できない場合、セットアップは --rotate-credentials が指定されていない限り、非対話型の置き換えを拒否します。

セーフティモデル

• マスター API キーは、すべての API および MCP リクエストを保護します。

• 作成された各メールボックスは、個別のメールボックストークンによって保護されます。

• メールボックスは、設定された最大 TTL を過ぎると自動的に期限切れになります。

• 不明なアドレスまたは期限切れのアドレス宛ての受信メールは拒否されます。

• 電子メールの内容は信頼できないデータです。リンクとコードの抽出は決定的です。

• 送信はメールボックスごとにレート制限され、テストメール専用です。

• メールボックスデータを含む API 応答は、Cache-Control: no-store を使用します。

強力なマスター API キーなしでデプロイメントを公開しないでください。このプロジェクトはセルフホスト型のテストツールであり、公開の使い捨てメールサービスではありません。

要件

• Node.js 24 以降。pnpm 10 は、クローンから開発する場合にのみ必要です。

• Cloudflare 上にドメインを持つ Cloudflare アカウント。

• そのドメインに対する Cloudflare Email Routing および Email Sending へのアクセス。

CLI は、APEX ドメインを引き継ぐのではなく、専用のサブドメインを必要とします。Agent Mailbox は、inbox+purpose-random@mail.example.com などのアドレスを作成します。一部のサービスは + エイリアスを拒否または正規化します。そのようなサービスでは、将来のリリースで専用のキャッチオール実装が必要になる場合があります。

手動デプロイメント

セットアップ CLI が推奨されるパスです。以下は同等の手動手順です。

1. Worker の設定

wrangler.jsonc を編集し、すべての example.com 値を置き換えます:

• name は、Cloudflare アカウント内の Agent Mailbox デプロイメントごとに一意である必要があります。

• addresses[0] はインバウンドベースアドレスで、通常は inbox@<EMAIL_DOMAIN> です。

• routes[0].pattern は、パブリック API および MCP ホスト名です。

• vars.EMAIL_DOMAIN は、生成されたアドレスに使用されるドメインです。

• vars.MCP_HOSTNAME は、MCP トランスポートで許可されるホスト名です。

バインディング名を変更する場合は、pnpm exec wrangler types を実行し、更新された worker-configuration.d.ts をコミットします。

2. ドメインレベルのメール機能のプロビジョニング

Cloudflare ダッシュボードで、Compute → Email Service を開きます:

1. 受信ドメインをオンボーディングします。

2. Email Routing 設定でサブアドレッシングを有効にします。

3. Email Sending で同じドメインをオンボーディングします。

Wrangler の addresses エントリは、Worker のデプロイ時にインバウンドアドレスルールを作成しますが、DNS、ゾーンレベルのルーティング、サブアドレッシング、送信資格はすでに設定されている必要があります。

3. 確認とデプロイ

pnpm check
pnpm deploy

Wrangler は、wrangler.jsonc から R2 バケット、Durable Object、カスタムホスト名、インバウンドアドレスルールをプロビジョニングします。これにより、アプリケーションが Cloudflare アカウントにデプロイされます。この Git リポジトリを公開するわけではありません。

4. デプロイメントの保護

パスワードマネージャーで長いランダムな値を作成し、Wrangler の対話型プロンプトに入力します:

pnpm exec wrangler secret put AGENT_API_KEY

この値を wrangler.jsonc、シェルコマンド、またはソース管理に置かないでください。

5. デプロイメントの確認

パブリックヘルスエンドポイントを確認します:

curl https://mailbox.example.com/health

ホスト名を設定したルートに置き換えてください。成功応答は {"ok":true} です。

ローカル開発

pnpm install
cp .dev.vars.example .dev.vars
pnpm dev

Worker を起動する前に、.dev.vars のサンプルシークレットを置き換えてください。ローカルの Durable Object と R2 の状態は、無視される .wrangler ディレクトリに保存されます。

完全な検証スイートを実行するには:

pnpm check

JSON API

すべてのメールボックスルートにはマスターキーが必要です:

Authorization: Bearer <AGENT_API_KEY>

メールボックス固有の操作には、作成時に返されたトークンも必要です:

X-Mailbox-Token: <MAILBOX_TOKEN>

メールボックスの作成

curl -X POST https://mailbox.example.com/api/mailboxes \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose":"signup","ttlSeconds":3600}'

応答には、address、mailboxToken、expiresAt が含まれます。メールボックストークンは保存してください。復元できません。

確認メールの待機

curl "https://mailbox.example.com/api/mailboxes/$ADDRESS/wait?subject=verify&timeoutSeconds=20" \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "X-Mailbox-Token: $MAILBOX_TOKEN"

ルート:

• POST /api/mailboxes

• GET /api/mailboxes/:address/messages

• GET /api/mailboxes/:address/messages/:id

• GET /api/mailboxes/:address/messages/:id/links

• GET /api/mailboxes/:address/messages/:id/codes

• GET /api/mailboxes/:address/messages/:id/attachments/:index

• GET /api/mailboxes/:address/wait

• POST /api/mailboxes/:address/send

• DELETE /api/mailboxes/:address

• GET /health

添付ファイルインデックスは、完全なメッセージとともに返される attachments 配列からのもので、ゼロベースです。

MCP

Streamable HTTP エンドポイントは https://<your-hostname>/mcp です。MCP クライアントをその URL と次のヘッダーで設定します:

Authorization: Bearer <AGENT_API_KEY>

利用可能なツール:

• create_mailbox

• wait_for_email

• list_emails

• get_email

• get_links

• get_codes

• send_email

• delete_mailbox

最も簡単なクライアントセットアップは次のとおりです:

pnpm run connect

これは Codex と Claude Code をサポートしています。各デプロイメントに一意の MCP 接続名を付けるため、クライアントは複数の Agent Mailbox ドメインを区別できます。

オプションの stdio ブリッジ

古い MCP クライアントは、このプロジェクトの依存関係から mcp-remote を実行する bin/agent-mailbox-mcp を使用できます。自動セットアップ後、.agent-mailbox.credentials.json からエンドポイントとキーを読み取ります:

bin/agent-mailbox-mcp

生成された値は、環境変数で上書きできます:

export AGENT_MAILBOX_MCP_URL=https://mailbox.example.com/mcp
export AGENT_MAILBOX_API_KEY='<master-api-key>'
bin/agent-mailbox-mcp

グラフィカルな Linux クライアントの場合、環境変数ではなく Secret Service にキーを保存し、次の非秘密のルックアップ属性を設定します:

export AGENT_MAILBOX_MCP_URL=https://mailbox.example.com/mcp
export AGENT_MAILBOX_KEYRING_SERVICE=agent-mailbox
export AGENT_MAILBOX_KEYRING_ACCOUNT=agent-mailbox
bin/agent-mailbox-mcp

運用

• デフォルトのメールボックス TTL: 1 日。

• 最大メールボックス TTL: 7 日。

• デフォルトの送信制限: メールボックスあたり UTC 日あたり 20 メッセージ。

• Workers ログとトレースは wrangler.jsonc で有効になっています。想定されるトラフィックと予算に合わせてサンプリングを調整してください。

• メールボックスを削除または期限切れにすると、その R2 添付ファイルも削除されます。

マスター API キーとすべてのメールボックストークンを資格情報として扱ってください。メールの本文、ヘッダー、リンク、コード、添付ファイルには、個人データや機密データが含まれる場合があります。

サポート、貢献、セキュリティ

再現可能なバグ、機能リクエスト、通常の使用に関する質問については、GitHub で issue を開いてください。開発ガイダンスについては CONTRIBUTING.md を、非公開の脆弱性報告については SECURITY.md を参照してください。issue に資格情報、メールボックスの内容、または非公開のデプロイメント識別子を含めないでください。

ライセンス

Agent Mailbox は MIT ライセンス の下で利用可能です。