Verify Email Address
API 文档

批量邮箱验证接口

一次提交最多 100 个邮箱，通过任务 ID 查询批量验证进度和全部结果。

批量验证采用异步任务。先提交邮箱数组并获取 task_id，再使用 task_id 查询处理进度；任务完成后，同一个查询接口会返回全部邮箱结果。

身份认证

Authorization: Bearer YOUR_API_KEY

第一步：创建批量任务

POST/api/v1/bulk-email-verification

请求正文

emails必填
string[]

需要验证的邮箱数组，每次最少 1 个、最多 100 个。重复地址会自动合并且不会重复扣除额度。

name
string

可选的任务名称，最长 25 个字符。

调用示例

curl --request POST \  --url https://verifyemailaddress.net/api/v1/bulk-email-verification \  --header 'Authorization: Bearer YOUR_API_KEY' \  --header 'Content-Type: application/json' \  --data '{    "name": "July contacts",    "emails": [      "one@example.com",      "two@example.com",      "three@example.com"    ]  }'

创建成功

任务创建成功返回 HTTP 201。保存 task_id，后续使用它查询进度和结果。

{  "status": "success",  "task_id": "0195fbb8-6632-7ac0-b497-a3f4a2c349ec",  "count_submitted": 3,  "count_duplicates_removed": 0,  "count_rejected_emails": 0,  "count_processing": 3}

第二步：查询进度与结果

GET/api/v1/bulk-email-verification/{taskId}

任务处于 waiting 或 running 时，可间隔数秒再次查询。任务完成后，status 会变为 completed，并在 results 中返回每个邮箱的完整验证结果。

curl --request GET \  --url https://verifyemailaddress.net/api/v1/bulk-email-verification/0195fbb8-6632-7ac0-b497-a3f4a2c349ec \  --header 'Authorization: Bearer YOUR_API_KEY'

处理中

{  "task_id": "0195fbb8-6632-7ac0-b497-a3f4a2c349ec",  "name": "API: July contacts",  "status": "running",  "count_total": 3,  "count_checked": 2,  "progress_percentage": 66.67}

处理完成

{  "task_id": "0195fbb8-6632-7ac0-b497-a3f4a2c349ec",  "name": "API: July contacts",  "status": "completed",  "count_total": 3,  "count_checked": 3,  "progress_percentage": 100,  "results": {    "one@example.com": {      "email": "one@example.com",      "status": "safe",      "overall_score": 98,      "is_safe_to_send": true,      "is_deliverable": true,      "is_valid_syntax": true,      "mx_accepts_mail": true,      "verification_mode": "power"    },    "two@example.com": {      "email": "two@example.com",      "status": "invalid",      "overall_score": 0,      "is_safe_to_send": false,      "is_deliverable": false,      "is_valid_syntax": true,      "mx_accepts_mail": true,      "verification_mode": "power"    },    "three@example.com": {      "email": "three@example.com",      "status": "catch_all",      "overall_score": 75,      "is_safe_to_send": false,      "is_deliverable": true,      "is_valid_syntax": true,      "mx_accepts_mail": true,      "is_catch_all": true,      "verification_mode": "power"    }  }}

额度扣除

创建任务时按提交数量预留额度。重复地址、格式被拒绝的地址、未进入处理的地址以及最终没有获得明确结果的地址，会自动退还对应额度。查询任务进度不会重复扣除额度。

响应头

X-Request-Id
string

当前批量任务对应的请求 ID。

X-Credits-Used
number

当前批量任务实际扣除的额度。任务完成并结算后，该值会反映退还结果。

错误响应

{  "status": "error",  "reason": "invalid_batch"}
400 · invalid_batch
POST

emails 缺失、为空、超过 100 个，或包含不符合请求格式的数据。

401 · invalid_api_key
POST / GET

API 密钥缺失、无效或已删除。

403 · subscription_required
POST

当前账号没有有效的付费套餐。

404 · task_not_found
GET

任务不存在、已超过保留时间，或不属于当前 API 密钥对应的账号。

429 · insufficient_credits
POST

账号可用额度不足以创建本次批量任务。

502 / 503 / 504
POST / GET

验证暂时不可用、服务不可用或请求超时。