MailerWire 开发者 API 文档

概述与架构理念

MailerWire 是定位关键业务的事务邮件路由控制面。连接您现有的 Resend 或 Brevo 供应商后，业务系统只需对接一套 API。当首选供应商用尽每日或每月限额时，MailerWire 自动按策略切换至备用出口；当供应商抛出业务异常或网络未明时，严格坚持“不盲目重投”，从根源杜绝重复发信。

请求基础地址 (Base URL)

所有事务发信请求均统一提交至 MailerWire API 接口地址：

基于标准 HTTPS 443 端口与 TLS 加密传输。

鉴权与认证机制

所有的 API 请求均需携带在控制台「项目与 API Key」(/app/api-keys) 中生成的密钥。密钥格式为 mw_live_<public_id>_<secret>，创建时仅展示一次。

Authorization: Bearer mw_live_<public_id>_<secret>

幂等防重保障 (Idempotency)

针对验证码、交易凭据、密码重置等关键事务场景，MailerWire 强制要求携带 Idempotency-Key 请求头，防止因网络波动、客户端重发导致用户收到多封邮件。

• 必填请求头：Idempotency-Key（最大 128 字符）。
• 单 API Key 维度拥有 24 小时幂等缓存窗口。
• 相同 Key 在窗口内重复提交时，直接返回首次受理记录，绝不会向供应商触发二次投递。

Idempotency-Key: order_20260906_983210

发送事务邮件 (Send Email)

提交一封邮件进入调度队列，按当前路由策略择机投递。

请求头要求 (Request Headers)

请求体参数 (Body Parameters)

响应结果 (202 Accepted)

为了保障极致的高吞吐与低延迟，MailerWire 采用异步排队机制。返回 202 状态码即代表系统已完成校验、幂等登记并进入投递队列。

{
  "id": "b4d1d94c-87d2-4328-971c-7f55f24209bf",
  "status": "accepted",
  "submitted_at": "2026-09-06T12:00:00.000Z"
}

多语言调用代码示例

curl -X POST https://api.mailerwire.com/v1/emails \
  -H "Authorization: Bearer mw_live_your_api_key" \
  -H "Idempotency-Key: req_$(date +%s)_order9823" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme Notification <notify@acme.com>",
    "to": "alex@example.com",
    "subject": "Your verification code: 629103",
    "text": "Your verification code is 629103. It expires in 10 minutes.",
    "html": "<p>Your code is <strong>629103</strong>.</p>"
  }'

投递状态与生命周期

每封邮件从提交到最终完成，状态严格遵循确定性状态机流转：

Webhook 状态回调与流水同步

在供应商（Resend / Brevo）管理后台配置以下 Webhook 地址，可将真实的“已送达”、“拒收/退信”、“打开”等事件实时回写至 MailerWire 发送记录流水。

系统错误码速查表

MailerWire 遵循标准 HTTP 规范与结构化错误返回格式：