Sendmux 发送邮件

ClawHub 账户说明

本 ClawHub 技能用于将 OpenClaw 智能体连接至 Sendmux。部分工作流需要有效的 Sendmux 账户及相应的 Sendmux API 密钥或智能体令牌（agent token）。Sendmux 账户的使用完全独立于 ClawHub；请勿要求用户在聊天中粘贴密钥等敏感信息。

当用户已准备好通过 Sendmux 发送外发邮件，或需要获取发送邮件所需的代码/命令时，可使用此技能。

安全第一

• 切勿要求用户提供 API 密钥。
• 切勿自行编造收件人、发件人地址、主题行或正文内容。
• 仅在用户明确提供或确认全部收件人及完整邮件内容后，才执行发送操作。
• 对于批量发送，请在调用发送工具前，完整确认所有收件人及对应邮件内容。
• 请使用具备发送能力的 smx_mbx_ 密钥，或经所有者授权的 Sending 资源型 smx_agent_ 令牌，以调用 Sending API。
• 禁止使用预注册（pre-claim）的 smx_agent_ 令牌进行邮件发送。预注册的自注册智能体令牌仅具备 mailbox.read 和 email.receive 权限，不包含 email.send 权限。
• 若使用自注册智能体，请在获得所有者批准后，使用已保存的 claim_token 向 resource=https://smtp.sendmux.ai/api/v1 兑换具备 Sending 资源权限的 smx_agent_ 令牌。

选择发送路径

批量发送最多支持 100 封邮件。批量响应可能为部分成功，因此请逐项检查每个结果项。

必需的 JSON 结构

单封邮件请求体：

{
  "from": { "email": "sender@example.com", "name": "Sender Name" },
  "to": { "email": "recipient@example.com", "name": "Recipient Name" },
  "subject": "Subject line",
  "html_body": "
Hello.
",
  "text_body": "Hello."
}

必需字段：from、to、subject、html_body。

常用可选字段：

• text_body：纯文本备选内容。
• cc、bcc：收件人数组，每组最多 100 个。
• reply_to：单个地址对象。
• return_path：退信处理所用的信封发件人地址。
• custom_headers：自定义 X-* 头部字段。
• attachments：最多 10 项。推荐使用已上传的引用形式：{ "attachment_id": "att_..." }；兼容内联格式则需提供 filename 及 base64 编码的 content，可选 type 字段，并显式指定 encoding: "base64"。

对于真实本地文件，切勿要求模型生成 base64 编码。应将附件密集型任务路由至 sendmux-attachments；使用 CLI --attach、SDK 文件辅助方法、sending_upload_attachment 或委托式 sending_create_attachment_upload 完成上传，再传入 attachment_id 引用。Sending 上传对单个文件大小上限为 18 MiB，最终发出的邮件总大小上限为 25 MB。邮箱中的 blob_id 引用仅适用于邮箱发送（mailbox sends），不适用于 Sending API 发送。

批量发送请求体：

{
  "messages": [
    {
      "from": { "email": "sender@example.com" },
      "to": { "email": "alice@example.com" },
      "subject": "Hello Alice",
      "html_body": "
Hi Alice.
"
    },
    {
      "from": { "email": "sender@example.com" },
      "to": { "email": "bob@example.com" },
      "subject": "Hello Bob",
      "html_body": "
Hi Bob.
"
    }
  ]
}

幂等性

对任何可能被重试的发送请求，均须添加 Idempotency-Key 请求头。每个逻辑邮件或批量请求应使用一个稳定不变的键值。

• 相同键值 + 相同请求体：24 小时内返回缓存响应。
• 相同键值 + 不同请求体：返回 409 idempotency_conflict 错误。
• 键值长度不得超过 255 字符。

MCP

当用户智能体已连接 Sending 服务时，推荐使用 MCP：

• 单条消息：使用 sending_send_email。
• 多条消息：使用 sending_send_email_batch。
• 发送前上传本地文件：使用 sending_upload_attachment 并传入 file_path 参数。
• 发送前上传托管文件或通过 Shell 执行上传：使用 sending_create_attachment_upload 获取预签名上传 URL，随后使用返回的请求头（不含 Sendmux API 密钥）向该 URL 发起 PUT 请求并上传字节流。
• 查询临时上传附件的元数据：使用 sending_get_attachment。

若客户端暴露了请求头参数，则应在请求中包含幂等性键（idempotency key）。若 MCP 客户端未清晰暴露请求头配置能力，则对重试敏感的发送操作应改用 CLI、SDK 或直接 HTTP 方式。对于通过 MCP 处理附件的场景，建议统一使用 sendmux-attachments，以便智能体根据实际情况自动选择 file_path、预签名上传或极小体积的内联 base64 编码。

CLI

单封邮件：

SENDMUX_API_KEY="$SENDMUX_MBX_KEY" sendmux sending:send 
  --idempotency-key "$IDEMPOTENCY_KEY" 
  --body '{
    "from": { "email": "sender@example.com", "name": "Sender Name" },
    "to": { "email": "recipient@example.com", "name": "Recipient Name" },
    "subject": "Subject line",
    "html_body": "
Hello.
",
    "text_body": "Hello."
  }' 
  --json

批量发送：

SENDMUX_API_KEY="$SENDMUX_MBX_KEY" sendmux sending:send:batch 
  --idempotency-key "$IDEMPOTENCY_KEY" 
  --body-file ./sendmux-batch.json 
  --json

使用 --attach ./file.pdf 处理本地文件；CLI 将自动完成文件上传，并在发送前注入 attachment_id 引用。对于较大 JSON 载荷或已准备就绪的 Sending API 附件对象，请使用 --body-file 参数。

TypeScript SDK

单封邮件：

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

const client = createSendingClient({ apiKey: process.env.SENDMUX_API_KEY! });

const response = await sendingSendEmail({
  client,
  headers: { "Idempotency-Key": idempotencyKey },
  body: {
    from: { email: "sender@example.com", name: "Sender Name" },
    to: { email: "recipient@example.com", name: "Recipient Name" },
    subject: "Subject line",
    html_body: "
Hello.
",
    text_body: "Hello.",
  },
});

console.log(response.data.message_id, response.data.status);

批量发送：

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

const client = createSendingClient({ apiKey: process.env.SENDMUX_API_KEY! });

const response = await sendingSendEmailBatch({
  client,
  headers: { "Idempotency-Key": idempotencyKey },
  body: {
    messages,
  },
});

for (const result of response.data.results) {
  console.log(result.index, result.status, result.message_id, result.error);
}

直接 HTTP

仅在无法使用 MCP、CLI 或 SDK 时，才采用直接 HTTP 方式：

curl -X POST https://smtp.sendmux.ai/api/v1/emails/send 
  -H "Authorization: Bearer $SENDMUX_MBX_KEY" 
  -H "Content-Type: application/json" 
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" 
  -d @sendmux-email.json

响应与错误处理

单封邮件成功响应返回 200 状态码，响应体结构如下：

• data.message_id：形如 eml_...
• data.status：值为 queued

批量发送成功响应同样返回 200 状态码，响应体结构如下：

• data.summary.total
• data.summary.queued
• data.summary.failed
• data.results[] 数组，其中每一项包含 index、status、message_id 及可选的 error

请显式处理以下错误：

• 401：密钥缺失、无效或已被撤销。
• 402：账户余额不足。
• 403：密钥缺少 email.send 权限、未获准用于当前发件人，或使用了错误的接口面（surface）。
• 409：幂等性冲突。
• 413：请求体超过 25 MB 限制。
• 422：校验失败；请查阅 error.errors 字段详情。
• 429 或 503：依据响应头中的重试策略进行重试。

路由指引

• 初始设置/鉴权调用：sendmux-getting-started。
• 附件文件路径、预签名上传 URL 及下载 URL：sendmux-attachments。
• 以邮箱为中心的回复操作：sendmux-mailbox-agent。
• 仅限 CLI 的细节说明：sendmux-cli。
• 成本最优调用决策：sendmux-token-efficient-usage。