使用 Sendly 发送短信

快速开始

import Sendly from "@sendly/node";

const sendly = new Sendly(process.env.SENDLY_API_KEY!);

const message = await sendly.messages.send({
  to: "+15551234567",
  text: "您的订单已发货！",
  messageType: "transactional",
});

身份验证

所有请求均需携带 Bearer Token。请将 API 密钥存入环境变量 SENDLY_API_KEY 中。

• sk_test_* 开头的密钥 → 沙盒模式（不发送真实短信，不扣除信用额度）
• sk_live_* 开头的密钥 → 生产环境（仅向已验证号码发送真实短信）

REST API

基础 URL： https://sendly.live/api/v1

发送短信

curl -X POST https://sendly.live/api/v1/messages 
  -H "Authorization: Bearer $SENDLY_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"to": "+15551234567", "text": "Hello!", "messageType": "transactional"}'

必填字段： to（E.164 格式）、text、messageType（可选值：transactional 或 marketing）

可选字段： metadata（对象类型，最大 4KB）、from（发件人 ID）

响应结构

{
  "id": "msg_abc123",
  "to": "+15551234567",
  "text": "Hello!",
  "status": "sent",
  "segments": 1,
  "creditsUsed": 2,
  "createdAt": "2026-03-31T10:00:00Z"
}

定时发送短信

curl -X POST https://sendly.live/api/v1/messages/schedule 
  -H "Authorization: Bearer $SENDLY_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"to": "+15551234567", "text": "Reminder!", "messageType": "transactional", "scheduledAt": "2026-04-01T14:00:00Z"}'

支持的定时窗口：未来 5 分钟至 5 天。

批量发送

curl -X POST https://sendly.live/api/v1/messages/batch 
  -H "Authorization: Bearer $SENDLY_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"messages": [{"to": "+15551234567", "text": "Hello"}, {"to": "+15559876543", "text": "Hi"}], "messageType": "transactional"}'

单批次最多支持 10,000 个收件人。

查询短信列表

curl "https://sendly.live/api/v1/messages?limit=50" 
  -H "Authorization: Bearer $SENDLY_API_KEY"

支持参数：limit、offset、status、q（全文搜索）。

Node.js SDK

npm install @sendly/node

import Sendly from "@sendly/node";

const sendly = new Sendly(process.env.SENDLY_API_KEY!);

const msg = await sendly.messages.send({ to: "+15551234567", text: "Hello!", messageType: "transactional" });
const scheduled = await sendly.messages.schedule({ to: "+15551234567", text: "Later!", messageType: "transactional", scheduledAt: "2026-04-01T14:00:00Z" });
const batch = await sendly.messages.batch({ messages: [{to: "+15551234567", text: "Hi"}], messageType: "transactional" });
const list = await sendly.messages.list({ limit: 50 });
const single = await sendly.messages.get("msg_abc123");

短信类型

• transactional：一次性密码（OTP）、订单确认、预约提醒、账户通知等。允许全天候发送（24/7）。
• marketing：促销信息、销售活动、新闻简报等。受静默时段限制（收件人本地时间晚 9 点至早 8 点）。

将 marketing 类型误标为 transactional 类型，将违反《电话消费者保护法案》（TCPA）。

沙盒测试

使用以 sk_test_* 开头的密钥，并配合以下魔术号码进行测试：

信用额度消耗

• 美国 / 加拿大：每条短信 2 个信用额度（$0.02）
• 国际短信：按国家不同而异（2–48 个信用额度）
• 1 个信用额度 = $0.01

会话 API（Conversations API）

短信将自动归入对应会话（Conversation）。如需支持双向通信，请使用 Conversations API：

const convos = await sendly.conversations.list({ status: "active", limit: 20 });
const replies = await sendly.conversations.suggestReplies("conv_abc123");

完整参考文档

• API 文档：https://sendly.live/docs/sms
• SDK 文档：https://sendly.live/docs/sdks
• OpenAPI 规范：https://sendly.live/openapi.yaml
• 沙盒文档：https://sendly.live/docs/sandbox