Sendmux Email Inbox Api + Sending

Sendmux によるメール受信トレイ API とメール送信

AI エージェント向けのメール受信トレイ API、受信メール、送信メールに対応した MCP および A2A サーバーです。Sendmux を通じて、メールの受信、クリーンな JSON パース、ウェブフック、複数プロバイダーへのルーティングを提供します。

このパッケージは Sendmux MCP です。ドキュメントツールで使用するドキュメント検索 MCP とは分けてください。

ドキュメント

• Sendmux ドキュメント：sendmux.ai/docs
• 管理 API リファレンス：sendmux.ai/docs/api/introduction
• メールボックス API リファレンス：sendmux.ai/docs/mailbox-api/introduction
• 送信 API リファレンス：sendmux.ai/docs/sending-api/introduction
• ソースリポジトリ：Sendmux/sendmux-sdk

要件

• Python 3.10 以降。
• 送信ツールには、送信可能な smx_mbx_* キー、またはオーナーが承認した送信リソースの smx_agent_* トークンが必要です。
• メールボックスツールには、メールボックススコープの smx_mbx_* キー、またはスコープを設定した smx_agent_* トークンが必要です。
• 管理ツールには、ルート smx_root_* キーが必要です。

2.0.0 へのアップグレード

バージョン 2.0.0 では、MCP 添付ファイルツールからローカルの file_path とルート入力が削除されました。セルフマネージドのパッケージまたはサーバーをアップグレードする前に、以前の正常動作が確認されているパッケージ環境、依存関係の状態、MCP クライアントとツールの設定を保持してください。添付ファイルを呼び出す箇所をエージェント向け添付ファイルワークフローを使うよう更新してから、ツールの検出と、エージェントが使用する各添付ファイルワークフローを確認してください。

セルフマネージドのインストールをロールバックするには、保持しておいたパッケージ環境、依存関係の状態、MCP クライアントとツールの設定をまとめて復元してください。エージェントを再開する前に、ツールの検出と該当する添付ファイルワークフローを確認してください。パッケージのロールバックでは、すでに完了したアップロードや送信は取り消されません。

Sendmux のホスト型エンドポイントを使用するクライアントの場合、ローカルの pip 環境を変更してもデプロイ済みサーバーのバージョンは変わりません。ホスト型デプロイのロールバックは、オペレーターが別途リリース操作を行い、ホスト型エンドポイントに対して確認する必要があります。

インストール

pip install sendmux-mcp

使用方法

サーフェスごとのコマンドを使って、単一のローカルサーバーを実行します。

SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-mailbox
SENDMUX_API_KEY=smx_root_... sendmux-mcp-management
SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-sending

sendmux-mcp を使って、統合ローカルサーバーを実行します。

SENDMUX_MCP_SURFACES=mailbox,sending \
SENDMUX_MAILBOX_API_KEY=smx_mbx_... \
SENDMUX_SENDING_API_KEY=smx_mbx_... \
sendmux-mcp

両方の種類のキーがある場合は、3 つすべてのローカルサーフェスを実行します。

SENDMUX_MCP_SURFACES=mailbox,management,sending \
SENDMUX_MAILBOX_API_KEY=smx_mbx_... \
SENDMUX_MANAGEMENT_API_KEY=smx_root_... \
SENDMUX_SENDING_API_KEY=smx_mbx_... \
sendmux-mcp

汎用の sendmux-mcp コマンドでは、--surface または --surfaces も指定できます。ラッパーコマンドはサーフェスを 1 つだけ選択します。

トランスポート

stdio は、ローカルのエージェントクライアントで使用されるデフォルトのトランスポートです。

SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-mailbox --transport stdio

http と streamable-http は、HTTP 経由で MCP エンドポイントを公開します。HTTP モードのデフォルトは 127.0.0.1:8765/mcp で、明示的に無効化しない限り、別途 MCP ベアラートークンが必要です。

SENDMUX_API_KEY=smx_mbx_... \
SENDMUX_MCP_HTTP_BEARER_TOKEN=local-mcp-token \
sendmux-mcp-mailbox --transport http --host 127.0.0.1 --port 8765 --path /mcp

/health は、選択したサーフェスの簡易な JSON ヘルスレスポンスを返します。

ホスト型エンドポイント

公開ホスト型 MCP エンドポイントは https://mcp.sendmux.ai/mcp です。

ホスト型クライアントでは、OAuth を使用する HTTP トランスポートを使ってください。クライアントが明示的に必要とする場合を除き、手動の Authorization ヘッダー、API キー、カスタム OAuth エンドポイント、カスタムスコープは追加しないでください。

登録時または認証時に要求スコープを指定しないホスト型 OAuth クライアントにも対応しています。サーバーはディスカバリーおよびベアラーチャレンジを通じて、ホスト型スコープセットを通知します。

パッケージに含まれる sendmux-mcp-hosted コマンドは、ホスト型サーバーランタイムを実行します。ローカルおよびプライベートのデプロイでは、OAuth 対応の互換性があるホスト型環境を運用している場合を除き、上記のローカルコマンドを使用してください。

ホスト型 A2A エンドポイント

同じホスト型ランタイムは、https://a2a.sendmux.ai/a2a/v1 で HTTP+JSON を使用した決定論的な A2A 1.0 も公開しています。https://a2a.sendmux.ai/.well-known/agent-card.json から検出できます。OAuth リソースメタデータは https://a2a.sendmux.ai/.well-known/oauth-protected-resource にあります。

A2A の message:send オペレーションには、JSON DataPart をちょうど 1 つ送信してください。そのデータで、厳選された Sendmux オペレーションを選択し、そのオペレーションへの入力を指定します。

{
  "operationId": "managementListDomains",
  "pathParameters": {},
  "query": { "limit": 10 },
  "headers": {},
  "body": null,
  "mailboxId": null
}

operationId には、ホスト型 MCP サービスと同じ厳選されたオペレーション ID を使用します。OAuth の許可は A2A リソースに紐づけられ、Sendmux のサーフェスと権限の制限を維持します。サービスは、上流のステータス、安全なレスポンスヘッダー、JSON ボディ（JSON 以外のレスポンスの場合は bodyBase64）を含む JSON DataPart を 1 つ返します。

A2A エンドポイントは即時実行型でステートレスです。ストリーミング、プッシュ通知、永続タスク、タスクのキャンセルは公開もルーティングもされません。

設定

設定	環境変数	デフォルト
ツールサーフェス	SENDMUX_MCP_SURFACES	sendmux-mcp では必須です。ラッパーコマンドは 1 つのサーフェスを選択します
API キーのフォールバック	SENDMUX_API_KEY	互換性のある単一キー構成で使用できます
メールボックス API キー	SENDMUX_MAILBOX_API_KEY	互換性のあるフォールバックがない場合、メールボックスを選択すると必須です
管理 API キー	SENDMUX_MANAGEMENT_API_KEY	互換性のあるフォールバックがない場合、管理を選択すると必須です
送信 API キー	SENDMUX_SENDING_API_KEY	送信を選択した場合に必須です。ただし、フォールバックキーが送信可能な smx_mbx_* キー、または所有者が承認した Sending リソースの smx_agent_* トークンである場合を除きます
アプリ API ベース URL	SENDMUX_APP_BASE_URL	https://app.sendmux.ai/api/v1
送信 API ベース URL	SENDMUX_SENDING_BASE_URL	https://smtp.sendmux.ai/api/v1
トランスポート	SENDMUX_MCP_TRANSPORT	stdio
HTTP ホスト	SENDMUX_MCP_HOST	127.0.0.1
HTTP ポート	SENDMUX_MCP_PORT	8765
HTTP パス	SENDMUX_MCP_PATH	/mcp
HTTP ベアラートークン	SENDMUX_MCP_HTTP_BEARER_TOKEN	オプトアウトを有効にしない限り、HTTP では必須です
認証なしの HTTP を許可	SENDMUX_MCP_ALLOW_UNAUTHENTICATED_HTTP	false
許可するブラウザーオリジン	SENDMUX_MCP_ALLOWED_ORIGINS	ブラウザーオリジンなし
スナップショットディレクトリの上書き	SENDMUX_MCP_OPENAPI_INPUT_DIR または OPENAPI_INPUT_DIR	パッケージに含まれるスナップショット
アプリのスナップショットの上書き	SENDMUX_MCP_APP_OPENAPI	パッケージに含まれるアプリのスナップショット
送信スナップショットの上書き	SENDMUX_MCP_SENDING_OPENAPI	パッケージに含まれる送信スナップショット
リクエストタイムアウト	SENDMUX_MCP_TIMEOUT_SECONDS	30
リトライ回数	SENDMUX_MCP_RETRY_MAX_ATTEMPTS	3
リトライ時間の上限（秒）	SENDMUX_MCP_RETRY_MAX_ELAPSED_SECONDS	未設定

リトライでは Retry-After と X-RateLimit-Reset を尊重し、ローカルのバックオフ上限は適用されません。また、retryable: false の場合はリトライを停止します。任意のリトライ時間上限を設定するには、RetryConfig(max_elapsed_seconds=30)、上記の環境変数、または --retry-max-elapsed-seconds 30 を使用してください。残りの時間上限を超えるリトライでは、元のエラーが返されます。実行中のリクエストには通常の HTTP タイムアウトが適用されます。

リリース済みのツール名、スキーマ、説明を安定させるため、デフォルトではパッケージに含まれる OpenAPI スナップショットが使われます。開発、カナリア、デバッグの実行では、パス、ディレクトリ、URL による上書きを使用できます。

ツールの種類

• Mailbox：許可されたメールボックス、プロファイル／セッションの検出、メッセージ、添付ファイル、指定範囲内でのメッセージ待機、スレッド、フォルダー、検索、件数、メールボックスからの送信を行うツールです。smx_mbx_* キー、またはスコープが設定された smx_agent_* トークンが必要です。エージェントトークンはサーバー側のスコープによる制限を受けます。claim 前に自己登録したエージェントトークンには email.send が含まれません。
• Management：ドメイン、メールボックス、ログ、メトリクス、支出の概要、ウェブフックを管理するツールです。smx_root_* キーが必要です。
• Sending：添付ファイルのアップロード参照、単一送信、バッチ送信を行うツールです。smx_mbx_* キー、または所有者が承認した Sending リソースの smx_agent_* トークンが必要です。

サーバーは、キーのプレフィックスが誤っている場合、起動前に拒否します。

パッケージの契約（メンテナー向け）

ソースチェックアウトには、実際のサーバーファクトリーの公開ツール検出から生成された sendmux_mcp/mcp-contract.json が含まれています。別のカタログを管理する代わりに、その tools.by_surface エントリーと tools.count を使用してください。各エントリーには、ツールの説明、入力／出力スキーマ、アノテーションが保持されています。この契約には、ホストされたリソース、ローカルトランスポート、API オリジン、認定済みプロトコルリビジョン、生成時に使用されたランタイムバージョンも記録されています。

契約を含むビルドをインストールした後は、認証情報やネットワークリクエストを使わずに読み込めます。

from sendmux_mcp.contract import load_contract

contract = load_contract()
print(contract["package"])

結果には、インストールされているディストリビューションとバージョンが示されます。load_contract() は、ソース／バージョンの証拠が古い場合、固定された FastMCP ランタイムと一致しない場合、または認定済みリビジョンがサポート対象外の場合に ValueError を発生させます。記録された間接的な MCP バージョンは来歴情報であり、依存関係の制約を狭めるものではありません。このアーティファクトを読み込んでも、新たに解決された依存関係のバージョンが認定されるわけではなく、デプロイ済みのサービスがこのビルドと一致することが証明されるわけでもありません。

uploads では、ローカルで適用されるインラインおよび Mailbox のバイト数上限と、Sending が返す max_size_bytes による上限が区別されています。Sending の presign リクエストスキーマには数値上限が設定されていません。過去のソース定数ではなく、アップロードインテントのレスポンスを使用してください。URL の有効期限と添付ファイルの物理的な保持期間は同じではなく、このアーティファクトはストレージのクリーンアップを認定しません。

リポジトリのルートから pnpm generate:mcp を実行すると、ネイティブの編集可能メタデータが更新され、決定的な契約バイト列が書き込まれます。その環境を準備した状態で pnpm exec .tmp/python-venv/bin/python -m sendmux_mcp.contract --check を実行すると、書き換えを行わずに最新状態かどうかを確認できます。pnpm build:mcp は、テスト、wheel／sdist への収録、インストール後の利用、固定された適合性チェックを検証します。チェックアウトでの変更は、リリースが公開されるまで pip install では利用できません。

エージェント向け添付ファイルのワークフロー

ユーザーがエージェントに新着メールを待つよう依頼した場合は、mailbox_wait_for_message を使用してください。このツールの実行時間には上限があります。matched=false が返された場合は、MCP ツールの呼び出しを無期限に開いたままにするのではなく、再度呼び出してください。

メッセージに添付ファイルがある場合：

1. 添付ファイルの内容が必要な場合は、message_id と attachment_id を指定して mailbox_read_attachment を呼び出します。
2. 小さなテキスト形式の添付ファイルの場合は、返された text を読み取ります。
3. バイナリ形式またはサイズの大きな添付ファイルの場合は、返された resource_link／download_url をモデルコンテキストの外で速やかに使用します。
4. メタデータだけで十分な場合、またはリンクを更新する必要がある場合に限り、mailbox_get_attachment を使用します。

MCP 経由で添付ファイルを送信する場合は、mailbox_upload_attachment を使用してください。入力方法は次のいずれか一つに限られます。

• ホスト型 MCP またはシェルを使用できるエージェントの場合は presign_upload_url=true を指定します。返された URL に正確なヘッダーを付けて、API キーなしでファイルをアップロードし、返された blob_id を使って送信します。
• content_base64 は、エージェントが作成した小さなファイルに限り使用でき、デコード後の上限は 32 KiB です。サイズが大きすぎる場合は、署名付きアップロード、CLI の --attach、または SDK のファイルヘルパーに切り替えてください。

署名付きアップロードでは、メールボックスの添付ファイル上限が適用されます。現在は添付ファイルごとに 7,500,000 バイトで、宣言された正確なバイト数とコンテンツタイプが固定されます。

メールボックスから送信する場合、mailbox_send_message では、小さなインライン Base64 添付ファイルオブジェクト（content、filename、content_type）またはアップロード済み添付ファイルの参照（blob_id、filename、content_type）のいずれかを使用できます。

Sending API から送信する場合、小さなインラインコンテンツには sending_upload_attachment のみを使用するか、sending_create_attachment_upload を呼び出して、モデルコンテキストの外でバイト列を PUT します。その後、sending_send_email.attachments[] に {"attachment_id": "att_..."} を渡します。

コンソールスクリプト

• sendmux-mcp
• sendmux-mcp-mailbox
• sendmux-mcp-management
• sendmux-mcp-sending
• sendmux-mcp-hosted

サポート

API エラーが発生した場合は、パッケージ名、バージョン、コマンド、トランスポート、およびリクエスト ID を添えて、Sendmux/sendmux-sdk で issue を作成してください。

ライセンス

MIT。ライセンスファイルを参照してください。