接码 API

iCloud Hide My Email · 公开接口文档

认证方式 公开

每个邮箱别名都有独立的 api_key（格式 alias_xxx）。在管理后台生成邮箱后获取。可通过 query 参数 ?key=xxx 或 header X-API-Key: xxx 传递。

公开接口 用户可用

GET/api/v1/health
健康检查▶

响应示例

{"status": "ok", "time": 1722931200}
GET/api/v1/code?key=xxx
获取最新验证码▶

参数

keystringAPI Key（必填）

响应示例

{"success": true, "email": "xxx@icloud.com", "code": "123456", "mail_count": 3}
GET/api/v1/code/wait?key=xxx&timeout=60
长轮询等待验证码▶

参数

keystringAPI Key（必填） timeoutint最大等待秒数（默认30，最大120）

响应示例

{"success": true, "email": "xxx@icloud.com", "code": "123456", "found": true}
// 超时未收到:
{"success": true, "email": "xxx@icloud.com", "code": "", "found": false, "message": "超时未收到验证码"}
POST/api/v1/code
POST 方式获取验证码（支持长轮询）▶

请求体

{"key": "alias_xxx", "timeout": 60}  // timeout=0 立即返回

响应示例

{"success": true, "email": "xxx@icloud.com", "code": "123456", "found": true}
POST/api/v1/key/rotate
自助更换邮箱 API Key▶

参数

keystring当前 API Key（query/header/body 均可）

响应示例

{"success": true, "email": "xxx@icloud.com", "new_key": "alias_abc123..."}
GET/api/v1/messages?key=xxx
列出邮件▶

参数

keystringAPI Key（必填） limitint返回条数（默认20）

响应示例

{
  "success": true,
  "email": "xxx@icloud.com",
  "count": 2,
  "method": "web_api",
  "messages": [
    {"id": "...", "from": "noreply@example.com", "subject": "验证码 123456", "preview": "...", "date": "2026-08-06T12:00:00+08:00"}
  ]
}

代码示例

JSJavaScript / 浏览器
▶ 
const API = 'http://your-server:8081';
const KEY = 'alias_your_key';

// 获取最新验证码
const res = await fetch(`${API}/api/v1/code?key=${KEY}`);
const data = await res.json();
console.log(data.code); // "123456"

// 长轮询等待验证码（最多60秒）
const res2 = await fetch(`${API}/api/v1/code/wait?key=${KEY}&timeout=60`);
const data2 = await res2.json();
if (data2.found) {
  console.log('收到验证码:', data2.code);
}
PYPython
▶ 
import requests

API = 'http://your-server:8081'
KEY = 'alias_your_key'

# 获取最新验证码
r = requests.get(f'{API}/api/v1/code', params={'key': KEY})
print(r.json()['code'])  # "123456"

# 列出所有邮件
r = requests.get(f'{API}/api/v1/messages', params={'key': KEY, 'limit': 10})
for msg in r.json()['messages']:
    print(f"{msg['date']} | {msg['from']} | {msg['subject']}")
PYPython（POST + 长轮询）
▶ 
import requests

API = 'http://your-server:8081'
KEY = 'alias_your_key'

# POST 长轮询等待验证码
r = requests.post(f'{API}/api/v1/code', json={
    'key': KEY,
    'timeout': 60  # 最多等60秒
})
data = r.json()
if data.get('found'):
    print(f"验证码: {data['code']}")
else:
    print("超时未收到验证码")
接码页面 · iCloud Hide My Email API