📚 API 使用文档 V2.0

🌟 V2.0 新特性

🚀 快速开始

📧 1. 生成临时邮箱

基础用法

请求参数（全部可选）：

{
  "provider": "tempmail",   // 可选：邮箱源ID（默认tempmail）
  "prefix": "mytest",       // 可选：自定义前缀（仅部分源支持）
  "mode": "fast"            // 可选：'fast'=智能最快模式
}

响应格式（V2新增字段）：

{
  "success": true,
  "data": {
    "email": "mytest@fexpost.com",
    "provider": "tempmail",        // ← V2新增：使用的邮箱源
               // ← V2新增：
  }
}

推荐Provider（核心源）

1. Temp-Mail.org（最快推荐）⚡

速度: 0.3秒 | 支持前缀: ✅

curl -X POST https://mail.mickeyhub.com/api/generate-email \
  -H "Content-Type: application/json" \
  -d '{"provider": "tempmail", "prefix": "test"}'

// 响应
{
  "success": true,
  "data": {
    "email": "test@fexpost.com",
    "provider": "tempmail",
    
  }
}

2. GuerrillaMail（稳定快速）⚡

速度: 0.5秒 | 支持前缀: ❌（自动生成）

curl -X POST https://mail.mickeyhub.com/api/generate-email \
  -d '{"provider": "guerrilla"}'

// 响应
{
  "success": true,
  "data": {
    "email": "vbtjbgjg@guerrillamailblock.com",
    "provider": "guerrilla",
    
  }
}

3. Mail.tm（完整API支持）⚡

速度: 0.8秒 | 支持前缀: ✅ | 返回Token: ✅

curl -X POST https://mail.mickeyhub.com/api/generate-email \
  -d '{"provider": "mailtm", "prefix": "test"}'

// 响应（包含JWT token）
{
  "success": true,
  "data": {
    "email": "test@airsworld.net",
    "token": "eyJ0eXAiOiJKV1Q...",
    "id": "695f0eca...",
    "provider": "mailtm",
    
  }
}

4. 智能最快模式 ⚡

速度: 2秒 | 特点: 并发所有核心源，返回最快的

curl -X POST https://mail.mickeyhub.com/api/generate-email \
  -d '{"mode": "fast"}'

// 响应
{
  "success": true,
  "data": {
    "email": "b1d5a1e0@fexbox.org",
    "provider": "tempmail"    // 自动选择了最快的
  }
}

其他核心源：

📦 2. 查看所有邮箱源（V2新增）

响应示例：

{
  "success": true,
  "data": {
    "total": 70,
    "core": 6,
    "extended": 64,
    "providers": [
      {
        "id": "tempmail",
        "name": "Temp-Mail.org",
        "url": "https://temp-mail.org",
        "type": "core",
        "recommended": true,
        "supportPrefix": true    // 是否支持自定义前缀
      },
      {
        "id": "guerrilla",
        "name": "GuerrillaMail",
        "url": "https://www.guerrillamail.com",
        "type": "core",
        "recommended": true,
        "supportPrefix": false   // 不支持自定义前缀
      },
      ...（共70个）
    ]
  }
}

cURL 示例：

curl https://mail.mickeyhub.com/api/providers

筛选推荐源：

curl https://mail.mickeyhub.com/api/providers | \\
  jq '.data.providers[] | select(.recommended == true)'

查看支持前缀的源：

curl https://mail.mickeyhub.com/api/providers | \\
  jq '.data.providers[] | select(.supportPrefix == true)'

📬 3. 获取邮件列表

路径参数：

• email - 邮箱地址（需URL编码）

查询参数（V2新增）：

• provider - 邮箱源ID（必须与生成时使用的相同）

响应示例：

{
  "success": true,
  "data": {
    "emails": [
      {
        "id": "msg_123",
        "subject": "欢迎注册",
        "from_address": "noreply@example.com",
        "timestamp": "2025-01-08T10:30:00Z",
        "is_read": false
      }
    ]
  }
}

cURL 示例：

curl "https://mail.mickeyhub.com/api/emails/test@fexpost.com?provider=tempmail"

JavaScript 示例：

const email = 'test@fexpost.com';
const provider = 'tempmail';

const response = await fetch(
  `https://mail.mickeyhub.com/api/emails/${encodeURIComponent(email)}?provider=${provider}`
);
const data = await response.json();
console.log('邮件列表:', data.data.emails);

📄 4. 查看邮件详情

路径参数：

• id - 邮件ID

查询参数：

• provider - 邮箱源ID

cURL 示例：

curl "https://mail.mickeyhub.com/api/email/msg_123?provider=tempmail"

📊 5. 获取统计信息（V2新增）

响应示例：

{
  "success": true,
  "data": {
    "total_providers": 70,
    "core_providers": 6,
    "extended_providers": 64,
    "core_list": [
      {
        "id": "tempmail",
        "name": "Temp-Mail.org",
        "recommended": true
      },
      ...
    ],
    "mode": "multi-source-v2"
  }
}

cURL 示例：

curl https://mail.mickeyhub.com/api/stats

💡 完整使用流程

Node.js 完整示例

const API_BASE = 'https://mail.mickeyhub.com';

async function example() {
  // 1. 查看所有可用的邮箱源
  const providersResp = await fetch(`${API_BASE}/api/providers`);
  const providers = await providersResp.json();
  console.log('可用邮箱源:', providers.data.total); // 70

  // 2. 使用Temp-Mail.org生成邮箱（最快0.3秒）
  const genResp = await fetch(`${API_BASE}/api/generate-email`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      provider: 'tempmail',  // 选择邮箱源
      prefix: 'mytest'       // 自定义前缀
    })
  });

  const genData = await genResp.json();
  const email = genData.data.email;
  const provider = genData.data.provider;

  console.log('邮箱:', email);          // mytest@fexpost.com
  console.log('来源:', provider);       // tempmail

  // 3. 等待接收邮件（实际使用中向该邮箱发送邮件）
  await new Promise(resolve => setTimeout(resolve, 10000));

  // 4. 获取邮件列表（必须传入provider参数）
  const emailsResp = await fetch(
    `${API_BASE}/api/emails/${encodeURIComponent(email)}?provider=${provider}`
  );
  const emailsData = await emailsResp.json();

  console.log('收到邮件:', emailsData.data.emails.length);

  // 5. 查看第一封邮件详情
  if (emailsData.data.emails.length > 0) {
    const firstEmail = emailsData.data.emails[0];
    const detailResp = await fetch(
      `${API_BASE}/api/email/${firstEmail.id}?provider=${provider}`
    );
    const detail = await detailResp.json();

    console.log('邮件主题:', detail.data.subject);
    console.log('邮件内容:', detail.data.content);
  }
}

example();

Python 完整示例

import requests
from urllib.parse import quote

API_BASE = 'https://mail.mickeyhub.com'

# 1. 查看所有邮箱源
providers = requests.get(f'{API_BASE}/api/providers').json()
print(f'可用邮箱源: {providers["data"]["total"]}')  # 70

# 2. 使用Mail.tm生成邮箱（返回token）
response = requests.post(f'{API_BASE}/api/generate-email',
                        json={'provider': 'mailtm', 'prefix': 'test'})
data = response.json()['data']

email = data['email']
provider = data['provider']
token = data.get('token')  # Mail.tm会返回token

print(f'邮箱: {email}')        # test@airsworld.net
print(f'来源: {provider}')     # mailtm
print(f'Token: {token}')       # eyJ0eXAiOiJKV1Q...

# 3. 获取邮件列表（传入provider参数）
emails_resp = requests.get(
    f'{API_BASE}/api/emails/{quote(email)}',
    params={'provider': provider}
)
emails = emails_resp.json()['data']['emails']

print(f'邮件数: {len(emails)}')

# 4. 智能最快模式
fast_resp = requests.post(f'{API_BASE}/api/generate-email',
                         json={'mode': 'fast'})
fast_data = fast_resp.json()['data']

print(f'智能模式邮箱: {fast_data["email"]}')
print(f'自动选择的provider: {fast_data["provider"]}')

Shell / Bash 完整示例

#!/bin/bash

# 1. 查看所有邮箱源
echo "=== 查看邮箱源 ==="
curl -s https://mail.mickeyhub.com/api/providers | \\
  jq '.data | {total, core, extended}'

# 2. 使用GuerrillaMail生成（不支持前缀）
echo -e "\\n=== 生成邮箱 ==="
RESPONSE=$(curl -s -X POST https://mail.mickeyhub.com/api/generate-email \\
  -H "Content-Type: application/json" \\
  -d '{"provider": "guerrilla"}')

EMAIL=$(echo $RESPONSE | jq -r '.data.email')
PROVIDER=$(echo $RESPONSE | jq -r '.data.provider')

echo "邮箱: $EMAIL"
echo "来源: $PROVIDER"

# 3. 获取邮件列表
echo -e "\\n=== 获取邮件 ==="
curl -s "https://mail.mickeyhub.com/api/emails/$EMAIL?provider=$PROVIDER" | \\
  jq '.data.emails'

🌐 70+个可用邮箱源

核心源（6个）

手动优化，高性能，始终可用

• ✅ tempmail - Temp-Mail.org (0.3秒)
• ✅ guerrilla - GuerrillaMail (0.5秒)
• ✅ mailtm - Mail.tm (0.8秒)
• ✅ tempmailio - Temp-Mail.io (1.0秒)
• ✅ chatgpt - ChatGPT Mail (1.8秒)
• ✅ tenminute - 10MinuteMail (2.0秒)

扩展源（64个）

自动生成，按需加载

包括：yopmail, mailinator, maildrop, getnada, snapmail, mailsac, dropmail 等64个网站

查看完整列表：

访问 /providers.html 查看所有70个邮箱源的详细信息

curl https://mail.mickeyhub.com/api/providers | \\
  jq '.data.providers[] | {id, name, type, supportPrefix}'

⚠️ 错误处理

错误响应格式：

{
  "success": false,
  "error": "错误描述信息"
}

HTTP 状态码：

📌 重要说明

• ✅ V2支持70+个邮箱源，通过provider参数选择
• ✅ 不指定provider时默认使用tempmail（最快）
• ✅ 使用mode: "fast"启用智能最快模式
• ✅ 获取邮件时必须传入provider参数（与生成时相同）
• ⚠️ 部分provider不支持自定义前缀（如guerrilla, tenminute）
• ⚠️ 扩展源默认不支持自定义前缀
• ⚠️ Mail.tm返回token，可用于后续API调用
• 📅 邮件自动保存24小时后删除（各源规则不同）

⚡ 性能对比

📝 V2.0 更新日志

新增功能

• ✅ 聚合70+个临时邮箱服务商
• ✅ provider 参数 - 选择邮箱源
• ✅ mode: "fast" - 智能最快模式
• ✅ GET /api/providers - 获取所有邮箱源
• ✅ GET /api/stats - 获取统计信息
• ✅ 响应包含 provider 字段
• ✅ supportPrefix 字段 - 标识是否支持前缀

性能提升

• ⚡ 最快速度: 1.8秒 → 0.3秒 (提升83%)
• 📦 邮箱源数: 1个 → 70+个
• 🌐 域名总数: 9个 → 400+个

Breaking Changes

• ⚠️ 获取邮件时建议传入provider参数
• ⚠️ 响应格式新增provider和source字段
• ⚠️ 默认provider从chatgpt改为tempmail

📦 测试工具

Postman Collection

下载 Postman 集合快速测试 API：

测试脚本

在服务器上运行：

cd /root/gptmail-api
./test-all-providers.sh

🔗 相关链接

• 返回首页 - 使用Web界面
• 查看所有邮箱源 - 70+个源的详细信息
• GitHub仓库 - 私密仓库