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

AIエージェント向けのメール受信トレイAPI、インバウンドメール、アウトバウンド送信のMCPおよびA2Aサーバーです。Sendmuxを通じて、インバウンドメール、クリーンなJSON解析、Webhook、マルチプロバイダールーティングを提供します。

このパッケージは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

Related MCP server: mcp-server-lobstermail

要件

• Python 3.10以降。

• 送信ツールには、送信可能なsmx_mbx_*キー、またはオーナー承認済みの送信リソースsmx_agent_*トークン。

• メールボックスツールには、メールボックススコープのsmx_mbx_*キー、またはスコープ付きsmx_agent_*トークン。

• 管理ツールには、ルートsmx_root_*キー。

インストール

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は、MCPエンドポイントをHTTP経由で公開します。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で決定的なA2A 1.0をHTTP+JSONで公開します。https://a2a.sendmux.ai/.well-known/agent-card.jsonからディスカバリできます。OAuthリソースメタデータはhttps://a2a.sendmux.ai/.well-known/oauth-protected-resourceにあります。

A2Aのmessage:send操作に、正確に1つのJSON DataPartを送信します。そのデータは、キュレーションされたSendmux操作を選択し、その操作の入力を提供します:

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

operationIdは、ホステッドMCPサービスと同じキュレーションされた操作IDを使用します。OAuthグラントはA2Aリソースにオーディエンスバインドされ、Sendmuxサーフェスと権限の制限を保持します。サービスは、アップストリームのステータス、安全なレスポンスヘッダー、JSONボディ（非JSONレスポンスの場合はbodyBase64）を含む1つのJSON DataPartを返します。

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

設定

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

ツールサーフェス

• メールボックス: 許可されたメールボックス、プロファイル/セッションディスカバリ、メッセージ、添付ファイル、境界付きメッセージ待機、スレッド、フォルダー、検索、カウント、メールボックス送信のための25ツール。smx_mbx_*キーまたはスコープ付きsmx_agent_*トークンが必要です。エージェントトークンはサーバー側スコープによって制限されたままです。事前クレームの自己登録エージェントトークンにはemail.sendは含まれません。

• 管理: ドメイン、メールボックス、ログ、メトリクス、支出サマリー、Webhookのための21ツール。smx_root_*キーが必要です。

• 送信: 添付アップロード参照、単一送信、バッチ送信のための5ツール。smx_mbx_*キーまたはオーナー承認済みの送信リソースsmx_agent_*トークンが必要です。

サーバーは、間違ったプレフィックスのキーを起動前に拒否します。

エージェント向け添付ワークフロー

ユーザーがエージェントに新しいメールを待つように依頼した場合は、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を使用します。これは正確に1つの入力モードを受け付けます:

• ローカルstdio MCPで、ファイルがクライアント宣言のファイルシステムルート内にある場合のfile_path。

• ホステッドMCPまたはシェル対応エージェントの場合はpresign_upload_url=true。返されたURLに正確なヘッダーとAPIキーなしでファイルをアップロードし、返されたblob_idで送信します。

• エージェントが作成した小さなファイルのみのcontent_base64。デコード後32 KiBに制限されます。大きすぎる場合は、file_path、プリサインアップロード、CLI --attach、またはSDKファイルヘルパーに切り替えてください。

file_pathとプリサインアップロードモードは、メールボックス添付上限（現在は添付あたり7,500,000バイト）を使用します。プリサインアップロードは、宣言された正確なバイト長とコンテンツタイプも固定します。

メールボックス送信の場合、mailbox_send_messageは、小さなインラインbase64添付オブジェクト（content、filename、content_type）またはアップロードされた添付参照（blob_id、filename、content_type）のいずれかを受け付けます。

送信API送信の場合、ローカルstdio MCPではfile_pathを指定してsending_upload_attachmentを呼び出すか、ホステッド/シェル対応エージェントではsending_create_attachment_uploadを呼び出してモデルコンテキスト外でバイトをPUTします。次に、sending_send_email.attachments[]に{"attachment_id": "att_..."}を渡します。小さな生成コンテンツを除き、送信インラインbase64は避けてください。

コンソールスクリプト

• sendmux-mcp

• sendmux-mcp-mailbox

• sendmux-mcp-management

• sendmux-mcp-sending

• sendmux-mcp-hosted

サポート

Sendmux/sendmux-sdk に、APIエラーから得られるパッケージ名、バージョン、コマンド、トランスポート、リクエストIDを添えてIssueを開いてください。

ライセンス

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