AutoSend

AutoSend Email API

通过 REST API 发送事务性邮件、管理联系人并使用模板。

使用 JavaScript/TypeScript？ 请参阅 SDK 指南，了解使用 autosendjs 软件包的 TypeScript 示例。

参考： API 指南 | 官方 API 参考

先决条件

使用 API 前，请完成以下步骤：

• 创建账户 — 在 autosend.com 注册
• 添加域名 — Settings → Domains → Add Domain → 选择 AWS 区域（文档）
• 配置 DNS — 将生成的记录（DKIM、SPF、DMARC）复制到 DNS 提供商
• 验证域名 — 点击“Verify Ownership”，并等待状态变为绿色（5-30 min）
• 获取 API 密钥 — Settings → API Keys → Generate API Key（文档）
• 设置环境变量 — export AUTOSEND_API_KEY=as_your_key_here

---

身份验证

所有请求都需要在 Authorization 标头中提供 Bearer 令牌：

Authorization: Bearer YOUR_API_KEY

基础 URL： https://api.autosend.com/v1

所有 POST/PUT 请求都必须包含 Content-Type: application/json。

---

邮件操作

发送邮件

POST /v1/mails/send

发送一封事务性邮件。

参数	类型	必填	说明
from	object	是	发件人 — { "email": "...", "name": "..." }
to	object	是	收件人 — { "email": "...", "name": "..." }
subject	string	是	邮件主题
html	string	否	HTML 正文
text	string	否	纯文本正文
templateId	string	否	模板 ID（替代 html/text）
dynamicData	object	否	模板变量替换值
cc	array	否	抄送收件人 — [{ "email": "...", "name": "..." }]
bcc	array	否	密送收件人 — [{ "email": "...", "name": "..." }]
replyTo	object	否	回复地址 — { "email": "...", "name": "..." }
attachments	array	否	文件附件 — [{ "filename": "...", "content": "..." }]

响应：

{
  "success": true,
  "data": { "emailId": "email_abc123" }
}

---

批量发送

POST /v1/mails/bulk

向多个收件人发送邮件，共用发件人、主题和可选模板。

参数	类型	必填	说明
from	object	是	共享发件人 — { "email": "...", "name": "..." }
subject	string	否	共享主题（除非模板提供主题，否则为必填）
html	string	否	共享 HTML 正文
text	string	否	共享纯文本正文
templateId	string	否	模板邮件的模板 ID
dynamicData	object	否	共享的默认模板变量
recipients	array	是	收件人对象数组（最多 100 个）

收件人对象：

参数	类型	必填	说明
email	string	是	收件人邮箱地址
name	string	否	收件人显示名称
dynamicData	object	否	每位收件人的变量（覆盖共享变量）
cc	array	否	每位收件人的抄送对象
bcc	array	否	每位收件人的密送对象

限制： 每个批量请求最多包含 100 位收件人。

响应：

{
  "success": true,
  "data": {
    "batchId": "batch_abc123",
    "totalRecipients": 2,
    "successCount": 2,
    "failedCount": 0
  }
}

---

模板

POST /v1/mails/send，并传入 templateId

传入 templateId 和 dynamicData，即可发送模板邮件，替代或搭配 html/text 使用。

参数	类型	必填	描述
templateId	string	是	模板标识符
dynamicData	object	否	模板变量的键值对

常见模板 ID：

模板	ID	常用变量
订单确认	tmpl_order_confirmation	orderNumber、customerName、orderTotal、estimatedDelivery
欢迎邮件	tmpl_welcome	firstName、activationLink、supportEmail
密码重置	tmpl_password_reset	resetLink、expiresIn

模板也支持批量发送——在批量请求正文中传入 templateId 和 dynamicData。

---

联系人管理

创建联系人

POST /v1/contacts

参数	类型	必填	描述
email	string	是	联系人的电子邮件地址
firstName	string	否	联系人的名字
lastName	string	否	联系人的姓氏
userId	string	否	外部用户 ID
listIds	array	否	要添加联系人的列表 — ["list_abc", "list_xyz"]
customFields	object	否	自定义字段值

响应：

{
  "success": true,
  "data": {
    "id": "contact_abc123",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "listIds": ["list_abc"],
    "customFields": {},
    "createdAt": "2025-01-15T00:00:00Z",
    "updatedAt": "2025-01-15T00:00:00Z"
  }
}

---

获取联系人

GET /v1/contacts/:id

参数	类型	必填	描述
id	string	是	联系人 ID（路径参数）

响应： 返回联系人对象（结构与创建联系人响应相同）。

---

新建或更新联系人

POST /v1/contacts/email

通过电子邮件地址创建或更新联系人。如果已存在具有给定电子邮件地址的联系人，则更新该联系人；否则创建新联系人。

参数	类型	必填	描述
email	string	是	联系人的电子邮件地址
firstName	string	否	联系人的名字
lastName	string	否	联系人的姓氏
userId	string	否	外部用户 ID
listIds	array	否	要添加联系人的列表
customFields	object	否	自定义字段值

响应： 返回联系人对象（结构与创建联系人响应相同）。

---

删除联系人

DELETE /v1/contacts/:id

参数	类型	必填	描述
id	string	是	联系人 ID（路径参数）

响应：

{
  "success": true
}

---

错误处理

所有错误均以包含 error 对象的 JSON 格式返回：

{
  "success": false,
  "error": {
    "message": "The 'to' field is required",
    "code": "VALIDATION_FAILED",
    "details": []
  }
}

状态	代码	描述
400	VALIDATION_FAILED	请求错误 — 缺少参数或参数无效
401	UNAUTHORIZED	API 密钥无效或缺失
402	PAYMENT_REQUIRED	需要升级套餐
403	FORBIDDEN	权限不足
404	NOT_FOUND	未找到资源
429	RATE_LIMIT_EXCEEDED	请求过多 — 请等待一段时间后重试
500	SERVER_ERROR	服务器内部错误