Sendblue Imessage API

何时使用

• 在长期运行的服务（server / worker / function）里用应用代码发送 Sendblue 消息时。
• 需要通过 Webhook 接收入站消息时。
• 需要 CLI 不暴露的能力：发送特效（send styles）、反应（reactions）、群发、输入指示、状态回调、媒体上传，或超出基础 CRUD 的联系人 API。

不该用的边界：

• 只是 shell 上下文的一次性外发（脚本、cron、agent hook、「X 完成时 ping 我」）——改用 [[sendblue-cli]]。
• 不需要完整 HTTP 集成时，无需引入本技能。

风险提示：每一次外发、联系人/Webhook 变更、已读回执、反应、输入指示都是「改变状态」操作。先向用户预览收件人、发送线路、内容、回调/Webhook 变更，等明确确认后再发。

步骤

1. 鉴权

Base URL：https://api.sendblue.com。每个请求都需要两个请求头（外加 Content-Type: application/json）：

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 格式（如 +15551234567）。
• from_number 必须是你自己拥有的线路，用 GET /api/lines 列出。

3. 跟踪送达

同步响应里有：

• message_handle（Apple GUID）——务必持久化，反应、回复、关联状态回调都要用它。
• status：REGISTERED、PENDING、QUEUED、ACCEPTED、SENT、DELIVERED、DECLINED、ERROR。

只有 DELIVERED 才代表真正送达。优先用 status_callback，而不是轮询 GET /api/status。

4. 接收入站

在 Dashboard 或通过 POST /api/account/webhooks 配置 Webhook URL。Sendblue 会向你的端点 POST JSON。尽快返回 2xx——非 2xx 会触发重试和重复投递。

事件类型：receive、outbound、typing_indicator、call_log、line_blocked、line_assigned、contact_created。

指令

核心端点：

示例

示例 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 生效（SMS 上静默忽略），合法值：celebration、shooting_star、fireworks、lasers、love、confetti、balloons、spotlight、echo、invisible、gentle、loud、slam。文本最长 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>",
  "reaction": "love"
}

反应仅 iMessage 可用，且需要原消息的 message_handle。合法值：love、like、dislike、laugh、emphasize、question。

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

{
  "accountEmail": "you@example.com",
  "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）镜像 send-message 响应，随消息从 SENT → DELIVERED（或 ERROR）更新。

注意事项

最佳实践：

• 每次发送都持久化 message_handle——反应、回复、关联状态回调都靠它。
• 用 status_callback 取代轮询，更省成本也更准。
• Webhook 快速返回 2xx，再异步处理；非 2xx 会导致重复投递（同一 message_handle 可能到达多次，端点需幂等）。
• 依赖 iMessage 专属特性前，先用 /api/evaluate-service 检查对方服务类型。
• 入站媒体 URL 约 30 天过期，收到时立即转存到自己的存储。

常见坑：

• 只接受 E.164：5551234567 或 (555) 123-4567 会失败，必须 +15551234567。
• from_number 必须是你的线路：伪造或未开通的号码会报错。
• send_style 在 SMS 上静默无效（绿色气泡收件人）。
• 状态是异步的：/api/send-message 返回 200 只代表「已接受」，不等于「已送达」。
• 每条线路有速率限制：单号码爆发式群发会触发 Apple 反垃圾启发式判定——放慢节奏或拆分到多条线路。

安全：

• sb-api-key-id / sb-api-secret-key 是服务端凭据，不能出现在浏览器、移动端或 CI 日志里。
• Webhook 端点应走 HTTPS 且幂等。
• 消息内容会在对方锁屏预览中可见，不要嵌入密钥、令牌或完整 PII——改为附带需鉴权的链接。
• 凭据泄露时从 Dashboard 轮换 API 密钥，旧密钥对在轮换后立即失效。

互见

• [[sendblue-cli]]——shell 上下文外发的封装（脚本、cron、agent hook），不需要完整 HTTP 集成时用它。
• [[sendblue-notify]]——在 API/CLI 之上做「X 完成时给我发消息」通知的模式与文案规则。
• 完整参考：https://docs.sendblue.com/ ；官网：https://sendblue.com
• 本文未展开的进阶能力：轮播卡片（/api/send-carousel）、FaceTime/联系人卡片分享、高级 Webhook 过滤、超出基础 CRUD 的联系人 API——见文档站。

采编自 sickn33/antigravity-awesome-skills（MIT）。