短信 API 文档
翼星科技短信平台 REST API，支持验证码、通知、营销短信。国内三网合一，5 秒送达，99%+ 到达率。
API 版本 v1 Base URL: https://api.esnlink.cn/v1
概述
所有接口采用 HTTPS POST，请求与响应均为 JSON 格式，字符编码 UTF-8。
| 环境 | 地址 |
|---|---|
| 生产环境 | https://api.esnlink.cn/v1 |
| 沙箱环境 | https://sandbox.esnlink.cn/v1 |
鉴权方式
每次请求需携带以下公共参数：
| 参数 | 类型 | 说明 |
|---|---|---|
| app_id | string | 控制台获取的应用 ID |
| timestamp | int | Unix 时间戳（秒），误差不超过 300 秒 |
| sign | string | 签名，见下方算法 |
签名算法
sign = MD5(app_id + timestamp + app_secret)将 app_secret 妥善保管，切勿写入前端代码或公开仓库。
发送短信
POST /sms/send
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| mobile | string | 是 | 手机号，多个用英文逗号分隔，最多 200 个 |
| template_id | string | 是 | 已审核通过的模板 ID |
| params | object | 否 | 模板变量，如 {"code":"123456"} |
| sign_name | string | 是 | 短信签名，如【翼星科技】 |
响应示例
{
"code": 0,
"message": "success",
"data": {
"msg_id": "20260718120000123456",
"count": 1
}
}状态回调
在控制台配置 callback_url 后，短信状态变更时向该地址 POST 推送：
{
"msg_id": "20260718120000123456",
"mobile": "13800138000",
"status": "DELIVERED",
"deliver_time": "2026-07-18 12:00:05"
}状态值：SENT 已发送 · DELIVERED 已送达 · FAILED 失败
错误码
| code | 说明 |
|---|---|
| 0 | 成功 |
| 1001 | 签名错误 |
| 1002 | 时间戳过期 |
| 2001 | 手机号格式错误 |
| 2002 | 模板不存在或未审核 |
| 3001 | 余额不足 |
| 5000 | 系统繁忙，请重试 |
代码示例
cURL
curl -X POST https://api.esnlink.cn/v1/sms/send \
-H "Content-Type: application/json" \
-d '{
"app_id": "your_app_id",
"timestamp": 1721289600,
"sign": "生成的MD5签名",
"mobile": "13800138000",
"template_id": "TPL_VERIFY_001",
"sign_name": "翼星科技",
"params": {"code": "123456"}
}'Python
import hashlib, time, requests
APP_ID = "your_app_id"
APP_SECRET = "your_app_secret"
ts = int(time.time())
sign = hashlib.md5(f"{APP_ID}{ts}{APP_SECRET}".encode()).hexdigest()
resp = requests.post("https://api.esnlink.cn/v1/sms/send", json={
"app_id": APP_ID,
"timestamp": ts,
"sign": sign,
"mobile": "13800138000",
"template_id": "TPL_VERIFY_001",
"sign_name": "翼星科技",
"params": {"code": "123456"}
})
print(resp.json())PHP
$appId = "your_app_id";
$secret = "your_app_secret";
$ts = time();
$sign = md5($appId . $ts . $secret);
$data = [
"app_id" => $appId,
"timestamp" => $ts,
"sign" => $sign,
"mobile" => "13800138000",
"template_id" => "TPL_VERIFY_001",
"sign_name" => "翼星科技",
"params" => ["code" => "123456"]
];
$ch = curl_init("https://api.esnlink.cn/v1/sms/send");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);常见问题
短信 API 如何鉴权？
使用 AppID + AppSecret 生成 MD5 签名，每次请求携带 sign、timestamp、app_id 参数。
验证码短信多久能到达？
国内三网短信通常 5 秒内到达，到达率 99%+。
是否支持状态回调？
支持。在控制台配置 callback_url，短信状态变更时 POST 推送回执。