目錄

API 文檔

透過 API Key 調用郵箱驗證介面，每次成功調用將扣除該 Key 對應用戶的 1 Credit。

01

調用示例

請求時在 HTTP 標頭中攜帶 API Key，任選其一：

curl -X GET "https://api.emailcheck.org/emailcheck/email/check?email=test%40gmail.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
Base URLhttps://api.emailcheck.org/emailcheck所有接口均使用 HTTPS 协议。
02

響應欄位說明

常见错误（业务码，HTTP 仍返回 200）：C000301 未授权；C000501 试用请求过多；C000603 Credit 不足。

{
  "code": "S000000",
  "debugMessage": "success",
  "userMessage": "Operation successful! Congratulations!",
  "data": {
    "status": 200,
    "email": "test@gmail.com",
    "normalized_email": "test@gmail.com",
    "domain": "gmail.com",
    "domain_authority": 0,
    "domain_age_in_days": 11182,
    "mx": true,
    "mx_records": [
      { "hostname": "gmail-smtp-in.l.google.com", "priority": 5 }
    ],
    "mx_providers": [
      { "slug": "google", "type": "mailbox", "grade": "professional" }
    ],
    "disposable": false,
    "public_domain": true,
    "relay_domain": false,
    "alias": false,
    "role_account": false,
    "spam": false,
    "did_you_mean": null,
    "blocklisted": false
  },
  "requestId": "example-request-id"
}
欄位含義
code业务结果码。已实测成功为 S000000；常见错误为 C000301、C000501、C000603。
debugMessage面向开发者的调试文案，例如 success、unauthorized、too many requests。
userMessage面向终端用户的提示文案。
requestId请求追踪 ID，用于排查日志。
data.status上游校验服务返回的状态码；当前实测成功响应均为 200，不等同于外层 HTTP 状态。
email实际参与校验的邮箱地址。
normalized_email标准化后的邮箱；当前实测通常与输入一致。
domain从邮箱中提取出的域名。
domain_authority域名权重分值；当前实测可能为 0。
domain_age_in_days域名年龄（天）。
mx布尔值：true | false，表示是否存在 MX 记录。
mx_records[].hostnameMX 主机名字符串。
mx_records[].priorityMX 优先级整数。
mx_providers[].slug上游识别出的服务商标识，例如 google、yahoo。
mx_providers[].type服务商类型字符串；当前实测值为 mailbox。
mx_providers[].grade服务商等级字符串；当前实测值包括 professional、basic。
disposable布尔值：true | false，表示是否一次性/临时邮箱。
public_domain布尔值：true | false，表示是否公共邮箱域名。
relay_domain布尔值：true | false，表示是否中继域名。
alias布尔值：true | false，表示是否别名邮箱。
role_account布尔值：true | false，表示是否角色账号（如 admin@ / support@）。
spam布尔值：true | false，表示是否被判定为高垃圾风险。
did_you_mean字符串或 null；检测到拼写建议时返回推荐邮箱，否则为 null。
blocklisted布尔值：true | false，表示域名是否命中封禁名单。

alias、role_account、did_you_mean 基于完整邮箱地址（而非仅域名）判定，属最佳努力字段；部分响应中可能返回默认值 false / null。spam 以域名为粒度判定并长期稳定。

03

单个地址可达性校验

通过 SMTP 握手判断邮箱是否真实可收信，每次扣除 1 Credit。同步请求最多阻塞约 20 秒；未出终态时 status 返回 TIMEOUT_PENDING，用 jobId 走下面的 status 接口继续拉取。

GET https://api.emailcheck.org/emailcheck/email/reachability?email=test%40example.com
Authorization: Bearer YOUR_API_KEY

// Response — 1 Credit is deducted regardless of status
{
  "code": "S000000",
  "data": {
    "jobId": "EVJ...",
    "email": "test@example.com",
    "status": "COMPLETE",            // PENDING | IN-PROGRESS | COMPLETE | FAILED | TIMEOUT_PENDING
    "emailAddressStatus": "VALID",   // VALID | INVALID | UNKNOWN | CATCH_ALL
    "completed": true
  }
}

超时或未出终态时，可用首次返回的 jobId 拉取最新状态，响应结构与单次校验一致。

GET https://api.emailcheck.org/emailcheck/email/reachability/status/{jobId}
Authorization: Bearer YOUR_API_KEY

// Same response shape as the single-check endpoint.
04

批量提交

单次最多 100 个邮箱；按被上游接收的邮箱逐条预扣 1 Credit。本地直接拒绝（格式不合法、批次内重复）当场退回；单个作业超时会在批次终态时自动退款。

POST https://api.emailcheck.org/emailcheck/email/reachability/bulk
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "emails": ["alice@example.com", "bob@example.com"],
  "filename": "my-list.csv",         // optional, for display only
  "source": "api"                     // csv | manual | api (defaults to "manual")
}

// Response
{
  "code": "S000000",
  "data": {
    "bulkId": "EVB...",
    "status": "PROCESSING",           // PROCESSING | COMPLETE | TIMEOUT_PARTIAL
    "requestedCount": 2,
    "acceptedCount": 2,
    "rejectedCount": 0,
    "accepted": [
      { "jobId": "EVJ...", "email": "alice@example.com",
        "status": "PENDING", "emailAddressStatus": "UNKNOWN", "completed": false }
    ],
    "rejected": []                    // { email, status: "FAILED", errorCode, errorMessage }
  }
}
05

管理批次

查看批次详情与进度、分页拉取批内作业、导出 CSV、强制回拉未终态作业、列出当前账号的历史批次。结果由服务商回调或后台 reconciler 回填，无需一直轮询。

# All endpoints below require: Authorization: Bearer YOUR_API_KEY

# Batch summary: counts, status, timestamps
GET  https://api.emailcheck.org/emailcheck/email/reachability/bulk/{bulkId}

# Paginate jobs inside a batch
GET  https://api.emailcheck.org/emailcheck/email/reachability/bulk/{bulkId}/items?offset=0&limit=100

# Export results as CSV
#   columns: email, status, email_address_status, completed_time, error
GET  https://api.emailcheck.org/emailcheck/email/reachability/bulk/{bulkId}/export.csv

# Force-refresh any job that hasn't reached a final status yet
POST https://api.emailcheck.org/emailcheck/email/reachability/bulk/{bulkId}/reconcile

# List all batches belonging to the current account
GET  https://api.emailcheck.org/emailcheck/email/reachability/bulk/list?offset=0&limit=20
06

用量统计与历史

当前账号最近 30 天的日调用量，以及最近 20 条作业明细，用于控制台/仪表板展示。

# Both endpoints require: Authorization: Bearer YOUR_API_KEY

# Daily call counts for the last 30 days
GET https://api.emailcheck.org/emailcheck/email/reachability/stats/daily

# 20 most recent jobs
GET https://api.emailcheck.org/emailcheck/email/reachability/logs/recent
07

响应字段说明

欄位含義
jobId本地作业 ID（以 EVJ_ 开头），用于 /email/reachability/status/{jobId} 复查。
email本次校验的邮箱地址。
status作业生命周期状态：PENDING | IN-PROGRESS | COMPLETE | FAILED | TIMEOUT_PENDING。TIMEOUT_PENDING 仅在单次同步请求超时时出现，作业仍在后台运行，稍后用 status 接口再查。
emailAddressStatus邮箱投递判定：VALID（可投递）| INVALID（不可投递）| UNKNOWN（无法确定，如 SMTP 连接被拒）| CATCH_ALL（域名收所有地址，无法区分）。仅当 status 为终态时有效。
completedtrue 表示 status 已进入终态（COMPLETE 或 FAILED），无需继续轮询。
bulkId批次 ID（以 EVB_ 开头）。
requestedCount本次提交的邮箱总数（含被本地校验拒绝的）。
acceptedCount本地校验通过并已转给上游的邮箱数。
rejectedCount本地直接拒绝的邮箱数（格式不合法、批次内重复等）。
completedCount已进入终态 COMPLETE 的作业数。
timeoutCount长时间未出终态被标记为 FAILED（超时）的作业数；对应 Credit 会自动退回。
deductCredit本批次实际扣减的 Credit（= acceptedCount 在退费前的值）。
refundedCredit累计退还的 Credit（含拒绝部分和超时部分）。
source批次来源标签：csv | manual | api，默认 manual，仅用于记账与展示。
filename选传的批次文件名，仅用于展示。
createdTime批次创建时间戳（Unix 毫秒）。
completedTime批次进入终态的时间戳（Unix 毫秒），未终态时缺省。
errorCode本地拒绝原因码：invalid_email | duplicate_email 等。
errorMessage对应 errorCode 的可读说明。