API 接口文档（超详细 · 防呆级

✅ 概念一：什么是 `template_id`（最重要）

📌 template_id ≠ 邮件标题
📌 template_id ≠ 模板名称
📌 template_id 是后台“邮件模板”里的【模板标识】字段

它由管理员在后台添加模板时手动填写
一旦填写，不可随意更改
调用 API 时必须一字不差地传

✅ 概念二：什么是 `data`（最容易错）

📌 所有模板变量，必须放在 data 对象里。

❌ 错误（平级传参，必失败）：
{ "order_no": "123", "price": "99" }

✅ 正确（嵌套传参，必成功）：
{ "data": { "order_no": "123", "price": "99" } }

✅ 概念三：什么是“已进入发送队列”（200 的真正含义）

📌 200 ≠ 对方已收到邮件

200 仅代表：
① API 校验通过
② 邮件任务成功进入 Redis 队列
③ Worker 会在后台异步发送

实际是否送达，取决于 SMTP 账号、收件邮箱反垃圾策略、网络等。

以下 template_id 为系统默认标识，请在后台“邮件模板”中确认是否存在：

template_id	用途	常见场景	Status
`verify_code`	邮箱验证码	注册 / 登录 / 找回密码	核心
`order_created`	订单提交成功	下单未支付提醒	常用
`order_paid`	订单支付成功	商城支付回调	核心
`order_shipped`	发货通知	ERP / 后台发货	常用
`order_completed`	订单已完成	服务 / 虚拟商品交付	常用
`refund_success`	退款成功	售后退款	常用
`balance_change`	账户余额变动	充值 / 消费 / 退款	常用
`customer_reply`	客服回复通知	工单系统回复	常用
`service_expire_warning`	服务即将到期	会员 / 服务续费提醒	常用
`default`	兜底模板	template_id 写错时使用	必填

⚠️ 如果调用时传入的 template_id 不存在，且 default 模板也不存在，API 将返回 404 模板不存在。

接口地址：

https://api.rabshop.cn/api/send.php

请求方式：POST（仅支持 POST，GET 无效）

Content-Type：application/json（必须）

请求头（每次请求必须带）：

Authorization: Bearer YOUR_API_KEY_HERE

✅ Bearer 后面必须有一个英文空格。
❌ 错误：Authorization:Bearer xxx
✅ 正确：Authorization: Bearer xxx

你的 API Key： 请登录后查看

YOUR_API_KEY_HERE

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

⚠️ 当传入 template_id 时，message 字段仅用于数据库日志备份，邮件正文以模板渲染结果为准。

模式一：简单模式（不推荐，仅测试）
- 不使用模板
- 直接发送 message
- 适合：临时测试、纯文本通知

{
  "to_email": "test@example.com",
  "subject": "测试邮件",
  "message": "这是一封测试邮件"
}

模式二：模板模式（✅ 强烈推荐，生产必用）
- 使用 template_id
- 所有变量放在 data 对象中
- 适合：订单、验证码、退款、发货

✅ 验证码模板

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

✅ 订单提交成功

{
  "to_email": "user@example.com",
  "subject": "订单提交成功通知",
  "message": "占位",
  "template_id": "order_created",
  "from_name": "客服中心",
  "data": {
    "username": "张三",
    "order_no": "ORD20260121001",
    "product_name": "VIP年卡",
    "amount": "399.00",
    "create_time": "2026-01-21 17:00",
    "pay_url": "https://example.com/pay?order_id=ORD20260121001"
  }
}

✅ 订单支付成功

{
  "to_email": "user@example.com",
  "subject": "订单支付成功",
  "message": "占位",
  "template_id": "order_paid",
  "from_name": "客服中心",
  "data": {
    "order_no": "ORD20260121001",
    "product_name": "VIP年卡",
    "price": "399.00",
    "status_text": "支付成功"
  }
}

✅ 发货通知

{
  "to_email": "user@example.com",
  "subject": "发货通知",
  "message": "占位",
  "template_id": "order_shipped",
  "data": {
    "order_no": "ORD20260121001",
    "express": "顺丰速运",
    "tracking_no": "SF123456"
  }
}

✅ 订单已完成

{
  "to_email": "user@example.com",
  "subject": "订单已完成通知",
  "message": "占位",
  "template_id": "order_completed",
  "from_name": "客服中心",
  "data": {
    "username": "张三",
    "order_no": "ORD20260121001",
    "product_name": "VIP年卡",
    "amount": "399.00",
    "finish_time": "2026-01-21 18:00"
  }
}

✅ 退款成功

{
  "to_email": "user@example.com",
  "subject": "退款通知",
  "message": "占位",
  "template_id": "refund_success",
  "data": {
    "order_no": "ORD20260121001",
    "refund_amount": "99.00",
    "arrive_time": "1-3个工作日"
  }
}

✅ 用户：退款申请已提交（申请阶段）

📌 用户提交退款申请后 立即发送，不等后台审核。
📌 对应 template_id：order_refund_apply_user

{
  "to_email": "user@example.com",
  "subject": "退款申请已提交",
  "message": "占位",
  "template_id": "order_refund_apply_user",
  "from_name": "客服中心",
  "data": {
    "username": "张三",
    "order_no": "ORD20260121001",
    "product_name": "VIP年卡",
    "refund_amount": "99.00",
    "apply_time": "2026-01-21 19:30"
  }
}

✅ 客服：新退款申请待处理（申请阶段）

📌 用户一提交申请，客服立刻收到。
📌 用于提醒客服尽快审核。
📌 对应 template_id：order_refund_apply_admin

{
  "to_email": "kefu@example.com",
  "subject": "新退款申请待处理",
  "message": "占位",
  "template_id": "order_refund_apply_admin",
  "from_name": "系统通知",
  "data": {
    "order_no": "ORD20260121001",
    "product_name": "VIP年卡",
    "refund_amount": "99.00",
    "apply_time": "2026-01-21 19:30"
  }
}

✅ 账户余额变动

{
  "to_email": "user@example.com",
  "subject": "账户余额变动通知",
  "message": "占位",
  "template_id": "balance_change",
  "from_name": "客服中心",
  "data": {
    "username": "张三",
    "change_type": "充值",
    "amount": "+100.00",
    "amount_class": "income",
    "balance": "488.00",
    "time": "2026-01-21 14:30"
  }
}

✅ 客服回复通知

{
  "to_email": "user@example.com",
  "subject": "客服回复通知",
  "message": "占位",
  "template_id": "customer_reply",
  "from_name": "客服中心",
  "data": {
    "username": "张三",
    "ticket_id": "TK20260121001",
    "reply_time": "2026-01-21 15:30",
    "reply_content": "您好，问题已处理完毕，当前通道已恢复正常。"
  }
}

✅ 服务即将到期提醒

{
  "to_email": "user@example.com",
  "subject": "服务即将到期提醒",
  "message": "占位",
  "template_id": "service_expire_warning",
  "from_name": "客服中心",
  "data": {
    "username": "张三",
    "expire_time": "2026-02-21 23:59",
    "days_left": "7",
    "renew_url": "https://example.com/user/service"
  }
}

✅ PHP (cURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.rabshop.cn/api/send.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_API_KEY_HERE'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'to_email' => 'test@example.com',
    'subject' => '测试',
    'message' => '占位',
    'template_id' => 'verify_code',
    'data' => ['code' => '123456']
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

✅ Python (requests)

import requests
url = 'https://api.rabshop.cn/api/send.php'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY_HERE'
}
data = {
    "to_email": "test@example.com",
    "subject": "测试",
    "message": "占位",
    "template_id": "verify_code",
    "data": {"code": "123456"}
}
response = requests.post(url, json=data, headers=headers)
print(response.json())

✅ Java (OkHttp)

OkHttpClient client = new OkHttpClient();
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
JSONObject data = new JSONObject();
data.put("to_email", "test@example.com");
data.put("subject", "测试");
data.put("message", "占位");
data.put("template_id", "verify_code");
JSONObject vars = new JSONObject();
vars.put("code", "123456");
data.put("data", vars);
RequestBody body = RequestBody.create(JSON, data.toString());
Request request = new Request.Builder()
    .url("https://api.rabshop.cn/api/send.php")
    .addHeader("Authorization", "Bearer YOUR_API_KEY_HERE")
    .post(body)
    .build();
client.newCall(request).enqueue(...);

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

✅ 为什么要用队列？

SMTP 发送很慢（2~5 秒 / 封）
如果 API 同步发送，用户会卡住
队列让 API 立即返回，后台慢慢发

✅ 什么是 SMTP 冷却？

📌 为了防止被邮箱服务商封号，系统会在以下情况自动冷却 SMTP 账号：

① 连续发送失败
② 达到频率限制
③ 账号被对方服务器限流

冷却期间，新任务会排队等待，不会丢失。

📌 QQ 邮箱会“静默丢弃”低质量邮件。
表现为：接口返回 200，但收件箱 / 垃圾箱都没有。

✅ 必须遵守的发送规范：

标题：必须带业务前缀，如【码农素材】。禁止单个词语。
正文：必须包含具体业务数据（订单号 / 金额）。禁止过于简单。
发件人：避免使用“商城 / 推广 / 营销”。推荐“XX客服中心”。
频率：同一邮箱发送间隔 ≥ 60 秒。

✅ 按规范发送，QQ 邮箱送达率可提升至 95%+。

✅ 模板用 template_id
✅ 变量全放 data 里
✅ 简单测试才用 message
✅ Bearer 后面有空格
✅ QQ 邮箱要规范
✅ 200 只是进队列

Q：返回 200，但只收到一个参数？

A：99% 是 data 没传，或变量没放进 data 对象。

Q：返回 404，提示模板不存在？

A：检查 template_id 是否和后台“模板标识”一字不差；确认 default 模板是否存在。

Q：QQ 邮箱收不到，其他邮箱正常？

A：见第九节。QQ 邮箱反垃圾最严，必须严格遵守规范。

Q：支持群发邮件吗？

A：✅ 支持，群发功能面向前台用户开放。
用户可在「群发邮件」中创建任务，系统通过 Redis 队列异步发送，支持批量导入收件人、失败自动重试、发送日志与成功率统计。

Q：Worker 没运行怎么办？

A：登录服务器执行 php mail/queue.php，或配置 Supervisor 守护进程。

Q：余额变动邮件里金额颜色不生效？

A：确保传入了 amount_class（income / expense），且模板未被转义。

Q：客服回复内容换行丢失？

A：模板中必须使用 white-space:pre-wrap，否则换行符会被折叠。

Q：服务到期提醒的续费链接点不开？

A：确保 renew_url 是完整 HTTP/HTTPS 地址，避免相对路径。

✅ 以下模板适用于：电商平台、SaaS 系统、企业后台、工单系统、财务系统、CRM、运维监控、会员订阅、协作工具等。

分类	template_id	用途说明	关键变量示例
🛒 订单交易	`order_created`	订单提交成功（待支付）	username, order_no, product_name, amount, pay_url
	`order_paid`	订单支付成功	order_no, product_name, price, pay_time
	`order_unpaid_close`	未支付订单自动关闭	order_no, close_reason, close_time
	`order_price_changed`	订单改价通知	order_no, old_amount, new_amount
	`order_shipped`	订单已发货	order_no, express, tracking_no, ship_time
	`order_delivered`	订单已签收	order_no, signer, sign_time
	`order_completed`	订单已完成	username, order_no, product_name, amount, finish_time
	`order_canceled`	订单已取消	username, order_no, cancel_reason, cancel_time
	`order_remark`	订单备注变更	order_no, remark, operator
	`order_partial_refund`	部分退款通知	order_no, refund_amount, remain_amount
	`order_auto_confirm`	系统自动确认收货	order_no, confirm_time
	`order_invoice_ready`	发票已开具	order_no, invoice_no, invoice_url
🛠 售后维权	`order_refund_apply_user`	退款申请已提交（用户）	username, order_no, product_name, refund_amount, apply_time
	`order_refund_apply_admin`	退款申请待处理（客服）	order_no, product_name, refund_amount, apply_time
	`refund_approved`	售后审核通过	order_no, refund_amount, audit_result
	`refund_rejected`	售后审核拒绝	order_no, reject_reason
	`refund_success`	退款成功	order_no, refund_amount, arrive_time
	`refund_failed`	退款失败	order_no, fail_reason
	`return_address`	退货地址通知	order_no, address, receiver, phone
	`return_received`	退货已签收	order_no, receive_time
	`exchange_shipped`	换货已重发	order_no, express, tracking_no
	`complaint_created`	投诉已受理	complaint_id, content
	`complaint_closed`	投诉已结案	complaint_id, result
🔐 账户安全	`verify_code`	邮箱验证码	code, expire_sec
	`register_success`	注册成功欢迎	username, register_time
	`bind_email`	绑定邮箱成功	username, email
	`unbind_email`	解绑邮箱通知	username, email
	`change_password`	密码修改成功	username, change_time
	`reset_password`	重置密码成功	username, reset_time
	`login_abnormal`	异常登录提醒	username, ip, location, time
	`device_login`	新设备登录提醒	username, device, ip, time
	`account_locked`	账号被锁定	username, lock_reason, unlock_time
	`account_unlocked`	账号解锁通知	username, unlock_time
	`permission_changed`	权限变更通知	username, role, change_desc
💰 资金财务	`balance_change`	余额变动	username, change_type, amount, balance
	`recharge_success`	充值成功	username, amount, pay_method
	`withdraw_apply`	提现申请提交	username, amount, fee
	`withdraw_success`	提现成功	username, amount, arrive_time
	`withdraw_failed`	提现失败	username, amount, fail_reason
	`invoice_apply`	发票申请提交	username, order_no, invoice_type
	`invoice_rejected`	发票申请驳回	username, reject_reason
	`settlement_success`	结算成功	username, settle_no, amount
	`commission_settled`	佣金结算通知	username, commission, level
	`bill_generated`	月度账单生成	username, bill_month, bill_url
🎁 优惠权益	`coupon_receive`	优惠券领取成功	username, coupon_name, amount
	`coupon_expire`	优惠券即将过期	username, coupon_name, expire_time
	`coupon_used`	优惠券已使用	username, coupon_name, order_no
	`points_change`	积分变动	username, change_type, points, balance
	`points_expire`	积分即将过期	username, expire_points, expire_time
	`vip_upgrade`	会员等级升级	username, new_level, expire_time
	`vip_expire_warning`	会员即将到期	username, days_left, renew_url
🎫 工单客服	`ticket_create`	工单提交成功	username, ticket_id, title
	`ticket_reply`	客服回复工单	username, ticket_id, reply_content
	`ticket_close`	工单已关闭	username, ticket_id, close_reason
	`ticket_reopen`	工单重新打开	username, ticket_id
	`ticket_assign`	工单指派通知	ticket_id, assignee
	`feedback_reply`	意见反馈回复	username, feedback_id, reply
	`survey_invite`	满意度调查邀请	username, survey_url
☁️ 订阅 / SaaS	`subscribe_success`	订阅成功	username, plan_name, expire_time
	`subscribe_renew`	订阅续费成功	username, plan_name, next_expire
	`subscribe_cancel`	订阅已取消	username, plan_name, cancel_time
	`trail_end`	试用即将结束	username, days_left
	`quota_warning`	配额不足预警	username, quota_type, used, total
	`quota_exceeded`	配额已超限	username, quota_type, upgrade_url
	`feature_release`	新功能发布通知	username, feature_name, desc
	`maintenance_notice`	系统维护通知	start_time, end_time, impact
👥 协作 / 企业	`invite_member`	邀请加入团队	inviter, team_name, invite_url
	`member_join`	成员加入通知	team_name, member_name
	`member_remove`	成员移除通知	team_name, member_name
	`role_change`	角色变更通知	username, new_role
	`project_invite`	项目协作邀请	project_name, inviter, invite_url
	`comment_notify`	评论 @ 通知	username, content, source_url
	`approval_notify`	审批结果通知	username, approval_type, result
🛡 风控 / 合规	`risk_warning`	风险操作预警	username, risk_type, ip, time
	`sensitive_op`	敏感操作提醒	username, op_type, verify_url
	`ip_blocked`	IP 被封禁	ip, block_reason, unblock_time
	`rate_limit`	接口限流警告	api, limit, retry_after
	`policy_update`	政策更新通知	policy_name, update_time, detail_url
	`data_export`	数据导出完成	username, export_type, download_url
	`backup_complete`	备份完成通知	backup_type, size, time
⚙️ 系统 / 运维	`server_alert`	服务器异常告警	server_ip, alert_type, level
	`ssl_expire_warning`	SSL 证书即将过期	domain, expire_days
	`task_fail`	定时任务失败	task_name, fail_reason, last_time
	`deploy_notify`	部署完成通知	version, env, deploy_time
	`queue_backlog`	队列堆积告警	queue_name, backlog_count
	`disk_alert`	磁盘空间告警	disk_path, usage_percent
🧑‍💼 客服收信	`order_created_admin`	新订单提醒（客服）	order_no, product_name, amount, create_time
	`order_paid_admin`	支付成功提醒（客服）	order_no, product_name, amount, pay_time
	`order_shipped_admin`	发货通知（客服）	order_no, express, tracking_no, ship_time
	`order_finished_admin`	订单完成通知（客服）	order_no, product_name, amount, finish_time
	`refund_apply_admin`	退款申请提醒（客服）	order_no, refund_amount, apply_time
	`order_cancel_admin`	订单取消提醒（客服）	order_no, cancel_reason, cancel_time
	`complaint_admin`	投诉/工单提醒（客服）	ticket_id, username, content, create_time
🚨 兜底	`default`	模板不存在时的兜底	template_id, raw_data

⚠️ 兜底模板非常重要：
当传入的 template_id 不存在时，系统将尝试使用 default 模板。
若 default 也不存在，API 将直接返回 404 模板不存在。

✅ 至此，你的邮箱推送系统已覆盖：
• 电商交易全流程
• 售后 / 退款 / 维权
• 账户安全 / 风控
• 财务 / 结算 / 发票
• 优惠券 / 积分 / 会员
• 工单 / 客服 / 满意度
• SaaS 订阅 / 配额 / 维护
• 团队协作 / 审批 / 评论
• 运维监控 / 告警 / 备份

几乎没有任何“想发却没模板”的场景。

✅ 以下模板适用于：CMS、博客、社区论坛、OA、HR、教育、医疗、物业、金融、IoT、营销系统等非电商场景。

📄 CMS / 内容系统

article_publish（文章发布通知）

{
  "to_email": "author@example.com",
  "subject": "文章发布成功",
  "message": "占位",
  "template_id": "article_publish",
  "data": {
    "article_title": "PHP 异步队列实战",
    "author": "张三",
    "publish_time": "2026-01-21 10:00",
    "article_url": "https://example.com/article/123"
  }
}

article_update（文章更新提醒）

{
  "to_email": "subscriber@example.com",
  "subject": "文章更新提醒",
  "message": "占位",
  "template_id": "article_update",
  "data": {
    "article_title": "PHP 异步队列实战",
    "update_time": "2026-01-22 14:00",
    "changelog": "新增 Redis 队列优化章节"
  }
}

comment_new（新评论通知）

{
  "to_email": "author@example.com",
  "subject": "收到新评论",
  "message": "占位",
  "template_id": "comment_new",
  "data": {
    "article_title": "PHP 异步队列实战",
    "commenter": "李四",
    "comment_content": "文章写得非常好，受益匪浅！"
  }
}

comment_reply（评论被回复）

{
  "to_email": "user@example.com",
  "subject": "有人回复了你的评论",
  "message": "占位",
  "template_id": "comment_reply",
  "data": {
    "parent_nickname": "张三",
    "reply_content": "谢谢支持，后续会继续更新。",
    "article_url": "https://example.com/article/123#comment-456"
  }
}

content_audit_reject（内容审核驳回）

{
  "to_email": "author@example.com",
  "subject": "内容审核未通过",
  "message": "占位",
  "template_id": "content_audit_reject",
  "data": {
    "content_type": "文章",
    "reject_reason": "包含违规外链，请修改后重新提交。",
    "audit_time": "2026-01-21 15:30"
  }
}

digest_weekly（周报推送）

{
  "to_email": "user@example.com",
  "subject": "本周精选内容推荐",
  "message": "占位",
  "template_id": "digest_weekly",
  "data": {
    "username": "张三",
    "week_range": "2026-01-15 ~ 2026-01-21",
    "article_list_html": "文章1
文章2"
  }
}

subscribe_confirm（订阅确认）

{
  "to_email": "user@example.com",
  "subject": "请确认你的订阅",
  "message": "占位",
  "template_id": "subscribe_confirm",
  "data": {
    "subscribe_email": "user@example.com",
    "confirm_url": "https://example.com/subscribe/confirm?token=abc123"
  }
}

💬 社区 / 论坛

thread_new（新帖子通知）

{
  "to_email": "user@example.com",
  "subject": "你关注的板块有新帖",
  "message": "占位",
  "template_id": "thread_new",
  "data": {
    "board_name": "技术交流",
    "thread_title": "Laravel 10 性能优化实践",
    "author": "王五"
  }
}

reply_at（@ 我的回复）

{
  "to_email": "user@example.com",
  "subject": "有人 @ 了你",
  "message": "占位",
  "template_id": "reply_at",
  "data": {
    "from_username": "赵六",
    "thread_title": "Laravel 10 性能优化实践",
    "reply_content": "@张三 这个方案非常棒，已在实际项目中验证。"
  }
}

private_message（私信通知）

{
  "to_email": "user@example.com",
  "subject": "收到一条新私信",
  "message": "占位",
  "template_id": "private_message",
  "data": {
    "from_user": "管理员",
    "message_preview": "关于您提交的工单，我们需要进一步核实……"
  }
}

ban_warn（禁言 / 封号警告）

{
  "to_email": "user@example.com",
  "subject": "账号处罚通知",
  "message": "占位",
  "template_id": "ban_warn",
  "data": {
    "username": "张三",
    "ban_reason": "多次发布违规广告",
    "ban_duration": "7 天"
  }
}

🏢 OA / 企业办公

attendance_remind（打卡提醒）

{
  "to_email": "employee@example.com",
  "subject": "上班打卡提醒",
  "message": "占位",
  "template_id": "attendance_remind",
  "data": {
    "username": "张三",
    "date": "2026-01-22",
    "work_start": "09:00"
  }
}

leave_apply（请假申请通知）

{
  "to_email": "leader@example.com",
  "subject": "新的请假申请待审批",
  "message": "占位",
  "template_id": "leave_apply",
  "data": {
    "applicant": "张三",
    "leave_type": "年假",
    "days": "3"
  }
}

leave_approve（请假审批结果）

{
  "to_email": "employee@example.com",
  "subject": "请假审批结果通知",
  "message": "占位",
  "template_id": "leave_approve",
  "data": {
    "approver": "李经理",
    "result": "已批准",
    "comment": "请做好工作交接"
  }
}

meeting_invite（会议邀请）

{
  "to_email": "staff@example.com",
  "subject": "会议邀请：Q1 季度复盘",
  "message": "占位",
  "template_id": "meeting_invite",
  "data": {
    "meeting_title": "Q1 季度复盘会议",
    "time": "2026-01-25 14:00",
    "location": "第一会议室",
    "join_url": "https://meet.example.com/q1-review"
  }
}

meeting_remind（会议开始前提醒）

{
  "to_email": "staff@example.com",
  "subject": "会议即将开始提醒",
  "message": "占位",
  "template_id": "meeting_remind",
  "data": {
    "meeting_title": "Q1 季度复盘会议",
    "start_in_minutes": "15"
  }
}

👤 HR / 招聘

resume_receive（简历投递成功）

{
  "to_email": "candidate@example.com",
  "subject": "简历投递成功",
  "message": "占位",
  "template_id": "resume_receive",
  "data": {
    "job_title": "PHP 高级工程师",
    "candidate_name": "张三"
  }
}

interview_invite（面试邀请）

{
  "to_email": "candidate@example.com",
  "subject": "面试邀请：PHP 高级工程师",
  "message": "占位",
  "template_id": "interview_invite",
  "data": {
    "interview_time": "2026-01-28 10:00",
    "address": "XX 大厦 18 楼会议室 A",
    "contact": "李女士 13800138000"
  }
}

offer_send（Offer 发放）

{
  "to_email": "candidate@example.com",
  "subject": "恭喜您获得 Offer",
  "message": "占位",
  "template_id": "offer_send",
  "data": {
    "position": "PHP 高级工程师",
    "salary": "25K-30K",
    "onboard_date": "2026-02-10"
  }
}

contract_expire（合同到期提醒）

{
  "to_email": "hr@example.com",
  "subject": "员工合同即将到期",
  "message": "占位",
  "template_id": "contract_expire",
  "data": {
    "username": "张三",
    "contract_end": "2026-03-31",
    "renew_url": "https://hr.example.com/contract/renew/123"
  }
}

🎓 教育 / 网校

course_enroll（课程报名成功）

{
  "to_email": "student@example.com",
  "subject": "课程报名成功",
  "message": "占位",
  "template_id": "course_enroll",
  "data": {
    "course_name": "PHP 高级架构师实战课",
    "student_name": "张三"
  }
}

course_start（开课提醒）

{
  "to_email": "student@example.com",
  "subject": "课程即将开课提醒",
  "message": "占位",
  "template_id": "course_start",
  "data": {
    "course_name": "PHP 高级架构师实战课",
    "start_time": "2026-02-01 20:00"
  }
}

exam_result（考试成绩通知）

{
  "to_email": "student@example.com",
  "subject": "考试成绩公布",
  "message": "占位",
  "template_id": "exam_result",
  "data": {
    "exam_name": "PHP 中级认证考试",
    "score": "92",
    "rank": "第 3 名"
  }
}

certificate_issue（证书发放）

{
  "to_email": "student@example.com",
  "subject": "恭喜您获得电子证书",
  "message": "占位",
  "template_id": "certificate_issue",
  "data": {
    "cert_name": "PHP 高级架构师认证",
    "cert_url": "https://edu.example.com/cert/abc123.pdf"
  }
}

live_room_remind（直播课提醒）

{
  "to_email": "student@example.com",
  "subject": "直播课即将开始",
  "message": "占位",
  "template_id": "live_room_remind",
  "data": {
    "live_title": "Redis 高并发实战",
    "start_time": "2026-01-23 19:30",
    "live_url": "https://live.example.com/room/888"
  }
}

🏥 医疗 / 健康

appointment_book（预约成功）

{
  "to_email": "patient@example.com",
  "subject": "预约挂号成功",
  "message": "占位",
  "template_id": "appointment_book",
  "data": {
    "patient_name": "张三",
    "doctor": "王医生",
    "time": "2026-01-30 09:30"
  }
}

appointment_remind（就诊前提醒）

{
  "to_email": "patient@example.com",
  "subject": "就诊提醒",
  "message": "占位",
  "template_id": "appointment_remind",
  "data": {
    "hospital": "XX 中心医院",
    "department": "内科",
    "room": "305 诊室"
  }
}

report_ready（检查报告已出）

{
  "to_email": "patient@example.com",
  "subject": "检查报告已出具",
  "message": "占位",
  "template_id": "report_ready",
  "data": {
    "report_type": "血常规",
    "report_url": "https://hospital.example.com/report/123456"
  }
}

prescription_notify（电子处方通知）

{
  "to_email": "patient@example.com",
  "subject": "电子处方已开具",
  "message": "占位",
  "template_id": "prescription_notify",
  "data": {
    "drug_list": "阿莫西林胶囊、布洛芬缓释胶囊",
    "usage": "每日三次，每次一粒，饭后服用"
  }
}

🏘 物业 / 智慧社区

property_fee_notify（物业费催缴）

{
  "to_email": "owner@example.com",
  "subject": "物业费缴费提醒",
  "message": "占位",
  "template_id": "property_fee_notify",
  "data": {
    "room_no": "3栋1201",
    "amount": "1280.00",
    "due_date": "2026-02-28"
  }
}

repair_apply（报修提交成功）

{
  "to_email": "owner@example.com",
  "subject": "报修申请已提交",
  "message": "占位",
  "template_id": "repair_apply",
  "data": {
    "repair_type": "水管漏水",
    "address": "3栋1201 主卫"
  }
}

repair_assign（维修人员派单）

{
  "to_email": "owner@example.com",
  "subject": "维修师傅已接单",
  "message": "占位",
  "template_id": "repair_assign",
  "data": {
    "worker_name": "李师傅",
    "phone": "13800138000"
  }
}

visitor_invite（访客通行码）

{
  "to_email": "visitor@example.com",
  "subject": "访客通行码",
  "message": "占位",
  "template_id": "visitor_invite",
  "data": {
    "visitor_name": "王五",
    "qr_code_url": "https://community.example.com/qrcode/abc123.png"
  }
}

💳 金融 / 风控

loan_apply（借款申请提交）

{
  "to_email": "user@example.com",
  "subject": "借款申请已提交",
  "message": "占位",
  "template_id": "loan_apply",
  "data": {
    "amount": "50000.00",
    "term": "12 个月"
  }
}

loan_approve（放款成功）

{
  "to_email": "user@example.com",
  "subject": "放款成功通知",
  "message": "占位",
  "template_id": "loan_approve",
  "data": {
    "loan_no": "LOAN20260121001",
    "amount": "50000.00",
    "repay_date": "2026-02-20"
  }
}

repayment_remind（还款日前提醒）

{
  "to_email": "user@example.com",
  "subject": "还款提醒",
  "message": "占位",
  "template_id": "repayment_remind",
  "data": {
    "amount": "4388.88",
    "due_date": "2026-02-20",
    "repay_url": "https://finance.example.com/repay/LOAN20260121001"
  }
}

overdue_warning（逾期警告）

{
  "to_email": "user@example.com",
  "subject": "逾期还款警告",
  "message": "占位",
  "template_id": "overdue_warning",
  "data": {
    "overdue_days": "3",
    "penalty": "50.00"
  }
}

credit_score_change（信用分变动）

{
  "to_email": "user@example.com",
  "subject": "信用分变动通知",
  "message": "占位",
  "template_id": "credit_score_change",
  "data": {
    "old_score": "650",
    "new_score": "680"
  }
}

🌐 IoT / 设备监控

device_online（设备上/下线）

{
  "to_email": "admin@example.com",
  "subject": "设备状态变更通知",
  "message": "占位",
  "template_id": "device_online",
  "data": {
    "device_id": "DEV-SENSOR-001",
    "device_name": "机房温度传感器"
  }
}

device_alarm（设备告警）

{
  "to_email": "admin@example.com",
  "subject": "设备告警通知",
  "message": "占位",
  "template_id": "device_alarm",
  "data": {
    "alarm_type": "温度过高",
    "level": "严重",
    "value": "42°C"
  }
}

sensor_threshold（传感器阈值超标）

{
  "to_email": "admin@example.com",
  "subject": "传感器阈值超标",
  "message": "占位",
  "template_id": "sensor_threshold",
  "data": {
    "sensor_name": "机房湿度传感器",
    "current_value": "85%"
  }
}

gateway_offline（网关离线）

{
  "to_email": "admin@example.com",
  "subject": "网关离线告警",
  "message": "占位",
  "template_id": "gateway_offline",
  "data": {
    "gateway_id": "GW-AREA-01",
    "last_time": "2026-01-21 18:30"
  }
}

📈 营销 / 增长

welcome_series_1（新用户欢迎邮件）

{
  "to_email": "user@example.com",
  "subject": "欢迎加入我们",
  "message": "占位",
  "template_id": "welcome_series_1",
  "data": {
    "username": "张三",
    "guide_url": "https://example.com/getting-started"
  }
}

inactive_user_recall（流失用户召回）

{
  "to_email": "user@example.com",
  "subject": "好久不见，专属福利已备好",
  "message": "占位",
  "template_id": "inactive_user_recall",
  "data": {
    "last_login_days": "30",
    "incentive": "满 100 减 30 优惠券"
  }
}

feature_announce（新功能公告）

{
  "to_email": "user@example.com",
  "subject": "新功能上线：智能数据分析",
  "message": "占位",
  "template_id": "feature_announce",
  "data": {
    "feature_name": "智能数据分析看板",
    "desc": "一键生成可视化报表，助力业务决策。",
    "detail_url": "https://example.com/features/analytics"
  }
}

webinar_invite（线上讲座邀请）

{
  "to_email": "user@example.com",
  "subject": "邀请函：SaaS 增长实战分享",
  "message": "占位",
  "template_id": "webinar_invite",
  "data": {
    "webinar_title": "SaaS 企业增长实战分享",
    "time": "2026-02-10 20:00",
    "join_url": "https://webinar.example.com/saas-growth"
  }
}

⚙️ 通用系统级

data_export_done（数据导出完成）

{
  "to_email": "admin@example.com",
  "subject": "数据导出完成",
  "message": "占位",
  "template_id": "data_export_done",
  "data": {
    "export_type": "用户行为日志",
    "download_url": "https://example.com/exports/user_logs_202601.zip",
    "expire_time": "2026-01-28 12:00"
  }
}

admin_login_notify（管理员登录提醒）

{
  "to_email": "admin@example.com",
  "subject": "管理员登录提醒",
  "message": "占位",
  "template_id": "admin_login_notify",
  "data": {
    "admin_user": "admin",
    "ip": "1.2.3.4",
    "time": "2026-01-21 22:15"
  }
}

config_change_notify（配置变更通知）

{
  "to_email": "admin@example.com",
  "subject": "系统配置变更通知",
  "message": "占位",
  "template_id": "config_change_notify",
  "data": {
    "config_key": "mail.smtp_host",
    "old_value": "smtp.qq.com",
    "new_value": "smtp.exmail.qq.com"
  }
}

license_expire_warning（授权即将到期）

{
  "to_email": "admin@example.com",
  "subject": "系统授权即将到期",
  "message": "占位",
  "template_id": "license_expire_warning",
  "data": {
    "days_left": "15",
    "license_type": "企业版"
  }
}

backup_fail（备份失败告警）

{
  "to_email": "admin@example.com",
  "subject": "数据库备份失败告警",
  "message": "占位",
  "template_id": "backup_fail",
  "data": {
    "backup_type": "MySQL 全量备份",
    "fail_reason": "磁盘空间不足"
  }
}

cron_job_fail（定时任务失败）

{
  "to_email": "admin@example.com",
  "subject": "定时任务执行失败",
  "message": "占位",
  "template_id": "cron_job_fail",
  "data": {
    "job_name": "daily_report_generate",
    "error_msg": "SQLSTATE[HY000]: General error: 2006 MySQL server has gone away"
  }
}

✅ 本节模板专用于：后台客服 / 运营人员邮箱。
✅ 与普通用户邮件区分，便于客服及时介入订单、售后与服务流程。

📌 使用前提

模板标识（template_id）需在后台“邮件模板”中存在
客服账号需绑定有效邮箱
建议在系统中限制：仅发送给 status = 1 且 online = 1 的客服

✅ 新订单提醒（客服）

{
  "to_email": "kefu@example.com",
  "subject": "客服新订单提醒",
  "message": "占位",
  "template_id": "order_created_admin",
  "from_name": "系统通知",
  "data": {
    "order_no": "ORD20260121001",
    "product_name": "VIP年卡",
    "amount": "399.00",
    "create_time": "2026-01-21 17:00"
  }
}

✅ 支付成功提醒（客服）

{
  "to_email": "kefu@example.com",
  "subject": "客服订单支付成功提醒",
  "message": "占位",
  "template_id": "order_paid_admin",
  "from_name": "系统通知",
  "data": {
    "order_no": "ORD20260121001",
    "product_name": "VIP年卡",
    "amount": "399.00",
    "pay_time": "2026-01-21 17:01"
  }
}

✅ 发货通知（客服）

{
  "to_email": "kefu@example.com",
  "subject": "客服发货通知",
  "message": "占位",
  "template_id": "order_shipped_admin",
  "from_name": "系统通知",
  "data": {
    "order_no": "ORD20260121001",
    "express": "顺丰速运",
    "tracking_no": "SF123456789",
    "ship_time": "2026-01-21 18:00"
  }
}

✅ 订单完成通知（客服）

{
  "to_email": "kefu@example.com",
  "subject": "客服订单完成通知",
  "message": "占位",
  "template_id": "order_finished_admin",
  "from_name": "系统通知",
  "data": {
    "order_no": "ORD20260121001",
    "product_name": "VIP年卡",
    "amount": "399.00",
    "finish_time": "2026-01-21 19:00"
  }
}

✅ 退款申请提醒（客服 · 申请阶段）

📌 用户提交退款申请后，第一时间通知客服。
📌 不等审核、不等发货。
📌 对应 template_id：order_refund_apply_admin

{
  "to_email": "kefu@example.com",
  "subject": "客服退款申请提醒",
  "message": "占位",
  "template_id": "order_refund_apply_admin",
  "from_name": "系统通知",
  "data": {
    "order_no": "ORD20260121001",
    "product_name": "VIP年卡",
    "refund_amount": "99.00",
    "apply_time": "2026-01-21 19:30"
  }
}

✅ 订单取消提醒（客服）

{
  "to_email": "kefu@example.com",
  "subject": "客服订单取消提醒",
  "message": "占位",
  "template_id": "order_cancel_admin",
  "from_name": "系统通知",
  "data": {
    "order_no": "ORD20260121002",
    "cancel_reason": "用户主动取消",
    "cancel_time": "2026-01-21 20:00"
  }
}

✅ 投诉 / 工单提醒（客服）

{
  "to_email": "kefu@example.com",
  "subject": "客服工单投诉提醒",
  "message": "占位",
  "template_id": "complaint_admin",
  "from_name": "系统通知",
  "data": {
    "ticket_id": "TK20260121001",
    "username": "张三",
    "content": "商品未收到，请尽快核实物流信息。",
    "create_time": "2026-01-21 20:30"
  }
}

✅ 至此，你的邮箱推送系统已成为真正的通用邮件中台：

• 电商交易 / 售后 / 财务
• CMS / 社区 / 内容平台
• OA / HR / 招聘 / 企业办公
• 教育 / 网校 / 培训系统
• 医疗 / 健康 / 预约系统
• 物业 / 智慧社区 / 园区管理
• 金融 / 借贷 / 风控系统
• IoT / 设备监控 / 工业系统
• 营销 / 增长 / 用户运营
• 系统运维 / 安全 / 合规
• 新订单 → 客服
• 支付成功 → 客服
• 发货 → 客服
• 订单完成 → 客服
• 退款申请 → 客服
• 订单取消 → 客服
• 投诉 / 工单 → 客服

无论什么业务系统，都能找到对应的模板与调用示例。

📘 API 接口文档（超详细 · 防呆级 · 最终版）

1第一节：你必须死记的三个概念

✅ 概念一：什么是 template_id（最重要）

✅ 概念二：什么是 data（最容易错）

✅ 概念三：什么是“已进入发送队列”（200 的真正含义）

2第二节：系统内置模板标识对照表

3第三节：接口基础信息

4第四节：请求字段完整说明

5第五节：两种发送模式详解

✅ 验证码模板

✅ 订单提交成功

✅ 订单支付成功

✅ 发货通知

✅ 订单已完成

✅ 退款成功

✅ 用户：退款申请已提交（申请阶段）

✅ 客服：新退款申请待处理（申请阶段）

✅ 账户余额变动

✅ 客服回复通知

✅ 服务即将到期提醒

6第六节：多语言调用示例

✅ PHP (cURL)

✅ Python (requests)

✅ Java (OkHttp)

7第七节：错误码大全（含排查步骤）

8第八节：队列与冷却机制（白话版）

✅ 为什么要用队列？

✅ 什么是 SMTP 冷却？

9第九节：QQ 邮箱特别说明（必读 ⚠️）

10第十节：对接口诀（必背）

11第十一节：常见问题排查清单

12第十二节：全量系统通知模板速查表（超全 · 最终版）

13第十三节：非商城系统模板速查表 + 调用示例（超全 · 最终版）

📄 CMS / 内容系统

article_publish（文章发布通知）

article_update（文章更新提醒）

comment_new（新评论通知）

comment_reply（评论被回复）

content_audit_reject（内容审核驳回）

digest_weekly（周报推送）

subscribe_confirm（订阅确认）

💬 社区 / 论坛

thread_new（新帖子通知）

reply_at（@ 我的回复）

private_message（私信通知）

ban_warn（禁言 / 封号警告）

🏢 OA / 企业办公

attendance_remind（打卡提醒）

leave_apply（请假申请通知）

leave_approve（请假审批结果）

meeting_invite（会议邀请）

meeting_remind（会议开始前提醒）

👤 HR / 招聘

resume_receive（简历投递成功）

interview_invite（面试邀请）

offer_send（Offer 发放）

contract_expire（合同到期提醒）

🎓 教育 / 网校

course_enroll（课程报名成功）

course_start（开课提醒）

exam_result（考试成绩通知）

certificate_issue（证书发放）

live_room_remind（直播课提醒）

🏥 医疗 / 健康

appointment_book（预约成功）

appointment_remind（就诊前提醒）

report_ready（检查报告已出）

prescription_notify（电子处方通知）

🏘 物业 / 智慧社区

property_fee_notify（物业费催缴）

repair_apply（报修提交成功）

repair_assign（维修人员派单）

visitor_invite（访客通行码）

💳 金融 / 风控

loan_apply（借款申请提交）

loan_approve（放款成功）

repayment_remind（还款日前提醒）

overdue_warning（逾期警告）

credit_score_change（信用分变动）

🌐 IoT / 设备监控

✅ 概念一：什么是 `template_id`（最重要）

✅ 概念二：什么是 `data`（最容易错）