sendblue-api

Sendblue API

概述

Sendblue 是一个 REST API，可通过已开通的电话号码发送 iMessage（蓝色气泡）、SMS 和 RCS。所有内容都是通过 HTTPS 传输的纯 JSON — 无需 SDK。该 API 支持发送单聊和群组消息、iMessage 特效、回应、输入指示器、状态回调和入站 Webhook。

何时使用此技能

• 在编写应用程序代码（服务器、工作进程、函数），以便在长期运行的服务中发送 Sendblue 消息时使用。
• 通过 Webhook 接收入站消息时使用。
• 需要 CLI 未提供的功能时使用：发送样式、回应、群组消息、输入指示器、状态回调、媒体上传，或超出基本 CRUD 的联系人 API。
• 对于 shell 上下文中的出站消息，请改用 [[sendblue-cli]]：一次性脚本、cron 作业、Agent 钩子、“X 发生时通知我”工作流。

工作原理

第 1 步：进行身份验证

https://api.sendblue.com

每个请求都需要两个标头：

sb-api-key-id: <YOUR_API_KEY_ID>
sb-api-secret-key: <YOUR_API_SECRET>
Content-Type: application/json

请将这两个值保存在服务器端 — 切勿发送到浏览器或移动客户端。

第 2 步：发送消息

curl -X POST https://api.sendblue.com/api/send-message \
  -H "sb-api-key-id: $KEY_ID" \
  -H "sb-api-secret-key: $SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "+15551234567",
    "from_number": "+1YOUR_SENDBLUE_NUMBER",
    "content": "Hello from the API!"
  }'

电话号码必须采用 E.164 格式。from_number 必须是你拥有的号码 — 使用 GET /api/lines 列出你的号码。

第 3 步：跟踪投递状态

同步响应包含一个 message_handle（Apple GUID — 请保存；回应和回复时需要用到）以及一个 status，取值为 REGISTERED、PENDING、QUEUED、ACCEPTED、SENT、DELIVERED、DECLINED、ERROR。只有 DELIVERED 表示消息已送达。请使用 status_callback，而不是轮询 /api/status。

第 4 步：接收入站消息

在控制面板中或通过 POST /api/account/webhooks 配置 Webhook URL。Sendblue 会向你的端点发送 JSON。请及时响应 2xx — 非 2xx 响应会触发重试和重复投递。事件类型：receive、outbound、typing_indicator、call_log、line_blocked、line_assigned、contact_created。

核心端点

方法	路径	用途
POST	/api/send-message	发送单聊消息（文本和/或媒体）
POST	/api/send-group-message	向多个收件人发送消息
POST	/api/create-group	创建已命名的群组会话
POST	/api/send-reaction	发送 Tapback 回应（喜爱/赞/踩/大笑/强调/疑问）
POST	/api/send-typing-indicator	在收件人的会话中显示“正在输入…”
POST	/api/mark-read	发送已读回执
POST	/api/upload-file / /api/upload-media-object	上传媒体（直接上传或从 URL 上传）
GET	/api/status	轮询消息的投递状态
GET	/api/evaluate-service	检查某个号码是否开通了 iMessage
GET	/api/v2/messages / /api/v2/messages/:id	读取消息历史记录
GET / POST / PUT / DELETE	/api/v2/contacts[...]	管理联系人
GET	/api/lines	列出你的 Sendblue 电话号码
POST	/api/account/webhooks	CRUD Webhook 订阅

示例

示例 1：发送包含媒体、特效和状态回调的消息

POST /api/send-message
{
  "number": "+15551234567",
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "content": "Optional text",
  "media_url": "https://example.com/img.jpg",
  "send_style": "celebration",
  "status_callback": "https://yourapp.com/sendblue/status"
}

必须提供 content 和/或 media_url。send_style 仅适用于 iMessage — 有效值：celebration、shooting_star、fireworks、lasers、love、confetti、balloons、spotlight、echo、invisible、gentle、loud、slam。SMS 会忽略此参数。文本最多 18,996 个字符；iMessage 媒体最大 100 MB，SMS 最大 5 MB。

示例 2：群组消息

POST /api/send-group-message
{
  "numbers": ["+15551234567", "+15557654321"],
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "content": "Hey team"
}

响应会返回一个 group_id — 请保存它，以便在同一会话中发送后续消息，而不是每次都创建新会话。

示例 3：回应消息

POST /api/send-reaction
{
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "message_handle": "<message_handle from prior send>",
  "reaction": "love"
}

回应仅适用于 iMessage，且需要原始消息的 message_handle。有效值：love、like、dislike、laugh、emphasize、question。

示例 4：入站 Webhook 负载（receive）

{
  "accountEmail": "[email protected]",
  "content": "Reply text",
  "media_url": "https://...",
  "is_outbound": false,
  "number": "+15551234567",
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "service": "iMessage",
  "group_id": "...",
  "date_sent": "2024-01-01T12:00:00Z"
}

状态回调负载（outbound）与发送消息的响应一致，并会随着消息状态从 SENT 更新为 DELIVERED（或 ERROR）。

最佳实践

• ✅ 每次发送都持久化 message_handle。 后续添加回应、回复消息以及关联状态回调时都需要它。
• ✅ 优先使用 status_callback，而不是轮询。 与 GET /api/status 相比，它成本更低，也更准确。
• ✅ Webhook 应快速返回 2xx，然后异步处理。 返回非 2xx 会触发重复投递。
• ✅ 在为收件人使用仅限 iMessage 的功能前，通过 /api/evaluate-service 检查服务。
• ✅ 收到媒体后立即重新托管 — 媒体 URL 会在约 30 天后过期。
• ❌ 不要将 sb-api-key-id / sb-api-secret-key 发送给客户端。 这些是服务端凭据。
• ❌ 不要把 /api/send-message 返回 200 当作已送达。 它只表示“已接受”。

限制

• 同步发送响应只报告已接受，不报告已送达。最终状态会通过 status_callback 或 GET /api/status 返回。
• send_style 在 SMS 上会静默无效（绿色气泡收件人）。
• 收到的媒体 URL 会在约 30 天后过期。
• 每条线路都有速率限制；从一个号码突发发送大量消息可能触发 Apple 的垃圾信息检测机制 — 请控制发送频率，或拆分到多条线路。
• 回应和特效仅适用于 iMessage。

安全与注意事项

• 将 sb-api-key-id 和 sb-api-secret-key 保存在服务端。这些信息不适合放在浏览器、移动设备或 CI 日志中。
• Webhook 端点应使用 HTTPS，并具备幂等性 — 同一个 message_handle 可能会被投递多次。
• 消息内容中的敏感数据会显示在收件人设备的锁屏预览中。不要嵌入密钥、令牌或完整的个人身份信息（PII）— 请改为链接到经过身份验证的仪表板，或使用精简后的内容。
• 如果任一值泄露，请从 Sendblue 仪表板轮换 API 密钥；轮换后，旧密钥对将失效。

常见问题

• 仅支持 E.164 格式。 5551234567 或 (555) 123-4567 会失败 — 请始终发送 +15551234567。
• from_number 必须是你拥有的线路之一。 使用伪造或未配置的号码会返回错误。
• send_style 在 SMS 上会静默无效。 如果收件人使用绿色气泡，特效将不会显示 — 如果这很重要，请先通过 /api/evaluate-service 检查服务。
• 保存 message_handle。 添加回应、回复消息以及将状态回调关联到你的记录时都需要它。
• 媒体 URL 会在约 30 天后过期。 如果需要长期保留通过入站 Webhook 收到的媒体，请收到后下载并重新托管。
• 状态是异步的。 /api/send-message 返回 200 表示已接受，而非已送达。请使用 status_callback，不要等待同步响应。
• 非 2xx 响应会触发 Webhook 重试。 即使你决定忽略该事件，也请返回 200；否则会收到重复投递。
• 速率限制按线路生效。 从一个号码突发发送大量消息会触发 Apple 的垃圾信息检测机制 — 请控制发送频率，或拆分到多条线路。

相关技能

• @sendblue-cli — 用于命令行上下文出站消息的 Shell 封装（脚本、cron、Agent 钩子）。如果不需要完整的 HTTP 集成，请使用它。
• @sendblue-notify — 在 API 或 CLI 之上实现“X 完成时给我发消息”出站通知的模式和文案规则。

链接

• 完整参考文档：https://docs.sendblue.com/
• Sendblue：https://sendblue.com
• 本文档未提及的实用功能：轮播（/api/send-carousel）、FaceTime/联系人名片分享、高级 Webhook 筛选，以及基础 CRUD 之外的联系人 API — 请参阅文档网站。