sendblue-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sendblue API

Overview

概述

Sendblue is a REST API that sends iMessage (blue bubbles), SMS, and RCS from a provisioned phone number. Everything is plain JSON over HTTPS — no SDK is required. The API covers outbound 1:1 and group sends, iMessage effects, reactions, typing indicators, status callbacks, and inbound webhooks.

Sendblue是一款REST API，可通过已配置的电话号码发送iMessage（蓝色气泡消息）、SMS和RCS消息。所有交互均基于HTTPS传输纯JSON数据——无需使用SDK。该API支持一对一及群组消息发送、iMessage特效、消息反应、输入状态提示、状态回调以及入站Webhook功能。

When to Use This Skill

何时使用该技能

Use when writing application code (server, worker, function) that sends Sendblue messages as part of a long-running service.
Use when receiving inbound messages via webhooks.
Use when you need features the CLI does not expose: send styles, reactions, group messages, typing indicators, status callbacks, media uploads, or the contacts API beyond basic CRUD.
Reach for [[sendblue-cli]] instead for shell-context outbound: one-shot scripts, cron jobs, agent hooks, "ping me when X" workflows.

当编写作为长期服务一部分、需要发送Sendblue消息的应用代码（服务器、工作进程、函数）时使用。
当通过Webhook接收入站消息时使用。
当需要CLI未提供的功能时使用：发送样式、消息反应、群组消息、输入状态提示、状态回调、媒体上传，或基础CRUD之外的联系人API功能。
若为Shell环境下的单次发送需求（如一次性脚本、定时任务、Agent钩子、"当X完成时通知我"工作流），请改用[[sendblue-cli]]。

How It Works

工作原理

Step 1: Authenticate

步骤1：身份验证

https://api.sendblue.com

Every request needs two headers:

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

Keep both values server-side — never ship them to a browser or mobile client.

https://api.sendblue.com

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

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

请将这两个值保存在服务器端——绝不要将它们部署到浏览器或移动客户端。

Step 2: Send a message

步骤2：发送消息

bash

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!"
  }'

Phone numbers must be E.164.

from_number

must be a line you own — list yours with

GET /api/lines

bash

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

列出您的所有号码。

Step 3: Track delivery

步骤3：跟踪投递状态

The synchronous response includes a

message_handle

(Apple GUID — persist this; you need it for reactions and replies) and a

status

from

REGISTERED

PENDING

QUEUED

ACCEPTED

SENT

DELIVERED

DECLINED

ERROR

. Only

DELIVERED

means it landed. Use

status_callback

instead of polling

/api/status

同步响应包含一个

message_handle

（苹果GUID——请保存该值，后续进行消息反应和回复时需要用到）以及一个状态值，可选状态包括

REGISTERED

、

PENDING

、

QUEUED

、

ACCEPTED

、

SENT

、

DELIVERED

、

DECLINED

、

ERROR

。只有

DELIVERED

表示消息已成功送达。请使用

status_callback

而非轮询

/api/status

接口。

Step 4: Receive inbound

步骤4：接收入站消息

Configure webhook URLs in the dashboard or via

POST /api/account/webhooks

. Sendblue POSTs JSON to your endpoint. Respond with 2xx promptly — non-2xx triggers retries and duplicate deliveries. Event types:

receive

outbound

typing_indicator

call_log

line_blocked

line_assigned

contact_created

在控制面板中或通过

POST /api/account/webhooks

配置Webhook URL。Sendblue会向您的端点发送POST请求并携带JSON数据。请及时返回2xx状态码——非2xx状态码会触发重试和重复投递。事件类型包括：

receive

、

outbound

、

typing_indicator

、

call_log

、

line_blocked

、

line_assigned

、

contact_created

。

Core Endpoints

核心端点

Method	Path	Purpose
POST	`/api/send-message`	Send a 1:1 message (text and/or media)
POST	`/api/send-group-message`	Send to multiple recipients
POST	`/api/create-group`	Create a named group thread
POST	`/api/send-reaction`	Send a tapback (love/like/dislike/laugh/emphasize/question)
POST	`/api/send-typing-indicator`	Show "typing…" in the recipient's thread
POST	`/api/mark-read`	Send a read receipt
POST	`/api/upload-file` / `/api/upload-media-object`	Upload media (direct or from URL)
GET	`/api/status`	Poll a message's delivery status
GET	`/api/evaluate-service`	Check whether a number is on iMessage
GET	`/api/v2/messages` / `/api/v2/messages/:id`	Read message history
GET / POST / PUT / DELETE	`/api/v2/contacts[...]`	Manage contacts
GET	`/api/lines`	List your Sendblue phone numbers
POST	`/api/account/webhooks`	CRUD webhook subscriptions

请求方法	路径	用途
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`	对Webhook订阅进行CRUD操作

Examples

示例

Example 1: Send with media, effects, and a status callback

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

json

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

and/or

media_url

is required.

send_style

is iMessage-only — valid values:

celebration

shooting_star

fireworks

lasers

love

confetti

balloons

spotlight

echo

invisible

gentle

loud

slam

. Ignored on SMS. Text up to 18,996 chars; media up to 100 MB on iMessage, 5 MB on SMS.

json

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消息中会被忽略。文本内容最多支持18996个字符；iMessage媒体文件最大为100MB，SMS媒体文件最大为5MB。

Example 2: Group message

示例2：群组消息

json

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

The response returns a

group_id

— persist it to send follow-ups into the same thread instead of creating a new one each time.

json

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

响应会返回一个

group_id

——请保存该值，以便后续发送消息到同一个会话，而非每次创建新会话。

Example 3: React to a message

示例3：对消息做出反应

json

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

Reactions only work on iMessage and need the original message's

message_handle

. Valid values:

love

like

dislike

laugh

emphasize

question

json

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

。

Example 4: Inbound webhook payload (

receive

)

示例4：入站Webhook负载（

receive

事件）

json

{
  "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"
}

Status callback payloads (

outbound

) mirror the send-message response and update as the message moves through

SENT

→

DELIVERED

(or

ERROR

json

{
  "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

事件）与发送消息的响应结构一致，会随着消息状态从

SENT

变为

DELIVERED

（或

ERROR

）而更新。

Best Practices

最佳实践

✅ Persist
message_handle
on every send. You need it for reactions, replies, and correlating status callbacks.
✅ Use
status_callback
over polling. It's lower-cost and more accurate than
```
GET /api/status
```
.
✅ Return 2xx fast from your webhook, then process async. Non-2xx triggers duplicate deliveries.
✅ Check service with
/api/evaluate-service
before relying on iMessage-only features for a recipient.
✅ Rehost inbound media on receipt — media URLs expire in ~30 days.
❌ Don't ship
sb-api-key-id
/
sb-api-secret-key
to a client. They are server-side credentials.
❌ Don't treat a 200 on
/api/send-message
as delivery. It only means "accepted".

✅ 每次发送消息后保存
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状态码视为消息已投递。它仅表示"已接受"。

Limitations

限制

Synchronous send responses only report acceptance, not delivery. Final state arrives via
```
status_callback
```
or
```
GET /api/status
```
.
```
send_style
```
silently no-ops on SMS (green-bubble recipients).
Inbound media URLs expire in ~30 days.
Per-line rate limits apply; bursting many sends from one number can trip Apple's spam heuristics — pace them or split across lines.
Reactions and effects are iMessage-only.

同步发送响应仅报告消息是否被接受，不报告投递状态。最终状态需通过
```
status_callback
```
或
```
GET /api/status
```
获取。
```
send_style
```
在SMS消息中会静默失效（接收者为绿色气泡消息）。
入站媒体URL会在约30天后过期。
每个号码都有速率限制；从单个号码批量发送大量消息可能会触发苹果的垃圾邮件检测机制——请控制发送频率或分散到多个号码发送。
消息反应和特效仅适用于iMessage。

Security & Safety Notes

安全与注意事项

Keep
```
sb-api-key-id
```
and
```
sb-api-secret-key
```
server-side. They are not safe in browser, mobile, or CI logs.
Webhook endpoints should be on HTTPS and idempotent — same
```
message_handle
```
may arrive more than once.
Sensitive data in message content is visible in lock-screen previews on the recipient's device. Don't embed secrets, tokens, or full PII — link to an authenticated dashboard or shortened payload instead.
Rotate API keys from the Sendblue dashboard if either value is exposed; the old pair is invalidated on rotation.

请将
```
sb-api-key-id
```
和
```
sb-api-secret-key
```
保存在服务器端。它们在浏览器、移动客户端或CI日志中是不安全的。
Webhook端点应使用HTTPS且具备幂等性——同一个
```
message_handle
```
可能会多次到达。
消息内容中的敏感数据会在接收者设备的锁屏预览中显示。请勿嵌入密钥、令牌或完整的个人身份信息——应链接到经过身份验证的控制面板或简化的负载内容。
如果任一凭据泄露，请在Sendblue控制面板中轮换API密钥；旧密钥对在轮换后会失效。

Common Pitfalls

常见陷阱

E.164 only.
```
5551234567
```
or
```
(555) 123-4567
```
will fail — always send
```
+15551234567
```
.
from_number
must be one of your lines. A spoofed or unprovisioned number returns an error.
send_style
silently no-ops on SMS. If the recipient is green-bubble, effects don't render — check service first with
```
/api/evaluate-service
```
if it matters.
Store
message_handle
. You need it for reactions, replies, and correlating status callbacks back to your records.
Media URLs expire in ~30 days. If you need durable media from inbound webhooks, download and re-host on receipt.
Status is async. A 200 on
```
/api/send-message
```
means accepted, not delivered. Use
```
status_callback
```
rather than blocking on the synchronous response.
Webhook retries on non-2xx. Return 200 even when you've decided to ignore the event; otherwise expect duplicate deliveries.
Rate limits apply per line. Bursting many sends from one number trips Apple's spam heuristics — pace them or split across lines.

仅支持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状态码；否则会收到重复投递。
每个号码都有速率限制。从单个号码批量发送大量消息会触发苹果的垃圾邮件检测机制——请控制发送频率或分散到多个号码发送。

Related Skills

链接

Full reference: https://docs.sendblue.com/
Sendblue: https://sendblue.com
Useful undocumented-here features: carousels (
```
/api/send-carousel
```
), FaceTime/contact-card sharing, advanced webhook filtering, contacts API beyond basic CRUD — see the docs site.

完整参考文档：https://docs.sendblue.com/
Sendblue官网：https://sendblue.com
本文档未提及的实用功能：轮播消息（
```
/api/send-carousel
```
）、FaceTime/联系人卡片分享、高级Webhook过滤、基础CRUD之外的联系人API功能——请查看官方文档网站。

sendblue-api

Original

Translation

Sendblue API

Sendblue API

Overview

概述

When to Use This Skill

何时使用该技能

How It Works

工作原理

Step 1: Authenticate

步骤1：身份验证

Step 2: Send a message

步骤2：发送消息

Step 3: Track delivery

步骤3：跟踪投递状态

Step 4: Receive inbound

步骤4：接收入站消息

Core Endpoints

核心端点

Examples

示例

Example 1: Send with media, effects, and a status callback

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

Example 2: Group message

示例2：群组消息

Example 3: React to a message

示例3：对消息做出反应

Example 4: Inbound webhook payload (receive)

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

Best Practices

最佳实践

Limitations

限制

Security & Safety Notes

安全与注意事项

Common Pitfalls

常见陷阱

Related Skills

相关技能

Links

链接

Example 4: Inbound webhook payload (
`receive`
)

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