API密钥文档

概述

API密钥允许高级用户无需登录验证即可访问邮箱验证API。API密钥端点使用单独的前缀 /api/v1/ 且不需要加密。

要求

仅高级计划：API密钥功能仅适用于高级用户
每个用户只能拥有一个API密钥
API密钥端点不使用加密（纯文本请求/响应）

入门

1. 生成API密钥

首先，您需要通过Web界面生成API密钥：

登录您的账户
点击您的个人资料菜单
选择"API密钥"（仅对高级用户可见）
点击"生成API密钥"
重要：立即复制并保存您的API密钥 - 您将无法再次查看它！

⚠️ 警告：生成后您将无法再次查看您的API密钥。请安全保存。

2. 使用API密钥

API密钥可以通过三种方式提供：

X-API-Key Header（推荐）:
```
X-API-Key: your-api-key-here
```
Authorization Header:
```
Authorization: Bearer your-api-key-here
```
Query Parameter（不太安全）:
```
?apiKey=your-api-key-here
```

API端点

所有API密钥端点使用 /api/v1/ 前缀且不需要加密。

1. 检查邮箱

提交任务以检查邮箱地址。

Endpoint:

POST /api/v1/check-emails

Request:

{
  "input": "[email protected]\[email protected]\[email protected]"
}

Response:

{
  "success": true,
  "code": "JOB_SUBMITTED",
  "message": "Job submitted successfully",
  "data": {
    "jobId": "job-123-1234567890",
    "status": "pending",
    "emailsCount": 3
  }
}

2. 获取任务历史

获取分页的任务列表。

Endpoint:

GET /api/v1/jobs/history?page=1&limit=20

3. 获取任务统计

获取特定任务的汇总统计信息。

Endpoint:

GET /api/v1/jobs/:jobId/stats

4. 获取任务详情

获取完整的任务详情，包括所有结果。

Endpoint:

GET /api/v1/jobs/:jobId

5. 获取使用统计

获取您当前的使用统计信息。

Endpoint:

GET /api/v1/usage

代码示例

cURL示例

# Check Gmail addresses
curl -X POST https://api.gmcheck.live/api/v1/check-emails \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"input": "[email protected]\[email protected]"}'

# Get job stats
curl -X GET https://api.gmcheck.live/api/v1/jobs/job-123-1234567890/stats \
  -H "X-API-Key: your-api-key-here"

Python示例

import requests

API_KEY = "your-api-key-here"
BASE_URL = "https://api.gmcheck.live/api/v1"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# Check emails
response = requests.post(
    f"{BASE_URL}/check-emails",
    headers=headers,
    json={"input": "[email protected]\[email protected]"}
)
job_data = response.json()
job_id = job_data["data"]["jobId"]

# Get job stats
stats_response = requests.get(
    f"{BASE_URL}/jobs/{job_id}/stats",
    headers=headers
)
stats = stats_response.json()
print(stats)

JavaScript示例

const API_KEY = "your-api-key-here";
const BASE_URL = "https://api.gmcheck.live/api/v1";

const headers = {
  "X-API-Key": API_KEY,
  "Content-Type": "application/json"
};

// Check Gmail addresses
const checkEmails = async () => {
  const response = await fetch(`${BASE_URL}/check-emails`, {
    method: "POST",
    headers: headers,
    body: JSON.stringify({
      input: "[email protected]\[email protected]"
    })
  });
  
  const data = await response.json();
  const jobId = data.data.jobId;
  
  // Poll for job completion
  const pollJob = async () => {
    const statsResponse = await fetch(`${BASE_URL}/jobs/${jobId}/stats`, {
      headers: headers
    });
    const stats = await statsResponse.json();
    
    if (stats.data.status === "completed") {
      // Get full results
      const detailResponse = await fetch(`${BASE_URL}/jobs/${jobId}`, {
        headers: headers
      });
      const detail = await detailResponse.json();
      console.log(detail.data.result);
    } else {
      // Poll again after delay
      setTimeout(pollJob, 2000);
    }
  };
  
  pollJob();
};

邮箱状态值

LIVE: 邮箱有效且活跃
VERIFY: 邮箱需要验证
DISABLE: 邮箱已禁用
NOT_EXIST: 邮箱不存在
UNKNOWN: 未知状态
PENDING: 邮箱仍在处理中

任务状态值

pending: 任务已排队等待处理
processing: 任务正在处理中
completed: 任务已成功完成
stopped: 任务已被用户停止
failed: 任务未能完成

安全最佳实践

永远不要分享您的API密钥：将API密钥视为密码:
使用环境变量：将API密钥存储在环境变量中，而不是代码中:
定期轮换：定期重新生成您的API密钥:
如果泄露则撤销：如果您怀疑API密钥已泄露，请立即撤销:
仅使用HTTPS：进行API请求时始终使用HTTPS:
监控使用情况：定期检查使用统计信息以检测未经授权的访问:

错误响应

Invalid API Key:

{
  "success": false,
  "code": "INVALID_API_KEY",
  "message": "Invalid API key. Please check your API key and try again."
}

Premium Required:

{
  "success": false,
  "code": "PREMIUM_REQUIRED",
  "message": "API key feature is only available for premium users."
}

Monthly Limit Exceeded:

{
  "success": false,
  "code": "MONTHLY_LIMIT_EXCEEDED",
  "message": "Monthly limit exceeded. You have checked 100000 / 100000 emails this month."
}

支持

有关API密钥的问题或疑问，请通过联系页面或Telegram联系支持。