云

云脉通信

连接品牌与用户的每一次沟通

API查看完整示例

开发者 API 文档

云脉通信提供联系人、群组、短信、彩信、账户等 REST 接口，统一 API Key 鉴权与 JSON 负载，支持回执回调。

Base setup

Base URLhttps://smsapi.lunaaaa.com/api
AuthAuthorization: Api-Key {api_key}
AcceptAccept: application/json
Content-TypeContent-Type: application/json
仅支持 HTTPS + UTF-8 JSON，请在控制台 API Keys 生成 API Key。
每个请求都需携带 Api-Key 头部，禁止将 key 放在 query 中。
文档中的 cURL 示例可直接验证连通性。
响应里的 uid 与 message_id 用于后续查询与回执关联，如泄露请在控制台吊销并重建。

快速上手

1) 获取 API Key

在控制台创建 API Key，妥善保存；所有 HTTP 调用均需此鉴权。

快速上手

2) 新建联系人与群组

使用 POST /api/http/v3/v3/contacts/{group_id}/store 通过 Api-Key 鉴权把号码加入群组。

快速上手

3) 发送第一条短信

POST /api/http/v3/http/sms/send，传 recipient、sender_id、type=plain、message，可附 schedule_time。

鉴权与基础信息

所有接口共用一个域名与 API Key 鉴权；联系人、群组、短信、彩信保持统一头部。

ANY/api/http/v3/{resource}

通用请求格式

使用 HTTPS + API Key 与 JSON，编码统一为 UTF-8。

Headers

AuthorizationApi-Key {api_key}

每个请求必填

Acceptapplication/json

指定 JSON 返回

Content-Typeapplication/json

POST/PUT/PATCH 时指定 JSON

Notes

  • API Key 在控制台创建并长期有效，可随时吊销或重建。
  • 非 200 返回包含 status 与 message，便于排查。

联系人 API

以唯一 ID 管理联系人，可带姓名与自定义字段；联系人归属群组便于复用。

GET/api/http/v3/http/contacts

查询联系人

分页返回联系人，可按群组过滤。

Headers

AuthorizationApi-Key {api_key}

控制台生成的 API Key

Acceptapplication/json

JSON 返回

Parameters

group_idOptional

string

可选群组 uid 过滤

pageOptional

number

分页页码

Notes

  • 成功时返回 status=success 与分页后的联系人数据。
POST/api/http/v3/v3/contacts/{group_id}/store

创建联系人

向指定群组新增联系人，返回创建后的对象。

Headers

AuthorizationApi-Key {api_key}

必填

Content-Typeapplication/json

JSON 请求体

Acceptapplication/json

JSON 返回

Parameters

group_idRequired

string

目标群组 uid

phoneRequired

string/number

国际号码格式的 MSISDN

first_nameOptional

string

名字，可选

last_nameOptional

string

姓氏，可选

Notes

  • 示例返回：{ status: "success", data: { ...contact } }。
  • 错误示例：{ status: "error", message: "可读错误信息" }。

cURL

curl -X POST \
  https://smsapi.lunaaaa.com/api/api/http/v3/v3/contacts/{group_id}/store \
  -H "Authorization: Api-Key YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"phone":"8801721970168","first_name":"Amy"}'

JSON

{
  "status": "success",
  "data": {
    "uid": "c_01hxyz",
    "group_uid": "g_01hgroup",
    "phone": "8801721970168",
    "first_name": "Amy",
    "last_name": null
  }
}

群组 API

用于组织联系人，便于批量发送与分层运营。

GET/api/http/v3/http/contact-groups

查询群组

分页返回群组列表，uid 可用于成员和发送操作。

Headers

AuthorizationApi-Key {api_key}

必填

Acceptapplication/json

JSON 返回

POST/api/http/v3/v3/contacts

创建群组

创建群组并返回 uid，后续添加联系人或群发均需此值。

Headers

AuthorizationApi-Key {api_key}

必填

Content-Typeapplication/json

JSON 请求体

Acceptapplication/json

JSON 返回

Parameters

nameRequired

string

群组名称，出现在控制台与 API 返回中

descriptionOptional

string

群组备注，可选

Notes

  • 请保存返回的 uid，添加联系人或发送到群组时需要该值。

短信 API

通过 REST 发送全球短信，返回唯一 message_id 便于查询或接收回执。

POST/api/http/v3/http/sms/send

发送短信

创建外呼短信，支持批量、定时与模板变量。

Headers

AuthorizationApi-Key {api_key}

必填

Content-Typeapplication/json

JSON 请求体

Acceptapplication/json

JSON 返回

Parameters

recipientRequired

string

单个或用逗号分隔的号码列表

sender_idRequired

string

字母数字发件人（最长 11 位）或号码

typeRequired

string

短信类型，文本填写 plain

messageRequired

string

短信内容

schedule_timeOptional

datetime

RFC3339 时间 (Y-m-d H:i) 定时发送

dlt_template_idOptional

string

需 DLT 时填写注册的模板 ID

Notes

  • 成功返回 status=success 与 message_id，用于查询或回执匹配。
  • 多个号码用逗号分隔即可批量发送。

cURL

curl -X POST \
  https://smsapi.lunaaaa.com/api/api/http/v3/http/sms/send \
  -H "Authorization: Api-Key YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
              -d '{"recipient":"31612345678,8801721970168","sender_id":"CloudMessaging","type":"plain","message":"你好，来自 API 的短信"}'

JSON

{
  "status": "success",
  "message_id": "msg_01hxabc123",
  "queued": true
}

彩信 API

发送带媒体内容的彩信，沿用相同的鉴权与 JSON 结构，需提供可访问的媒体 URL。

POST/api/http/v3/http/mms/send

发送彩信

发送带媒体的彩信，返回 message_id 便于送达跟踪。

Headers

AuthorizationApi-Key {api_key}

必填

Content-Typeapplication/json

JSON 请求体

Acceptapplication/json

JSON 返回

Parameters

recipientRequired

string

单个或逗号分隔的号码列表

sender_idRequired

string

地区支持的发件人

media_urlRequired

string

可访问的媒体资源 URL

messageOptional

string

可选的文字说明

cURL

curl -X POST \
  https://smsapi.lunaaaa.com/api/api/http/v3/http/mms/send \
  -H "Authorization: Api-Key YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
              -d '{"recipient":"31612345678","sender_id":"CloudMessaging","media_url":"https://example.com/promo.jpg","message":"优惠详情请查看图片"}'

JSON

{
  "status": "success",
  "message_id": "mms_01hxghi789"
}

账户与资料

在自动化前查询账户资料、余额与策略上限，降低发送风险。

GET/api/http/v3/http/profile

获取账户资料

返回账户信息、余额与策略元数据，便于预检与风控。

Headers

AuthorizationApi-Key {api_key}

必填

Acceptapplication/json

JSON 返回

Notes

  • 大批量发送前先检查余额和限额。
  • 结合 message_id 回执对账计费与送达。

回执与回调

配置回调 URL 后会以 POST 推送回执；返回 200 视为接收成功，超时或非 200 会按退避策略重试。

message_id

消息唯一 ID，用于对账和查询

status

送达状态（success/failed/queued/throttled 等）

timestamp

事件时间戳

reason

失败或拦截原因（如有）

  • 建议使用 HTTPS，快速返回 HTTP 200 以避免重试。
  • 非 200 或超时会自动重试，遵循文档的退避策略。

常见错误码

401

API Key 缺失/无效

在控制台创建或重新生成 API Key，并放入 Authorization 头

403

无权限或产品未开通

在控制台开通或联系支持开权限

429

触发限频/限速

降低突发流量或申请更高配额

422

参数或内容不符合要求

检查必填字段、编码、模板/内容要求

更多错误码、示例负载与 SDK 见完整文档。

参考链接

  • 完整的参数表、示例 payload 与 SDK 代码可在托管文档查看。
查看完整示例
Telegram