Sendmux 入门指南

ClawHub 账户说明

本 ClawHub 技能用于将 OpenClaw 智能体连接至 Sendmux。部分工作流需要一个 Sendmux 账户以及对应的 Sendmux API 密钥或智能体令牌（agent token）。Sendmux 账户的使用独立于 ClawHub；请勿要求用户将密钥粘贴到聊天窗口中。

使用此技能，可帮助用户从“我有一个 Sendmux 任务”出发，快速定位到正确的接入面（surface）、密钥类型、软件包，并完成首次经验证的调用。

安全第一

• 切勿要求用户提供 API 密钥。
• 切勿在任何输出中打印 API 密钥。
• 优先使用已有的环境变量、本地 CLI 配置文件，或用户的密钥管理器（secret manager）。
• 注册完成后，须立即将自注册凭证包（self-registration credential bundle）存入安全存储；后续的 MCP、CLI、SDK、邮箱（mailbox）及发送（sending）操作均依赖该凭证包。
• claim_token 或智能体凭证绝不可仅通过聊天记录、日志、代码仓库文件、截图或仅驻留内存的状态进行传递或存储。
• identity_assertion 或预申领（pre-claim）的 smx_agent_* 令牌需持续可用，直至所有者邀请返回 202 状态码；claim_token 仅用于审批通过后的交换流程。
• 若密钥意外出现在聊天记录或日志中，请立即中止操作，并提示用户轮换（rotate）该密钥后再继续。

安装 Sendmux 技能

若当前智能体支持 Skills 功能，且尚未安装 Sendmux 相关技能，请先安装技能包：

npx skills add Sendmux/skills

Skills 为可选功能。若智能体不支持安装 Skills，请直接从 https://app.sendmux.ai/auth.md 开始操作。

选择密钥类型

若任务同时涉及管理类与邮箱类操作，请分别使用独立密钥及对应客户端或配置文件。切勿在邮箱作用域场景中使用 root 密钥。

选择接入面（Surface）

1. 当用户智能体已连接相关 sendmux-mcp 服务，且所需工具已被精选收录时，优先选用 MCP。
2. 对于一次性终端操作、调试、Shell 脚本或用户可直接复制到终端中执行的示例，请使用 sendmux CLI。建议添加 --json 参数，以便下游智能体解析响应结构。
3. 编写应用程序代码时，请使用 SDK。除非项目需同时对接多个接入面，否则仅安装所选接入面对应的软件包即可。
4. 仅当用户运行环境无法使用 MCP、CLI 或 SDK 时，才采用直接 HTTP 调用方式。

安装对应软件包

CLI：

npm install -g @sendmux/cli

MCP：

pipx install sendmux-mcp

TypeScript SDK 软件包：

npm install @sendmux/mailbox
npm install @sendmux/management
npm install @sendmux/sending

请根据任务类型选择并安装唯一匹配的软件包；除非项目确实需要全部三类功能，否则无需安装全部三个包。

首次经验证调用

邮箱密钥（Mailbox Key）与邮箱类操作

MCP 工具调用：

mailbox_get_me

CLI：

SENDMUX_API_KEY="$SENDMUX_MBX_KEY" sendmux profiles:set mailbox --default --json
sendmux mailbox:me:get --json

SDK：

import { createMailboxClient, mailboxGetMe } from "@sendmux/mailbox";

const client = createMailboxClient({ apiKey: process.env.SENDMUX_API_KEY! });
const response = await mailboxGetMe({ client });
console.log(response.data);

该调用将解析承载令牌（bearer token）所关联的邮箱身份，是针对 smx_mbx_ 及作用域受限的 smx_agent_ 邮箱工作流默认且安全的首调接口。

自注册智能体令牌（Self-registered Agent Token）

适用于智能体尚无任何人手工创建密钥的情形。

1. 阅读 https://app.sendmux.ai/auth.md 文档。
2. 若智能体需精确复现求解逻辑，可参考 /auth.md 中提供的复制粘贴式证明辅助工具（copy-paste proof helper）。
3. 向 POST /agent-auth/agent/identity/challenge 端点提交匿名注册请求体（intended anonymous registration body），以获取注册挑战（registration challenge）。
4. 求解返回的 PoW（Proof-of-Work）挑战。
5. 将 proof_of_work 编码为 Base64 UTF-8 格式的 JSON 字符串，格式如下：{ "challenge": , "solution": { "counter": , "derivedKey": } }。
6. 在 identity_endpoint（即 POST /agent-auth/agent/identity）处，使用相同请求体并附加 proof_of_work 创建匿名身份。
7. 立即在令牌交换前，将返回的 claim_token 与智能体凭证包（agent credential bundle）安全持久化存储；随后使用返回的 identity_assertion 向 POST /agent-auth/oauth2/token 发起令牌交换。
8. 使用返回的 smx_agent_ 令牌调用 GET /api/v1/mailbox/me。
9. identity_assertion 或预申领令牌（pre-claim token）须保持可用，直至所有者邀请返回 202；claim_token 本身无法触发邀请流程。
10. 预申领令牌成功后不可停止流程。若已知所有者邮箱地址，请调用 POST /agent-auth/agent/identity/invite 发起邀请；若未知，则询问：我应邀请哪位所有者邮箱进行审批？
11. 待所有者在 Sendmux 中接受并批准发送权限后，使用 claim_token 完成申领授权（claim grant）；在调用 Sending API 前，需指定 resource=https://smtp.sendmux.ai/api/v1。

预申领的 smx_agent_ 令牌仅具备 mailbox.read 与 email.receive 权限，不具备 email.send；经所有者批准的 Sending 资源型 smx_agent_ 令牌方可从所分配邮箱发送邮件。Sendmux 通过邀请端点（invite endpoint）向所有者发送邀请邮件。同一时刻仅允许存在一个有效的预申领邀请；重试时需复用相同的幂等性键（idempotency key）。若令牌交换返回预期的 503 状态，应遵循 Retry-After 或 retry_after 响应头等待重试；若注册返回 503 server_error，请立即中止并上报错误，而非循环重试；若智能体认证（agent auth）返回 429，也须等待 Retry-After 或 retry_after 后再重试。

claim_token 仅在注册成功后显示一次，且所有者审批通过后必须使用该值。Sendmux 无法在之后恢复该令牌。注册完成后，须立即安全存储完整的智能体凭证包，包含：claim_token、registration_id、mailbox.email、claim_token_expires、identity_assertion、token_endpoint、应用资源 URL 与发送资源 URL。推荐使用 1Password、操作系统密钥链（OS keychain）或智能体平台提供的加密密钥存储服务。令牌交换后，应保留预申领令牌，或持续维护 identity_assertion 的可用性直至邀请返回 202。若无可用安全存储，请中止流程并询问用户：“凭证包应存于何处？” 再发送所有者邀请。若 claim_token 遗失，需重新执行注册与邀请流程，并生成新的智能体身份；若在邀请返回 202 前已丢失 identity_assertion 和预申领令牌，请立即在同一上下文中重跑注册与邀请流程。

Root 密钥与管理类操作

MCP 工具调用：

management_list_mailboxes

CLI：

SENDMUX_API_KEY="$SENDMUX_ROOT_KEY" sendmux profiles:set root --default --json
sendmux management:mailboxes:list --query limit=1 --json

SDK：

import {
  createManagementClient,
  managementListMailboxes,
} from "@sendmux/management";

const client = createManagementClient({ apiKey: process.env.SENDMUX_API_KEY! });
const response = await managementListMailboxes({
  client,
  query: { limit: 1 },
});
console.log(response.data);

建议以小规模列表查询作为首次管理类检查，既可验证 root 密钥有效性，又避免误创建或修改资源。

发送类操作（Sending Work）

发送（Sending）接入面需使用具备 email.send 权限的发送能力型 smx_mbx_ 密钥，或经所有者批准的 Sending 资源型 smx_agent_ 令牌。除非用户明确要求发送测试邮件并提供完整消息内容，否则不应以真实邮件发送作为健康检查手段。

CLI 端软件包/API 发现：

SENDMUX_API_KEY="$SENDMUX_MBX_KEY" sendmux sending:get-open-api-spec --json

SDK 端软件包/API 发现：

import { createSendingClient, sendingGetOpenApiSpec } from "@sendmux/sending";

const client = createSendingClient({ apiKey: process.env.SENDMUX_API_KEY! });
const response = await sendingGetOpenApiSpec({ client });
console.log(response.data.info);

如需真实发送邮件，请路由至 sendmux-send-email 并附带 Idempotency-Key 请求头。

故障排查指南

• 前缀不匹配错误：所选接入面与凭证类型不一致。请确认：邮箱类操作使用 smx_mbx_ 或作用域受限的 smx_agent_；发送类操作使用具备发送能力的 smx_mbx_ 密钥或经所有者批准的 Sending 资源型 smx_agent_；管理类操作使用 smx_root_。
• 401：密钥缺失、无效或已被撤销。
• 403：密钥有效，但缺少当前调用所需的权限或接入面支持。
• 429 或 503：请严格依据响应头中的重试策略执行，切勿手动循环重试。
• 返回空列表且 ok: true：身份认证已成功，仅表示当前暂无对应资源。

设置完成后的后续路由

• 发送一条或多条出站邮件：sendmux-send-email。
• 从邮箱中读取、搜索、同步或回复邮件：sendmux-mailbox-agent。
• 管理域名、邮箱、密钥、Webhook、支出、日志或指标数据：sendmux-management。
• 面向 CLI 的特定工作流：sendmux-cli。
• MCP 客户端配置：sendmux-mcp-setup。
• 选择成本最优的调用模式：sendmux-token-efficient-usage。