Sendmux Email Inbox Api + Sending

Sendmux 提供的电子邮件收件箱 API 和发送功能

为 AI Agent 提供电子邮件收件箱 API、入站邮件和出站发送 MCP 与 A2A 服务，支持入站电子邮件、简洁的 JSON 解析、Webhooks，以及通过 Sendmux 进行多提供商路由。

此软件包是 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 或更高版本。
• 用于 Sending 工具的、具备发送能力的 smx_mbx_* 密钥，或经所有者批准的 Sending 资源 smx_agent_* 令牌。
• 用于 Mailbox 工具的邮箱范围 smx_mbx_* 密钥或范围限定的 smx_agent_* 令牌。
• 用于 Management 工具的根 smx_root_* 密钥。

2.0.0 升级

2.0.0 版从 MCP 附件工具中移除了本地 file_path 和 roots 输入。升级自行管理的软件包或服务之前，请保留之前已知可正常工作的软件包环境、依赖项状态，以及 MCP 客户端和工具配置。更新附件调用方，改用面向 Agent 的附件工作流，然后验证工具发现功能以及 Agent 使用的每个附件工作流。

要回滚自行管理的安装，请一并恢复保留的软件包环境、依赖项状态，以及 MCP 客户端和工具配置。恢复 Agent 运行前，请验证工具发现功能和相关附件工作流。回滚软件包不会撤销已经完成的上传或发送操作。

对于使用 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

同时拥有两种密钥类型时，运行全部三个本地表面。

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。包装器命令只选择一个表面。

传输方式

stdio 是本地 Agent 客户端的默认传输方式。

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

http 和 streamable-http 会通过 HTTP 暴露 MCP 端点。HTTP 模式默认使用 127.0.0.1:8765/mcp，并且需要单独的 MCP Bearer 令牌，除非你明确选择不使用该令牌。

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 客户端，服务端也会支持；服务端会通过发现机制和 Bearer 挑战公布托管范围集合。

打包的 sendmux-mcp-hosted 命令会运行托管服务运行时。在本地和私有部署中，除非你正在运行兼容的 OAuth 托管环境，否则请使用上文的本地命令。

托管 A2A 端点

同一托管运行时通过 HTTP+JSON 在 https://a2a.sendmux.ai/a2a/v1 提供确定性的 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。其 data 用于选择精选的 Sendmux 操作并提供该操作的输入：

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

operationId 使用与托管 MCP 服务相同的精选操作 ID。OAuth 授权的受众绑定到 A2A 资源，并保留其 Sendmux 接口和权限限制。该服务会返回一个 JSON DataPart，其中包含上游状态、安全响应头和 JSON 正文（对于非 JSON 响应，则包含 bodyBase64）。

A2A 端点即时响应且无状态：不提供流式传输、推送通知、持久化任务和任务取消功能，也不会对此类请求进行路由。

配置

设置	环境变量	默认值
工具接口	SENDMUX_MCP_SURFACES	sendmux-mcp 必填；封装命令会选择一个接口
API 密钥回退	SENDMUX_API_KEY	兼容的单密钥配置可使用
邮箱 API 密钥	SENDMUX_MAILBOX_API_KEY	选择邮箱时必填，除非提供兼容的回退密钥
管理 API 密钥	SENDMUX_MANAGEMENT_API_KEY	选择管理时必填，除非提供兼容的回退密钥
发送 API 密钥	SENDMUX_SENDING_API_KEY	选择发送时必填，除非回退密钥是可发送的 smx_mbx_* 密钥，或所有者批准的 Sending-resource 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 Bearer 令牌	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。

工具界面

• 邮箱：用于已授权邮箱、资料/会话发现、邮件、附件、有界邮件等待、会话串、文件夹、搜索、计数和邮箱发送的工具。需要 smx_mbx_* 密钥或受限范围的 smx_agent_* 令牌。Agent 令牌仍受服务器端范围限制；认领前自行注册的 Agent 令牌不包含 email.send。
• 管理：用于域名、邮箱、日志、指标、支出摘要和 Webhook 的工具。需要 smx_root_* 密钥。
• 发送：用于附件上传引用、单封发送和批量发送的工具。需要 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"])

结果会标明已安装的发行版和版本。若源代码/版本证据过时、固定的 FastMCP 运行时不匹配，或已认证的修订版本不受支持，load_contract() 会引发 ValueError。记录的传递依赖 MCP 版本仅用于溯源，并不意味着依赖约束更严格。读取此制品并不能认证新解析出的依赖版本，也不能证明已部署的服务与此构建版本一致。

uploads 会区分本地强制执行的内联内容和 Mailbox 字节数上限，以及 Sending 返回的 max_size_bytes 权限值。Sending 预签名请求架构不会设置数值上限；请使用上传意图响应，而非历史源代码常量。URL 过期与附件的实际保留期限并不等同，此制品也不认证存储清理行为。

在仓库根目录中，pnpm generate:mcp 会刷新原生可编辑元数据并写入确定性的契约字节。准备好该环境后，pnpm exec .tmp/python-venv/bin/python -m sendmux_mcp.contract --check 会检查新鲜度，但不会重写文件。pnpm build:mcp 会验证测试、wheel/sdist 内容、安装后使用情况和冻结的一致性检查。检出版本中的更改只有在发布后才能通过 pip install 获取。

Agent 附件工作流

当用户要求 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。它只接受一种输入模式：

• 对于托管 MCP 或具备 shell 能力的 Agent，使用 presign_upload_url=true；将文件上传到返回的 URL，并使用准确的请求头且不带 API 密钥，然后使用返回的 blob_id 发送。
• content_base64 仅用于 Agent 创建的极小文件，解码后上限为 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 错误，请在 Sendmux/sendmux-sdk 中提交 issue，并附上包名称、版本、命令、传输方式和请求 ID。

许可证

MIT。请参阅许可证文件。