多类型邮箱收件与账号领取

自动化邮箱 API

适合 AI 自动化的邮箱服务,为自动化注册、验证码接收、Outlook 接码和完整账号领取场景提供稳定能力。调用接口获取邮箱或账号资料,再按类型查询最新邮件。

充值比例 1 RMB = 100 额度 1 USDT = 670 额度

邮箱库存

实时展示各接码服务当前可用的邮箱域名及数量,每 3 分钟更新一次。

邮箱类型列表

根据业务场景选择邮箱来源:自定义域名、Edu 教育邮箱、Gmail 和 iCloud 邮箱适合常规验证码;长效苹果隐私邮箱和 Outlook 可由平台查询验证码;短效 Outlook、美国教育邮箱、全新 Google 邮箱接码及完整 Google/Outlook 账号领取会返回邮箱地址或完整账号资料。

接口调用方式

先获取一个邮箱地址,再用返回的邮箱名称查询最新邮件;需要查看额度时可直接查询余额。

1. 获取邮箱

`type` 选择不同邮箱类型,系统按类型返回邮箱地址或完整账号资料;`google-code` 需指定 `service`。点击右侧复制按钮可复制完整请求地址。

企业域名邮箱 /api/user/email?type=domain&apikey={KEY}
教育邮箱 /api/user/email?type=edu&apikey={KEY}
长效苹果隐私邮箱 /api/user/email?type=private-icloud&apikey={KEY}
长效 Outlook 邮箱 /api/user/email?type=outlook&apikey={KEY}
短效 Outlook 邮箱 /api/user/email?type=short-outlook&apikey={KEY}
Outlook 账号领取 /api/user/email?type=outlook-account&apikey={KEY}
美国教育邮箱 /api/user/email?type=us-edu&apikey={KEY}
Gmail 子邮箱 /api/user/email?type=gmail&apikey={KEY}
iCloud 子邮箱 /api/user/email?type=icloud&apikey={KEY}
Google 账号领取 /api/user/email?type=google-account&apikey={KEY}
选择邮箱和服务 /api/user/email?type=google-code|outlook-code|icloud-code|yandex-code|rambler-code|mail-code|email-code|gmx-code&service=github|paypal|line|claude|commandcode|linkedin|aws|openai|openrouter|perplexity|puter|runninghub|apple|cursor|grok|manus|figma|leonardo|facebook|dropshot|capcut|tinder|vani|vinted|telegram|tiktok|yeblock|notion|strava|adobe|arena&apikey={KEY}
Google 单次收码 · claude /api/user/email?type=google-code-one&service=claude&apikey={KEY}
Google 单次收码 · openai /api/user/email?type=google-code-one&service=openai&apikey={KEY}
Google 单次收码 · aws /api/user/email?type=google-code-one&service=aws&apikey={KEY}
Google 单次收码 · telegram /api/user/email?type=google-code-one&service=telegram&apikey={KEY}
Google 单次收码 · tiktok /api/user/email?type=google-code-one&service=tiktok&apikey={KEY}
Google 单次收码 · github /api/user/email?type=google-code-one&service=github&apikey={KEY}
查看返回结果示例
获取邮箱返回
{
  "code": 0,
  "message": "success",
  "data": {
    "type": "domain",
    "email": "m261a02vf7f@example.com"
  }
}
领取 Outlook 账号返回
{
  "code": 0,
  "message": "success",
  "data": {
    "type": "outlook-account",
    "email": "user@outlook.com",
    "account": "user@outlook.com",
    "password": "password",
    "client_id": "14d82eec-204b-4c2f-b7e8-296a70dab67e",
    "token": "refresh_token"
  }
}
2. 查询邮件

把第一步返回的邮箱填入 `email`,获取该邮箱最新一封邮件。

/api/user/mail?email={邮箱名称}&apikey={KEY}
查看返回结果示例
查询邮件返回
{
  "code": 0,
  "message": "success",
  "data": {
    "from": "sender@gmail.com",
    "to": "m261a02vf7f@example.com",
    "subject": "新邮件通知",
    "text": "your code is 123456",
    "code": "123456"
  }
}
3. 查询余额

查看当前 KEY 的总额度、已用额度和剩余额度。

/api/user/quota?apikey={KEY}
查看返回结果示例
查询余额返回
{
  "code": 0,
  "message": "success",
  "data": {
    "quota_total": 100,
    "quota_used": 3,
    "quota_left": 97
  }
}
4. 触发邮箱激活

复制邮箱时 fire-and-forget 调用,触发后端查询/重新激活,不扣费、不返回验证码内容。

POST /api/user/activate · Header X-API-Key · Body {"email":"{邮箱名称}"}
5. 分享接码(免 Key)

获取邮箱时带 share=1 生成 share_token,他人用此链接免 API Key 直接查看邮件 HTML。

/api/share/{share_token}

AI IDE 对接 Skill

把下面内容复制给 AI IDE,它会按本系统的接口规则完成接入代码、配置和调用流程。

展开 Skill 内容
Skill 内容
# 自动化邮箱 API 接入 Skill

你需要帮助用户把“自动化邮箱 API”接入到当前项目中。

## 接入目标

实现以下能力:
- 获取一个可用于收件的邮箱地址,或领取一个完整 Outlook 账号;可选生成分享 token。
- 使用该邮箱查询最新一封邮件。
- 可选:触发邮箱激活(不扣费)。
- 可选:通过分享 token 免 API Key 查看邮件。
- 可选:查询当前 API Key 的额度。
- 可选:取消未接码邮箱并退款。

## 基础配置

接入前必须先询问用户以下信息:
- 请求域名:接口服务的完整域名或地址,例如 `https://your-domain.com`
- API Key:用户的接口密钥

拿到用户提供的信息后,必须保存到项目配置中。

不要把 API Key 写死在业务代码里。

需要的配置项:
- EMAIL_API_BASE_URL:用户提供的请求域名
- EMAIL_API_KEY:用户提供的 API Key

## 鉴权方式

只使用 GET 接口和 URL Query 鉴权:
- URL Query:`apikey={EMAIL_API_KEY}`

所有示例请求都把 API Key 放在 URL 参数中。

## 接口

### 1. 获取邮箱

GET `/api/user/email?type=domain&apikey={EMAIL_API_KEY}`

参数:
- type:可选,`domain`、`edu`、`gmail`、`icloud`、`private-icloud`、`outlook`、`outlook-account`、`short-outlook`、`us-edu`、`google-code`、`google-code-one`、`outlook-code`、`icloud-code`、`yandex-code`、`rambler-code`、`mail-code`、`email-code`、`gmx-code` 或 `google-account`,默认 `domain`
- service:当 `type=google-code`、`google-code-one`、`outlook-code`、`icloud-code`、`yandex-code`、`rambler-code`、`mail-code`、`email-code` 或 `gmx-code` 时必填,传入服务名(如 `github`、`paypal`、`line`、`claude`、`commandcode`、`linkedin`、`aws`、`openai`、`openrouter`、`perplexity`、`puter`、`runninghub`、`apple`、`cursor`、`grok`、`manus`、`figma`、`leonardo`、`facebook`、`dropshot`、`capcut`、`tinder`、`vani`、`vinted`、`telegram`、`tiktok`、`yeblock`、`notion`、`strava`、`adobe`、`arena`)选择接码服务(`manus` 仅支持 `outlook-code`、`icloud-code`)
- share:可选,`share=1` 时为该订单生成 64 字符 `share_token`,可用于免 API Key 的分享接码接口;每个订单只生成一次,返回在 `data.share_token`

类型说明:
- `domain`:自定义域名邮箱,返回邮箱地址,用平台邮件接口查码。
- `edu`:教育邮箱,适合需要学校或教育邮箱环境的注册、验证和测试场景。
- `gmail`:Gmail 子邮箱,返回邮箱地址,用平台邮件接口查码;不支持注册 openai、claude。
- `icloud`:iCloud 子邮箱,返回邮箱地址,用平台邮件接口查码;不支持注册 openai、claude。
- `private-icloud`:长效苹果隐私邮箱,仅含邮箱地址,适合接收常规验证码。
- `outlook`:Outlook/Hotmail 平台接码邮箱,只返回邮箱地址,用平台邮件接口查码。
- `outlook-account`:完整 Outlook 账号领取,返回账号、密码、clientId、token 等资料,可自行使用。
- `short-outlook`:短效 Outlook/Hotmail 邮箱,有效期约一个月,只返回邮箱地址,用平台邮件接口查码。
- `us-edu`:真实美国教育邮箱,返回账号和密码,可自行登录使用。
- `google-code`:全新 Google 邮箱,可作为母号裂变使用,查询验证码不另收费;有效期 1–7 天,需指定 service 参数。
- `google-code-one`:Google 单次收码邮箱,母号、只支持单次查询,不可裂变;仅适用于 openai、claude、aws、telegram、tiktok、github,需指定 service 参数。
- `outlook-code`:Outlook 超低价接码,母号、收码,可裂变,查询不收费;需指定 service 参数。
- `icloud-code`:iCloud 高性价比接码,母号、收码,可裂变,查询不收费;需指定 service 参数。
- `yandex-code`:Yandex 接码(yandex.com),母号、收码,查询不收费;需指定 service 参数。
- `rambler-code`:Rambler 接码(rambler.ru),母号、收码,查询不收费;需指定 service 参数。
- `mail-code`:Mail.com 接码(mail.com),母号、收码,查询不收费;需指定 service 参数。
- `email-code`:Email.com 接码(email.com),母号、收码,查询不收费;需指定 service 参数。
- `gmx-code`:GMX 接码(gmx.com),母号、收码,查询不收费;需指定 service 参数。
- `google-account`:完整 Google 账号领取,返回账号、密码、2FA 密钥、注册 IP 地区、session、cookie 等资料,可自行使用。

成功返回:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "type": "domain",
    "email": "m261a02vf7f@example.com"
  }
}
```

使用 `data.email` 作为注册、验证或测试时的收件邮箱。

`outlook-account` 返回示例:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "type": "outlook-account",
    "email": "user@outlook.com",
    "account": "user@outlook.com",
    "password": "password",
    "client_id": "14d82eec-204b-4c2f-b7e8-296a70dab67e",
    "token": "refresh_token"
  }
}
```

### 2. 查询最新邮件

GET `/api/user/mail?email={email}&apikey={EMAIL_API_KEY}`

参数:
- email:获取邮箱接口返回的 `data.email`

成功且有邮件时返回:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "from": "sender@gmail.com",
    "to": "m261a02vf7f@example.com",
    "subject": "新邮件通知",
    "text": "your code is 123456",
    "code": "123456"
  }
}
```

成功但暂时没有邮件时返回:
```json
{
  "code": 0,
  "message": "success"
}
```

如果业务需要等待邮件,请实现轮询:
- 每 3 到 5 秒查询一次。
- 最多等待 60 到 120 秒。
- 查询到 `data` 后停止轮询。
- 没有邮件时不要当成错误。

### 3. 查询余额

GET `/api/user/quota?apikey={EMAIL_API_KEY}`

成功返回:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "quota_total": 100,
    "quota_used": 3,
    "quota_left": 97
  }
}
```

### 4. 触发邮箱激活

POST `/api/user/activate`,Header `X-API-Key: {EMAIL_API_KEY}`,Body `{"email":"{email}"}`

fire-and-forget 调用,触发后端查询/重新激活,**不扣费、不返回验证码内容**。验证码必须走"2. 查询最新邮件"接口扣费获取。适合用户复制邮箱时预热,加快后续接码。

成功返回:
```json
{ "code": 0, "message": "success" }
```

### 5. 分享接码(免 API Key)

GET `/api/share/{share_token}`

浏览器直接访问,无需 API Key。按 `share_token` 查订单并直接输出邮件 HTML。失败/取消的订单链接自动失效。

`share_token` 在"1. 获取邮箱"时带 `share=1` 生成,返回在 `data.share_token`。

### 6. 取消邮箱(退款)

GET `/api/user/email/cancel?email={email}&apikey={EMAIL_API_KEY}`

未接码(status=1)的 AM 邮箱可主动取消并退款;已接码(status=2)不可取消。邮箱创建满 4 分钟后才可取消,当日取消率上限 10%。

参数:
- email:获取邮箱接口返回的 `data.email`

成功返回:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "refunded": 25
  }
}
```

`refunded` 为实际退还额度,受 `quota_used` 上限约束,可能小于下单成本;并发已处理时返回 0。重复取消(幂等)返回 `{"code":0,"message":"already canceled"}`。

### 7. 查询邮箱库存

GET `/api/open-services`

无需鉴权。返回当前所有开放接码服务下、各邮箱类型(google-code、google-code-one、outlook-code、icloud-code、yandex-code、rambler-code、mail-code、email-code、gmx-code)的可用邮箱域名及数量,每 3 分钟更新一次。

成功返回:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "types": [
      {
        "type": "google-code",
        "services": [
          {"service": "openai", "emails": [{"domain": "gmail.com", "count": 240456}]}
        ]
      }
    ],
    "updated_at": 1726626000
  }
}
```

`count` 为各服务当前可用邮箱数量,仅供展示参考;实际下单以「1. 获取邮箱」接口为准。

## 错误响应

请求失败时 HTTP 状态码非 200,返回格式统一为:
```json
{
  "code": 410,
  "message": "email unavailable"
}
```
`code` 与 HTTP 状态码一致,`message` 为英文错误描述。

常见错误:

| HTTP | message | 含义与处理方式 |
| --- | --- | --- |
| 400 | `missing service parameter` | `google-code`、`google-code-one`、`outlook-code`、`icloud-code`、`yandex-code`、`rambler-code`、`mail-code`、`email-code`、`gmx-code` 类型必须传 service 参数 |
| 400 | `invalid or missing service parameter` | service 值不支持,检查服务名拼写 |
| 400 | `invalid email type` | type 值无效 |
| 400 | `missing email` / `invalid recipient` | 查询邮件时 email 参数缺失或格式错误 |
| 400 | `cannot query mail via base email address` | 不能用母邮箱地址查询,需使用接口返回的邮箱地址 |
| 400 | `email does not support cancellation` | 该邮箱不是 AM 接码邮箱,不支持取消 |
| 400 | `cannot cancel: email created less than 4 minutes ago` | 邮箱创建不足 4 分钟,稍后再取消 |
| 401 | `missing api key` / `invalid api key` | 未传 apikey 或 API Key 无效,检查配置 |
| 402 | `insufficient quota` | 余额不足,提示用户充值,不要重试 |
| 403 | `outlook email does not belong to api key` | 查询的邮箱不属于当前 API Key |
| 403 | `outlook account is blocked due to repeated failures` | 该 Outlook 账号已被锁定,更换邮箱 |
| 403 | `email does not belong to api key` | 该邮箱不属于当前 API Key |
| 404 | `no unused outlook emails` / `no unused google accounts` / `no unused private-icloud emails` | 该类型库存不足,稍后重试或联系客服 |
| 404 | `order not found or canceled` | 订单不存在或已取消 |
| 409 | `cannot cancel: code already received` | 已接码完成,不可取消退款 |
| 410 | `email unavailable` | 邮箱已失效无法收码,费用已自动退回;停止轮询,重新获取新邮箱 |
| 411 | `email banned` | 邮箱已被封禁,无法继续接码;停止轮询,重新获取新邮箱 |
| 429 | `too many pending outlook emails` | 未收码邮箱过多,先完成已有邮箱的收码再获取新邮箱 |
| 429 | `cancel rate limit exceeded (max 10%)` | 当日取消率超过 10% 上限,明日再试 |
| 502 | `email service failed` / `google code api call failed` | 服务暂时失败,稍后重试 |
| 502 | `cancel error` | 上游取消失败,稍后重试 |
| 500 | `internal server error` / `failed to query mail` | 服务器内部错误,稍后重试或联系客服 |
| 500 | `refund failed` | 退款失败,联系客服 |
| 503 | `activation refreshing, retry shortly` | 提示:请重新发送邮件,邮箱激活中 |

处理原则:
- HTTP 状态码非 200 时按上表处理,不要把错误响应当成成功。
- 收到 402、403、409、410、411 时不要重试,直接按提示处理。
- 收到 404、429、500、502、503 时可以间隔几秒后重试;「邮箱创建不足 4 分钟」的稍等满 4 分钟再取消。

## 实现要求

- 如果发现项目已有逻辑、文件或配置发生冲突,必须先询问用户,不能直接运行、覆盖或删除。
- 封装一个独立客户端,例如 `EmailApiClient`、`emailApiClient` 或项目现有命名风格。
- 所有请求都要检查 HTTP 状态码和 JSON 中的 `code`。
- 不要在日志中打印完整 API Key。
- 查询邮件时要兼容“成功但没有 data”的返回。
- 如果响应里存在 `data.code`,可以作为验证码使用;不要假设每封邮件都有验证码。
- 返回给业务层的数据应包含原始 `email`、邮件内容、标题和验证码字段;领取 `outlook-account` 时还应保留账号、密码、clientId 和 token。
- 如果项目已有 HTTP 请求库、重试工具、环境变量读取方式,请优先复用现有项目写法。
- 使用邮箱前请先调用一次"2. 查询最新邮件"或调用"4. 触发邮箱激活"接口,防止邮箱因长时间未激活而被回收或失效。

## 推荐封装方法

- `createEmail(type?: string, service?: string, share?: boolean)`
- `getLatestMail(email: string)`
- `waitForLatestMail(email: string, options?: { timeoutMs?: number; intervalMs?: number })`
- `getQuota()`
- `getLatestMailHtml(email: string)`
- `activateEmail(email: string)` — fire-and-forget 触发激活,不扣费
- `getShareUrl(shareToken: string)` — 拼接免 key 分享链接
- `cancelEmail(email: string)` — 取消未接码邮箱并退款
- `getEmailInventory()` — 查询开放服务邮箱库存(免鉴权)

请根据当前项目语言和框架生成代码,并补充最小可运行示例。

使用流程

  • 1
    调用获取邮箱接口,选择 domain、edu、gmail、icloud、private-icloud、outlook、outlook-account、short-outlook、us-edu、google-code、google-code-one、outlook-code、icloud-code、yandex-code、rambler-code、mail-code、email-code、gmx-code 或 google-account 类型。
  • 2
    系统返回邮箱地址;如果选择 outlook-account、us-edu 或 google-account,会返回完整账号资料。
  • 3
    把返回的邮箱用于注册、验证或测试收件。
  • 4
    邮件到达后,通过查询接口获取最新邮件内容。