邮件分发接口文档

1. 注册账号，在控制台「API 密钥」中复制密钥；
2. 在「发信邮箱」中添加至少一个 QQ / 163 邮箱，并测试连接；
3. 调用 POST /api/v1/send，把收件人、主题、正文传过来。

curl

curl -X POST https://smtp.xueyuanpie.com/api/v1/send \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "订单已发货",
    "html": "
你好，你的包裹已发出。
",
    "provider": "qq"
  }'

PHP

$ch = curl_init('https://smtp.xueyuanpie.com/api/v1/send');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-API-Key: sk_live_xxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'to'      => 'user@example.com',
        'subject' => '订单已发货',
        'html'    => '
你好，你的包裹已发出。
',
        'provider'=> 'qq',
    ]),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

Python

import requests

resp = requests.post(
    'https://smtp.xueyuanpie.com/api/v1/send',
    headers={'X-API-Key': 'sk_live_xxxxxxxxxxxxxxxx'},
    json={
        'to': 'user@example.com',
        'subject': '订单已发货',
        'html': '
你好，你的包裹已发出。
',
        'provider': 'qq',
    },
    timeout=30,
)
print(resp.json())

Node.js

const res = await fetch('https://smtp.xueyuanpie.com/api/v1/send', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: 'user@example.com',
    subject: '订单已发货',
    html: '
你好，你的包裹已发出。
',
    provider: 'qq',
  }),
});
console.log(await res.json());

所有 /api/v1/* 接口都需要携带 API 密钥，二选一：

X-API-Key: sk_live_xxxxxxxxxxxxxxxx
# 或
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

密钥在控制台「API 密钥」中创建，只在创建时完整展示一次，服务端仅保存哈希。泄露后请立即停用并重建。

POST /api/v1/send　Content-Type: application/json

系统会从你的邮箱池中选择一个可用邮箱投递。可用 provider 指定只用 QQ 或 163，也可用 mailbox_id 指定具体邮箱。

同步发送：

{
  "code": 0,
  "msg": "发送完成",
  "data": {
    "request_id": "req_9f2c1a7b8e3d4c5a",
    "mode": "sync",
    "accepted": 2,
    "queued": 0,
    "sent": 2,
    "failed": 0,
    "task_id": null,
    "results": [
      {
        "to": "a@example.com",
        "status": "sent",
        "error": "",
        "message_id": "<...@qq.com>",
        "log_id": 1024
      }
    ]
  }
}

异步入队：

{
  "code": 0,
  "msg": "已进入发送队列",
  "data": {
    "request_id": "req_9f2c1a7b8e3d4c5a",
    "mode": "queue",
    "accepted": 50,
    "queued": 50,
    "sent": 0,
    "failed": 0,
    "task_id": 18,
    "results": []
  }
}

GET /api/v1/status/{request_id}

异步任务的逐封状态（最多返回前 100 条）：

{
  "code": 0,
  "data": {
    "request_id": "req_9f2c1a7b8e3d4c5a",
    "status": "running",
    "total": 50,
    "sent": 32,
    "failed": 1,
    "progress": 66,
    "items": [
      { "to": "a@example.com", "status": "sent", "error": "", "message_id": "<...>" }
    ]
  }
}

status 取值：pending / running / paused / done / canceled。

GET /api/v1/mailboxes

返回当前账号下已绑定的邮箱、服务商、启用状态与今日用量（不包含授权码）。

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": 1,
        "provider": "qq",
        "provider_name": "QQ邮箱",
        "email": "notice@qq.com",
        "is_default": 1,
        "status": 1,
        "daily_limit": 200,
        "sent_today": 36,
        "healthy": true
      }
    ]
  }
}

GET /api/v1/usage

{
  "code": 0,
  "data": {
    "today_sent": 128,
    "daily_limit": 1000,
    "remaining": 872,
    "key": { "name": "生产环境", "prefix": "sk_live_abc123…" },
    "mailboxes": 3,
    "requests_today": 42
  }
}

常见发送失败原因

• 535 Authentication failed：授权码错误或已失效，重新生成授权码；QQ 邮箱不要填登录密码。
• 550 / 554：被服务商判定为垃圾邮件或收件人不存在，调整内容与收件人。
• Connection timed out：服务器端口 / 加密方式不匹配，QQ 常用 465 + SSL。
• 今日额度已用完：调高邮箱每日额度或增加邮箱，等待次日重置。

添加邮箱时选择对应服务商即可自动填好以上参数，无需手动输入。

• 控制频率：单个 QQ / 163 邮箱每日 200 封以内更稳妥，可按邮箱设置更低额度。
• 通知类优先：验证码、订单、告警等一对一通知最适合普通邮箱模式。
• 准备备用邮箱：至少绑定 2 个邮箱，轮询能显著降低单账号受限的影响。
• 异步 + 轮询：批量分发用 async: true，再用状态接口更新业务状态，避免长连接超时。
• 幂等处理：request_id 可用于业务侧去重与追踪。