让邮件能力，融入你的业务
从一封事务通知开始。清晰的接口、可追踪的提交状态，以及可安全重放的幂等请求。
认证与接入申请
联系平台申请事务邮件应用，确认发件域名、发件地址与应用配额。平台安全发放 edm_ 开头的应用密钥；当前没有网页自助生成密钥功能。应用密钥与商家后台账号、旧版接口密钥、MCP 凭据互不通用。
请求头传 Authorization: Bearer <EDM_API_KEY>，使用 HTTPS。不要放到网页 JavaScript、URL、聊天记录或 Git。本文所有示例均为占位内容，不会在本页面触发发送。
https://edm.zhmj.com默认配额：每应用 20 次/滚动小时、100 次/北京时间自然日，同一收件人 5 次/滚动小时。实际以平台给应用配置的配额为准；新的发送尝试计入限额。
提交事务邮件
/api/v1/mail用于通知、验证、到期提醒等单封事务邮件。Content-Type: application/json，整个原始 JSON 请求最多 40,000 字节。拒绝未声明的额外字段；发件身份由平台配置，不能由请求覆盖。
| 字段 | 要求 |
|---|---|
| Authorization | 必填，应用 Bearer 密钥 |
| Content-Type | 必填，application/json |
| Idempotency-Key | 必填，8–128 个 ASCII 字符，仅字母、数字、下划线、点、冒号和短横线。同一业务事件始终复用同一键。 |
| 参数 | 类型 / 必填 | 说明 |
|---|---|---|
| to | string / 是 | 单一有效邮箱，最多254字节，不能包含换行或多个收件人。 |
| subject | string / 是 | 非空，最多240字节，不允许CR、LF或NUL；不是240个汉字。 |
| html | string / 是 | 非空HTML正文，最多24,000字节。 |
| text | string / 否 | 纯文本正文，最多12,000字节；省略时从HTML去标签生成。 |
正在加载代码示例…| HTTP / status | 含义与处理 |
|---|---|
| 200 / accepted | 服务商接受了发送请求，不代表已送达或进入收件箱。保存响应的32位消息id。 |
| 202 / sending | 正在处理；稍后查询状态，不新建幂等键。 |
| 202 / unknown | 服务商响应不确定，可能已经发送。查询、对账或联系平台，禁止换键自动重发。 |
| 502 / failed | 本次发送失败，保存消息id及状态，核查原因。 |
| 同键同内容 | 返回原记录，不再次发送。卡住超过60秒的sending在重放时会转为unknown。 |
| 同键不同内容 | 409 idempotency_conflict。不要用新键掩盖业务事件冲突。 |
查询本应用的邮件状态
/api/v1/mail/status?id=<MESSAGE_ID>使用创建该消息的应用密钥。id 为32位小写十六进制字符串；不存在或属于其他应用均返回404，不泄露其他应用信息。
正在加载代码示例…仅返回 id、status、created_at、updated_at，时间是 Unix 秒。目前不提供 delivered、打开率、点击率等事务 API 状态。
Supabase Send Email Hook
/api/v1/mail/supabase这是平台专用的 Supabase Auth 集成，需要平台预先配置应用、发件身份与 Hook 共享密钥。不能使用普通 Bearer 密钥替代 Hook 签名。事件由 Supabase 生成，包含 user 与 email_data；不要手工拼接验证链接或在日志中保存验证 token。
| webhook-id | 1–128个可打印ASCII字符，作为事件幂等标识。 |
|---|---|
| webhook-timestamp | Unix秒时间戳，与服务器时间偏差不超过300秒。 |
| webhook-signature | v1,<Base64签名>，签名为HMAC-SHA256。 |
| 签名原文 | webhook-id.webhook-timestamp.原始请求体。必须按收到的原始字节验签，不能先解析再重新序列化。 |
| 大小 / 响应 | 原始body最多80,000字节。成功200及空JSON对象；无效JSON400、签名失败401、事件不受支持或发送不可用503及嵌套error对象。 |
平台支持轮换Hook签名密钥。Supabase事件字段与签名格式参见 Supabase 官方文档 ↗ 和 Standard Webhooks ↗。
旧版发信接口 仅保留兼容
/api/email/send已有集成可继续使用，新项目请选择新版事务 API。使用表单体 application/x-www-form-urlencoded，四个必填字符串：api_key、to、subject、html。密钥来自平台配置的旧版 EMAIL_API_KEYS，与新版 edm_ 密钥不同。
旧版不提供新版的应用级幂等、配额及状态隔离保障。响应是历史 code / data / msg 业务信封，HTTP 200不等于业务成功，必须检查业务code（成功200，失败通常400）。GET不支持；不要在URL传密钥。
服务端代码示例
从环境变量读取密钥。示例地址属于保留的 example.invalid 域名；实际测试请换成你获授权接收的地址，并做好结果保存和错误处理。
正在加载代码示例…正在加载代码示例…错误处理与安全重试
| HTTP | error / 处理建议 |
|---|---|
| 400 | 参数校验失败或JSON不合法，按error提示修正。不要记录密钥、收件地址和正文。 |
| 401 | unauthorized：缺少、错误或已禁用的应用密钥。 |
| 403 | 应用停用等权限限制；联系平台确认。 |
| 404 | not_found：本应用下找不到该消息ID。 |
| 409 | idempotency_conflict：同幂等键的内容与原请求不同。 |
| 413 / 415 | payload_too_large / json_required：缩小原始请求体或使用JSON。 |
| 429 | rate_limit_exceeded：应用/收件人频率限制；退避等待配额窗口，仍复用原业务键。 |
| 503 | mail_service_unavailable：服务暂不可用；不要紧密循环请求。 |
网络超时不等于未发送。先查询已保存的消息 ID；如没有 ID，只能以同一幂等键、相同内容重放核对原记录。遇到 unknown 应人工对账，不换新键盲目重试。
清楚知道，能做什么与不能做什么
本版本公开的是事务邮件集成，不是商家后台的完整远程控制接口。客户管理、营销群发、到期续费记录、插件开关、支付及管理员内部回调不作为公共API或MCP写工具开放，原有客户使用方式不变。
事务接口保存用于幂等和核对的内容哈希、收件人哈希及状态，不保存原始收件地址或正文；客户端和上游服务商的数据保留策略需要你另行审查。事务API当前不是商家营销积分扣费接口，应用配额与后台营销积分是不同机制。