邮件推送 API 对接指南与开发文档

5 分钟完成邮件推送 API 对接

🔌 方式一：RESTful API（推荐）

通过 HTTP POST 请求调用发送接口，简单直接，适合所有编程语言。完整接口说明请以「API 接口文档」为准。

📌 接口基础信息

• 接口地址：/api/send.php（仅支持 POST，GET 无效）
• 请求方式：POST
• Content-Type：application/json（必须）
• 请求头：Authorization: Bearer 你的API_Key（Bearer 后必须有一个英文空格）

📦 请求字段说明

字段名	必填	类型	说明
to_email	✅	String	收件人邮箱
subject	✅	String	邮件标题
message	✅	String	简单模式正文 / 模板模式占位（建议填“占位”）
template_id	❌	String	模板标识（如 verify_code、order_paid）
data	❌	Object	模板变量集合（必须嵌套传入）
from_name	❌	String	发件人名称

✅ 发送示例（模板模式）

POST /api/send.php
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "to_email": "user@example.com",
  "subject": "验证码",
  "message": "占位",
  "template_id": "verify_code",
  "data": {
    "code": "123456",
    "expire_sec": "300"
  }
}

✅ PHP (cURL) 调用示例

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "/api/send.php");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "to_email" => "user@example.com",
    "subject" => "验证码",
    "message" => "占位",
    "template_id" => "verify_code",
    "data" => ["code" => "123456"]
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

⚠️ 两个关键约定

• 模板变量必须放进 data 对象：平级传参会失败，正确写法是 {"data": {"code": "123456"}}。
• 200 不代表已送达：200 仅代表校验通过并成功进入发送队列，邮件由后台 Worker 异步投递。

核心 API 接口

• /api/send.php —— 单封邮件发送（推荐）
• /api/send_multi.php —— 批量邮件发送（群发请使用用户中心「群发邮件」功能，系统通过 Redis 队列异步发送）

返回码说明

错误码	含义	排查步骤
200	成功（已入队）	等待队列发送，检查 SMTP 日志
400	参数错误	检查 to_email / subject / message 是否为空；检查 data 是否为对象
401	API Key 无效	检查 Key 是否正确；检查 Bearer 后是否有空格
402	余额不足	前往控制台充值
404	模板不存在	检查 template_id 是否拼写错误；确认后台模板是否存在
429	请求过快	限制为 30 次 / 分钟，请降低频率
409	SMTP 冷却中	当前 SMTP 账号处于冷却期，请稍后重试
500	服务器错误	联系管理员，检查 SMTP 配置 / 数据库

🔒 安全认证

所有 API 调用需在请求头中传递 API Key（Authorization: Bearer 你的API_Key）。支持 IP 白名单绑定，单 Key 每分钟限 30 次请求。

查看完整 API 接口文档 → | 查看常见问题 → | 查看价格方案 →