API 参考 · v1

一个接口,批量收各家邮箱

用代码调用收信能力:传入 Firstmail、GMX 或 Hotmail 账号,一次拉取收件箱与垃圾箱的最新邮件,并自动识别验证码。API 仅对注册用户开放,需在控制台生成密钥。

Base URL https://你的域名

provider = firstmail provider = gmx provider = microsoft

本机与自有部署

本地运行时 Base URL 为 http://127.0.0.1:8787。对外部署时请置于 HTTPS 反向代理之后,并用你自己的域名。邮件内容不落库,仅在响应中返回。

认证 · 获取密钥

登录控制台,进入「API 密钥」生成一个密钥(明文只显示一次,请立即保存)。所有 API 请求通过 Authorization 头携带该密钥。

Authorization 头

# 所有请求都带上 Bearer 密钥
curl https://你的域名/api/v1/providers \
  -H "Authorization: Bearer mg_live_xxxxxxxxxxxx"

const res = await fetch("https://你的域名/api/v1/providers", {
  headers: { "Authorization": "Bearer mg_live_xxxxxxxxxxxx" }
});
const { providers } = await res.json();

密钥即权限

密钥只在服务端使用,切勿写进前端或公开仓库。可在控制台随时吊销;吊销后使用它的调用立即失效。

支持平台

GET/api/v1/providers

返回支持的邮箱平台及其服务器信息。

200 OK

{
  "providers": {
    "firstmail": { "label": "Firstmail",         "host": "imap.firstmail.ltd",   "port": 993, "auth": "password" },
    "gmx":       { "label": "GMX",               "host": "imap.gmx.com",         "port": 993, "auth": "password" },
    "microsoft": { "label": "Hotmail / Outlook", "host": "outlook.office365.com","port": 993, "auth": "oauth" }
  }
}

收信

POST/api/v1/fetch

登录一个或多个邮箱,拉取收件箱与垃圾箱的最新邮件并识别验证码。lines 每行一个账号,行数即账号数,可批量。

参数	类型	说明
provider 必填	string	`firstmail` · `gmx` · `microsoft`
lines 必填	string	账号列表,每行一个,格式见账号格式。
limit 可选	number	每个邮箱抓取的邮件数,默认 `10`,最大 `50`。

POST /api/v1/fetch

curl -X POST https://你的域名/api/v1/fetch \
  -H "Authorization: Bearer mg_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gmx",
    "lines": "[email protected]:pass1\[email protected]:pass2",
    "limit": 10
  }'

const res = await fetch("https://你的域名/api/v1/fetch", {
  method: "POST",
  headers: {
    "Authorization": "Bearer mg_live_xxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    provider: "gmx",
    lines: "[email protected]:pass1\[email protected]:pass2",
    limit: 10
  })
});
const data = await res.json();

200 OK

{
  "provider": "gmx",
  "limit": 10,
  "count": 2,
  "results": [
    {
      "email": "[email protected]",
      "ok": true,
      "messages": [
        {
          "folder": "inbox",
          "subject": "Verify your email address",
          "from": "[email protected]",
          "date": "2026-07-19T09:04:49.000Z",
          "text": "…enter the code 747572…",
          "codes": ["747572"]
        }
      ]
    },
    { "email": "[email protected]", "ok": false, "error": "登录失败:账号或密码/令牌无效", "messages": [] }
  ]
}

逐账号结果

每个账号单独返回 ok;失败的带 error,不影响其他账号。codes 为识别到的验证码候选,folder 为 inbox 或 junk。

账号格式

lines 每行一个账号,按平台使用以下格式:

平台	格式
firstmail	`邮箱:密码`(域名可各不相同,统一走 Firstmail 服务器)
gmx	`邮箱:密码`
microsoft	`邮箱----密码----refresh_token----client_id`

批量时把多行拼进 lines,用换行符 \n 分隔。

速率限制

每个密钥默认 120 请求 / 分钟。响应头返回剩余额度,超出返回 429,请按 Retry-After 退避。

响应头

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1784927400

错误码

错误以标准 HTTP 状态码返回,响应体为 { "error": { "code", "message" } }。

状态	code	说明
400	invalid_request	参数缺失或格式错误(如未知 provider、缺少账号)。
401	unauthorized	密钥缺失、无效或已吊销。
429	rate_limited	超过速率限制,按 `Retry-After` 重试。
5xx	server_error	服务端异常,可安全重试。

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "API 密钥无效或已吊销"
  }
}