开发者 API - Glulu 邮箱接码

1. 鉴权方式

所有 /api/v1 接口都需要 API Key。不要把真实 Key 写进前端页面或公开仓库。

X-Glulu-Api-Key: YOUR_API_KEY

也支持 Authorization: Bearer YOUR_API_KEY。如果需要 Key，请联系站点管理员发放。

2. 查询可用域名

先拉取当前可创建邮箱的域名列表，避免软件写死域名。

curl https://glulu.me/api/v1/domains \
  -H "X-Glulu-Api-Key: YOUR_API_KEY"

请求

GET /api/v1/domains

关键返回

domains：全部可接入域名；default_domain：默认域名。

3. 创建邮箱

推荐让系统自动生成数字邮箱前缀，减少撞号和重复使用问题。

curl -X POST https://glulu.me/api/v1/mailboxes \
  -H "X-Glulu-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"qhua.edu.evofu.com","mailbox_mode":"temporary","auto_generate":true}'

domain可选，不传则使用默认域名。

mailbox_modetemporary 或 permanent。

auto_generate建议传 true，由系统生成邮箱前缀。

local_part自定义前缀，仅在 auto_generate=false 时使用。

note可选备注，方便后台排查。

{
  "success": true,
   "email": "[email protected]",
  "password": "mailbox_password",
  "mailbox_mode": "temporary",
  "expires_at": "2026-05-12T02:00:00+00:00"
}

4. 等待邮件和验证码

高并发接入优先用长轮询接口。一个请求最多等待 60 秒，服务端内部会合并查询，避免客户端一直刷接口。

curl "https://glulu.me/api/v1/mailboxes/[email protected]/wait-code?timeout_seconds=60&poll_interval_seconds=2" \
  -H "X-Glulu-Api-Key: YOUR_API_KEY"

{
  "success": true,
  "found": true,
  "email_count": 1,
  "latest_code": "123456",
  "emails": [
    {
      "subject": "你的验证码",
      "from_addr": "[email protected]",
      "date": "Tue, 12 May 2026 01:40:00 +0000",
      "preview": "验证码为 123456",
      "code": "123456",
      "links": []
    }
  ]
}

如果只想立即查一次，仍可使用 GET /api/v1/mailboxes/{email}/messages。高并发场景不要用死循环刷查件接口。

5. Outlook 凭据查信

如果你的软件已有 Outlook OAuth 凭据，可以直接提交完整凭据格式。

curl -X POST https://glulu.me/api/v1/outlook/messages \
  -H "X-Glulu-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "raw_input": "email----password----client_id----refresh_token",
    "limit": 1,
    "skip": 0
  }'

返回结构同样包含 latest_code。系统会自动处理 IMAP/Graph 读取和 refresh token 轮换。

6. JavaScript 示例

适合 Node.js 或 Electron 软件接入。

const API_KEY = process.env.GLULU_API_KEY;

async function createMailbox(domain = "qhua.edu.evofu.com") {
  const res = await fetch("https://glulu.me/api/v1/mailboxes", {
    method: "POST",
    headers: {
      "X-Glulu-Api-Key": API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      domain,
      mailbox_mode: "temporary",
      auto_generate: true
    })
  });
  if (!res.ok) throw new Error(await res.text());
  return await res.json();
}

async function waitCode(email) {
  const res = await fetch(
    `https://glulu.me/api/v1/mailboxes/${encodeURIComponent(email)}/wait-code?timeout_seconds=60&poll_interval_seconds=2`,
    { headers: { "X-Glulu-Api-Key": API_KEY } }
  );
  const data = await res.json();
  if (data.latest_code) return data.latest_code;
  throw new Error("验证码等待超时");
}

7. 错误处理

软件应按 HTTP 状态码处理，不要无限重试。

401API Key 缺失或错误。

400参数错误、域名未接入、邮箱格式不合法。

404邮箱不存在或已删除。

429调用过快，按 retry_after_seconds 等待。

5xx服务端或邮件服务暂时不可用，稍后重试。