API 文档

对外接码 API 的完整参考。用 API 密钥以 Bearer Token 调用，自动申请临时邮箱并拉取验证码。

快速开始

先到 API 密钥创建一个密钥，然后两步拿到验证码：申请临时邮箱 → 长轮询拉取最新验证码。

基础地址

https://email.magic666.xyz/v1

示例地址，实际公网地址以部署为准。

认证

所有请求在 Header 携带 Bearer Token（你的 API 密钥）：

Authorization: Bearer mek_live_xxxxxxxx

密钥的权限（只读/读写/所有）与域名范围在创建时设定；只读密钥不能创建/释放邮箱。

接口清单

GET

/v1/domains

获取可用域名（免费）

返回平台当前可用的域名列表，B 端据此拿到 domainId 再去创建邮箱。此接口不计费。

curl https://email.magic666.xyz/v1/domains \
  -H "Authorization: Bearer mek_live_xxx"

# 响应示例
# {
#   "code": 0,
#   "msg": "success",
#   "data": [
#     { "id": 1, "domain": "mail.example.com" },
#     { "id": 2, "domain": "inbox.example.com" }
#   ]
# }

POST

/v1/inbox

创建临时邮箱

申请一个临时邮箱（对外 API 仅支持临时邮箱，持久「网页邮箱」是网页端能力）。可带 Idempotency-Key 头防网络重试重复创建。

参数	类型	必填	说明
domainId	number	必填	域名 ID（在控制台或域名列表获取）
prefix	string	可选	自定义前缀，留空则随机生成
ttlSeconds	number	可选	有效期秒数；不传=默认 24h（API 不支持创建永久邮箱）

curl -X POST https://email.magic666.xyz/v1/inbox \
  -H "Authorization: Bearer mek_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"domainId": 1, "ttlSeconds": 600}'

GET

/v1/inbox/{address}

查询邮箱信息

按邮箱地址查询其状态、收件数、有效期、备注（note）与标签（tags，名称数组）。

参数	类型	必填	说明
address	path	必填	完整邮箱地址，如 [email protected]

curl https://email.magic666.xyz/v1/inbox/[email protected] \
  -H "Authorization: Bearer mek_live_xxx"

GET

/v1/inbox/{address}/messages

拉取收件列表

获取该邮箱的收件摘要（含已提取的验证码，不含正文）。支持分页：page 与 limit 配合翻页。

参数	类型	必填	说明
address	path	必填	完整邮箱地址
page	query	可选	页码，默认 1
limit	query	可选	每页数量，默认 50，最大 200

curl "https://email.magic666.xyz/v1/inbox/[email protected]/messages?page=1&limit=20" \
  -H "Authorization: Bearer mek_live_xxx"

# 分页响应：data 内为 { list, total, page, size }

GET

/v1/inbox/{address}/messages/{id}

查询单封邮件详情

获取单封邮件的完整内容，比收件列表多了正文字段：textBody（纯文本）、htmlBody（HTML）、rawHeaders（原始邮件头）。

参数	类型	必填	说明
address	path	必填	完整邮箱地址
id	path	必填	邮件 ID（拉取收件列表返回的 id）

curl https://email.magic666.xyz/v1/inbox/[email protected]/messages/123 \
  -H "Authorization: Bearer mek_live_xxx"

# 响应示例（data 字段节选）
# {
#   "id": 123,
#   "fromAddress": "[email protected]",
#   "subject": "Your verification code",
#   "extractedCode": "123456",
#   "textBody": "Your code is 123456",
#   "htmlBody": "<p>Your code is <b>123456</b></p>",
#   "rawHeaders": { "Message-ID": "<...>", "Date": "..." },
#   "receivedAt": "2026-06-10 12:00:00"
# }

POST

/v1/inbox/{address}/messages/{id}/read

标记单封邮件已读

把指定邮件标记为已读（写入读取时间）。需写权限密钥。

参数	类型	必填	说明
address	path	必填	完整邮箱地址
id	path	必填	邮件 ID

curl -X POST https://email.magic666.xyz/v1/inbox/[email protected]/messages/123/read \
  -H "Authorization: Bearer mek_live_xxx"

PUT

/v1/inbox/{address}/note

修改邮箱备注

设置网页邮箱（含购买的 Outlook / Hotmail）的备注，最长 100 字符，首尾空白会去掉，传空串即清除。临时邮箱不支持备注（400）。需写权限密钥。

参数	类型	必填	说明
address	path	必填	完整邮箱地址
note	body	必填	备注内容，空串清除

curl -X PUT https://email.magic666.xyz/v1/inbox/[email protected]/note \
  -H "Authorization: Bearer mek_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"note": "项目A 注册用"}'

# 响应示例（data 字段）
# { "note": "项目A 注册用" }

GET

/v1/inboxes

我的邮箱列表（可按标签筛选）

列出账号下的邮箱，可按类型、来源、关键词筛选。tag 按标签名称筛选一个标签：tagMode=include 只看带该标签的，exclude 排除带该标签的（如找还没注册过某网站的邮箱）；按标签筛选只在网页邮箱里进行。

参数	类型	必填	说明
tag	query	可选	标签名称（不区分大小写）
tagMode	query	可选	include（默认）/ exclude
type	query	可选	temporary / persistent
source	query	可选	platform / outlook / hotmail
keyword	query	可选	地址或备注模糊匹配
page / size	query	可选	页码（默认 1）/ 每页条数（默认 20，最大 100）

# 取一个还没打上 Netflix 标签的网页邮箱
curl "https://email.magic666.xyz/v1/inboxes?tag=Netflix&tagMode=exclude&size=1" \
  -H "Authorization: Bearer mek_live_xxx"

# 响应示例（data 字段）
# { "list": [{ "id": 88, "address": "[email protected]", "source": "hotmail", "unreadCount": 0,
#              "note": "", "tags": ["A站"], ... }], "total": 37, "page": 1, "size": 1 }

POST

/v1/inbox/{address}/tags

给邮箱加标签

按名称给网页邮箱加标签，名称不存在的自动新建（灰色）；每个邮箱最多 20 个标签，每个账号最多 100 个标签。临时邮箱不支持标签（400）。需写权限密钥。

参数	类型	必填	说明
address	path	必填	完整邮箱地址
tags	body	必填	标签名称数组，每个最长 20 字符

curl -X POST https://email.magic666.xyz/v1/inbox/[email protected]/tags \
  -H "Authorization: Bearer mek_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["Netflix"]}'

# 响应示例（data 字段）：邮箱现有的全部标签
# { "tags": ["A站", "Netflix"] }

DELETE

/v1/inbox/{address}/tags/{name}

从邮箱移除标签（免费）

按名称从邮箱上摘掉标签，标签本身保留；邮箱上没有该标签也返回成功。需写权限密钥。

参数	类型	必填	说明
address	path	必填	完整邮箱地址
name	path	必填	标签名称（需 URL 编码）

curl -X DELETE https://email.magic666.xyz/v1/inbox/[email protected]/tags/Netflix \
  -H "Authorization: Bearer mek_live_xxx"

GET

/v1/inbox/{address}/code

长轮询等待验证码

阻塞最多 60 秒，命中最新验证码即返回；无新码超时返回 {"code": null}。since 只等该 Unix 时刻之后到达的新码。每次请求计 1 次额度（含超时无码）。

参数	类型	必填	说明
address	path	必填	完整邮箱地址
since	query	可选	Unix 秒；只等此刻之后的新码，避免拿到旧码

curl "https://email.magic666.xyz/v1/inbox/[email protected]/code?since=0" \
  -H "Authorization: Bearer mek_live_xxx"

GET

/v1/outlook/offer

Outlook 报价与库存（免费）

返回单价（分）、单次购买上限与各后缀可购数量。不计调用次数。

curl https://email.magic666.xyz/v1/outlook/offer \
  -H "Authorization: Bearer mek_live_xxx"

# 响应示例（data 字段）
# { "priceCents": 10, "maxQuantity": 50, "stock": { "outlook": 120, "hotmail": 35 } }

POST

/v1/outlook/orders

批量购买 Outlook 邮箱

从号池购买真实的 Outlook / Hotmail 邮箱，归你独占，一次发齐。整单从余额扣费（另计 1 次 API 调用），余额不足返回 402，库存不足返回 409 且不扣费。售出不退不换：之后授权失效的账号只标记失效（凭据接口返回 authFailed=true），不更换、不退款。购买后的收件、长轮询验证码、删除沿用 /v1/inbox/{address} 系列接口；删除后该号作废。带 Idempotency-Key 头重试返回同一订单、不重复扣费。

参数	类型	必填	说明
quantity	body	必填	购买数量，1 到 offer 返回的 maxQuantity
brand	body	可选	后缀：outlook / hotmail，不传为不限
note	body	可选	备注，最长 100 字符；记在订单上，本单发出的每个邮箱都带上

curl -X POST https://email.magic666.xyz/v1/outlook/orders \
  -H "Authorization: Bearer mek_live_xxx" \
  -H "Idempotency-Key: 7b0f5c1e-..." \
  -H "Content-Type: application/json" \
  -d '{"quantity": 10, "brand": "hotmail", "note": "项目A"}'

# 响应示例（data 字段）
# {
#   "id": 42, "brand": "hotmail", "quantity": 10,
#   "unitPriceCents": 10, "paidCents": 100, "heldCount": 10, "note": "项目A",
#   "inboxes": [{ "id": 88, "address": "[email protected]", "note": "项目A", ... }]
# }

GET

/v1/outlook/orders/{id}

查询 Outlook 订单

返回订单概要与本单当前仍持有的邮箱（已删除的不含）。

参数	类型	必填	说明
id	path	必填	订单 ID

curl https://email.magic666.xyz/v1/outlook/orders/42 \
  -H "Authorization: Bearer mek_live_xxx"

GET

/v1/outlook/orders/{id}/credentials

导出订单凭据

返回本单仍持有账号的完整凭据列表（已删除的不含）。只读密钥也可调用。

参数	类型	必填	说明
id	path	必填	订单 ID

curl https://email.magic666.xyz/v1/outlook/orders/42/credentials \
  -H "Authorization: Bearer mek_live_xxx"

# 响应示例（data 字段）
# { "list": [{ "email": "[email protected]", "password": "...", "clientId": "...", "refreshToken": "...", "authFailed": false }] }

GET

/v1/outlook/{address}/credentials

查看 Outlook 账号凭据

返回该 Outlook 账号的完整凭据（邮箱、密码、client_id、refresh_token），仅限购买者本人。authFailed 为 true 表示授权已失效（例如你修改了密码），本站将无法继续收信。

参数	类型	必填	说明
address	path	必填	购买到的 Outlook 邮箱地址

curl https://email.magic666.xyz/v1/outlook/[email protected]/credentials \
  -H "Authorization: Bearer mek_live_xxx"

DELETE

/v1/inbox/{address}

释放邮箱（免费）

释放邮箱，停止接收新邮件（已收邮件保留）。清理类操作不计费。

参数	类型	必填	说明
address	path	必填	完整邮箱地址

curl -X DELETE https://email.magic666.xyz/v1/inbox/[email protected] \
  -H "Authorization: Bearer mek_live_xxx"

DELETE

/v1/inbox/{address}/messages/{id}

删除单封邮件（免费）

删除邮箱中的某封邮件（物理删除，不可恢复）。需写权限密钥。清理类操作不计费。

参数	类型	必填	说明
address	path	必填	完整邮箱地址
id	path	必填	邮件 ID（拉取收件列表返回的 id）

curl -X DELETE https://email.magic666.xyz/v1/inbox/[email protected]/messages/123 \
  -H "Authorization: Bearer mek_live_xxx"

错误码

响应体为 { code, msg, data }，成功 code=0。失败时 HTTP 状态码与 code 一致：

状态码	含义
401	API Key 缺失 / 无效 / 已撤销 / 已停用 / 已过期
402	额度已用尽（套餐配额 + 调用池都耗尽，请升级套餐或购买调用包）；亦可能为计费系统临时故障，稍后重试即可
403	权限不足（只读 Key 执行写操作，或域名不在该 Key 的允许范围）
404	邮箱不存在
409	状态冲突（如邮箱地址已被占用）
429	请求过于频繁（超过该 Key 的速率限制）

计费说明

按 API 调用计费：每次调用按「套餐每日配额 → 套餐每月配额 → 调用池」顺序扣减 1 次额度，全部耗尽返回 402（额度不足）。业务失败（4xx/5xx，如邮箱不存在）会自动退还该次额度，净效果是失败不计费。带相同 Idempotency-Key 头重试创建邮箱时同一次只扣一次费。

两类 402：① 额度用尽 —— 需升级套餐或购买调用包； ② 计费系统临时故障（如数据库抖动）—— 此时不放行也不扣费，稍后重试即可，不必升级套餐。

免费接口（不计费）：所有 DELETE（释放邮箱、删除邮件）以及 GET /v1/domains（域名列表）。

长轮询 GET /v1/inbox/{address}/code 每次请求计 1 次（含超时无码也计），因为它替代了客户端的多次轮询。

额度不足时，到套餐订阅升级套餐，或在我的余额购买调用包（永久不过期）。

加载中...