开发文档

开放平台发信使用请求头 X-Api-Key 与 X-Api-Secret ，对应数据库字段 tb_apikey.apiKey / apiSecret；不使用 Authorization。工作台 Web 发信需在登录态下传入 apiKeyId 并使用 JWT。下文与服务端 Joi 及统一 JSON 信封一致。

快速开始

基础地址由部署环境决定，本站当前 API 根路径示例为：https://api.senddash.app（与 Nuxt public API_BASE_URL 一致）。

统一响应 JSON

成功：code === 0， message 一般为 success，业务数据在 data。失败：code 为非 0（常与 HTTP 状态一致），可读说明在 message，补充字段可选在 data。

// 成功
{
  "code": 0,
  "data": { /* 业务数据 */ },
  "message": "success"
}

// 失败（示例）
{
  "code": 400,
  "data": {},
  "message": "参数校验失败说明"
}

获取 API Key 与 Secret

工作台「API Key 管理」新建、或首页「接入指南」中 POST /users/send-key（需同意条款）：将生成成对的 apiKey（前缀 sd_）与 apiSecret（前缀 ss_）。对外开放发信时必须同时带上请求头 X-Api-Key （值为 apiKey）与 X-Api-Secret （值为 apiSecret）；不包含 Authorization。成功时响应体 data 会含 apiKey 与 apiSecret（并会邮件抄送）；列表类接口仍不返回 Secret。

前往首页接入指南

工作台 Web 发信（JWT）

已登录用户可调用 POST /users/emails/send：Authorization: Bearer <登录 JWT>， Body 必填 apiKeyId（整数，归属当前用户的凭证行 id），服务端在库内匹配密钥并发信，无需在浏览器传入 Secret。支持与开放接口相近的收件人、主题、正文、分组等字段（详见工作台「发送邮件」页的请求）。

开放接口 · 邮件推送

POST

路径与鉴权头

POST /v1/emails/send — 固定路径，无须在 URL 中传递批次 id。

请求头	必填	说明
X-Api-Key	是	与库字段 apiKey 相同（常为 sd_…）；勿放入 Authorization。
X-Api-Secret	是	与库字段 apiSecret 相同（常为 ss_…）；禁止写入前端可见代码或开源仓库。
Content-Type	是	application/json（与 JSON Body 同时使用）。

https://api.senddash.app/v1/emails/send

Body 使用 JSON。emails 与 groups 至少填写其一；单次收件人上限由常量控制（当前为 10000）。支持纯文本 TEXT、HTML 与模板 TPL。

请求体字段（application/json）

参数名	类型	必选	描述
emails	string[]	条件	收件人邮箱。与 groups 二者至少选一；每项须为合法邮箱；单次合并后总人数不超过 10000。
groups	number[]	条件	当前用户名下的客户分组 id。服务端展开分组内联系人邮箱后再发送。
subject	string	否	主题；服务端截断至多 50 个字符用于发信（Joi）。
contentType	string	否	TEXT \| HTML \| TPL；默认 TEXT。
content	string	条件	当 contentType 为 TEXT / HTML 时必填；正文最大约 50000 字符（Joi）；TPL 模式下可不填或由模板产出正文。
params	object	条件	TPL 时必填对象，至少含 templateId；可含模板变量键值；非 TPL 可为空对象（默认 {}).
templateId	number \| string	否	非 TPL 时可选：写入发件日志中的模板关联字段；不改变正文渲染路径。
recordLog	boolean	否	是否在 tb_email 中落库每一笔投递尝试；开放平台默认 false，示例中为 true 便于调试。

TPL（模板邮件）

设置 contentType: "TPL" 时，须在 params 对象中提供 templateId（正整数或可解析为整数的字符串）；其余键为模板 Mustache 变量。此时对 content 不作为正文必填。

请求示例：cURL（TEXT）

curl -X POST 'https://api.senddash.app/v1/emails/send' \
-H 'X-Api-Key: 您的_API_KEY' \
-H 'X-Api-Secret: 您的_API_SECRET' \
-H 'Content-Type: application/json' \
-d '{
  "emails": ["user@example.com"],
  "contentType": "TEXT",
  "subject": "报警通知：服务器负载过高",
  "content": "服务器 node-01 的 CPU 使用率已达到 95%，请立即排查。",
  "recordLog": true
}'

请求示例：Node.js fetch

const response = await fetch('https://api.senddash.app/v1/emails/send', {
method: 'POST',
headers: {
  'X-Api-Key': '您的_API_KEY',
  'X-Api-Secret': '您的_API_SECRET',
  'Content-Type': 'application/json'
},
body: JSON.stringify({
  emails: ['user@example.com'],
  contentType: 'TEXT',
  subject: '报警通知：服务器负载过高',
  content: '服务器 node-01 的 CPU 使用率已达到 95%，请立即排查。',
  recordLog: true
})
});

const envelope = await response.json();
console.log(envelope);

成功响应示例

data.results为逐收件人投递结果数组，元素至少含收件人与 status（SUCCESS / FAILED）。

{
  "code": 0,
  "data": {
    "results": [
      {
        "recipient": "user@example.com",
        "status": "SUCCESS"
      }
    ]
  },
  "message": "success"
}

错误与排查

HTTP 失败时通常为 4xx / 5xx；响应 JSON 仍会带 code 与 message。若返回 401，请核对是否同时传入非空的 X-Api-Key与 X-Api-Secret（与服务端存的键值完全一致），凭证状态为 ACTIVE，且未错误使用 Bearer。

HTTP	典型原因	处理建议
400	JSON 无效、字段不满足 Joi（如收件人为空、TPL 缺 templateId、主题/正文超限等）。	对照本文请求体表格与服务端错误 message 逐项修正 Body。
401	未带或未正确传递 X-Api-Key / X-Api-Secret，或与库中记录不一致；凭证状态非 ACTIVE。	创建后仅存一份 Secret；检查 Header 名大小写与环境 Base URL（路径应为 /v1/emails/send）。勿使用 Bearer。
500	下游邮路或部分内容渲染失败（如部分收件人 FAILED）。	查看响应 data.results 中单条失败原因；必要时稍后重试或联系运维。