📧 ZCMail API 文档

多 QQ 邮箱 SMTP 账号池 · 自动轮询 · 每账号每日限额 · Token 鉴权

1. 鉴权

所有 API（除 health）均需在请求头携带管理后台生成的 Token：

Authorization: Bearer <你的token>

Token 在管理后台「Token 管理」中生成，可启停、删除。

2. 健康检查

GET /api.php?action=health

curl -k https://mail.zgric.top/api.php?action=health

{"code":0,"msg":"ok","status":"ok","app":"ZCMail","time":"2026-08-11T16:30:00+08:00"}

3. 发送邮件

POST /api.php?action=send Content-Type: application/json

参数	类型	必填	说明
to	string	✅	收件人邮箱
subject	string	✅	邮件主题
body	string	✅	邮件正文
body_type	string	—	`plain`（默认）或 `html`
cc	string	—	抄送，多个用英文逗号分隔
bcc	string	—	密送，多个用英文逗号分隔
account	string	—	可选，指定某个发件账号（精确邮箱），不填则自动轮询

请求示例：

curl -X POST "https://mail.zgric.top/api.php?action=send" \
  -H "Authorization: Bearer 你的token" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "someone@example.com",
    "subject": "测试邮件",
    "body": "你好，这是一封测试邮件",
    "body_type": "plain"
  }'

成功返回：

{"code":0,"msg":"发送成功","account":"xxx@qq.com"}

account 字段指示本次实际使用的发件账号。

4. 轮询与额度说明

发信时系统从账号池中选择 启用中 且 今日未达限额 的账号，优先选「今日已发最少」者，实现负载均衡。
每个账号的每日限额在管理后台可自由设置（默认 40 封），跨天自动重置。
发送成功后该账号今日计数 +1；若某账号达上限，自动切换下一个候选账号。
若所有账号均达上限，返回 code: 500，msg 为「今日所有账号发信额度已用完」。
也可传 account 参数强制使用指定账号（若该账号已停用或达上限会失败）。

5. 调用示例

PHP

$ch = curl_init('https://mail.zgric.top/api.php?action=send');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer 你的token',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to' => 'someone@example.com',
        'subject' => '测试邮件',
        'body' => '你好',
    ]),
]);
echo curl_exec($ch);

Python

import requests
r = requests.post(
    "https://mail.zgric.top/api.php?action=send",
    headers={"Authorization": "Bearer 你的token"},
    json={"to": "someone@example.com", "subject": "测试", "body": "你好"},
)
print(r.json())

JavaScript (fetch)

fetch("https://mail.zgric.top/api.php?action=send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer 你的token",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ to: "someone@example.com", subject: "测试", body: "你好" }),
}).then(r => r.json()).then(console.log);

6. 返回码

code	HTTP	含义
0	200	成功
400	400	参数错误（缺参 / 邮箱格式错误 / body_type 非法）
401	401	token 缺失或无效
404	404	接口不存在
500	500	发送失败（SMTP 错误 / 额度用完 / 指定账号不可用）

← 返回管理后台