邮箱验证接口 — Verify Email Address API 文档

使用一个 POST 请求验证邮箱地址。认证、参数、响应、额度和错误码均在本页说明。

POST/api/v1/email-verification

身份认证

每次请求只使用下面这一种认证方式。

Authorization: Bearer YOUR_API_KEY

保护 API 密钥

请只在服务器端保存和使用 API 密钥。怀疑密钥泄露时，请立即在账号后台删除并重新创建。

请求正文

字段类型说明

email必填

string

需要验证的邮箱地址，最长 254 个字符。

调用示例

curl --request POST \  --url https://verifyemailaddress.net/api/v1/email-verification \  --header 'Authorization: Bearer YOUR_API_KEY' \  --header 'Content-Type: application/json' \  --data '{"email":"name@example.com"}'

响应示例

验证完成后返回 HTTP 200。下面列出几种常见结果；实际响应只包含本次能够获得的验证信号。

可投递

{  "email": "name@example.com",  "status": "safe",  "overall_score": 98,  "username": "name",  "domain": "example.com",  "is_safe_to_send": true,  "is_valid_syntax": true,  "is_disposable": false,  "is_role_account": false,  "can_connect_smtp": true,  "has_inbox_full": false,  "is_catch_all": false,  "is_deliverable": true,  "is_disabled": false,  "is_spamtrap": false,  "is_free_email": false,  "mx_accepts_mail": true,  "mx_records": ["mx.example.com"],  "verification_mode": "power"}

不可投递

{  "email": "missing@example.com",  "status": "invalid",  "overall_score": 0,  "username": "missing",  "domain": "example.com",  "is_safe_to_send": false,  "is_valid_syntax": true,  "is_disposable": false,  "is_role_account": false,  "can_connect_smtp": true,  "has_inbox_full": false,  "is_catch_all": false,  "is_deliverable": false,  "is_disabled": false,  "is_spamtrap": false,  "is_free_email": false,  "mx_accepts_mail": true,  "mx_records": ["mx.example.com"],  "verification_mode": "power"}

全收域名

{  "email": "name@example.com",  "status": "catch_all",  "overall_score": 75,  "username": "name",  "domain": "example.com",  "is_safe_to_send": false,  "is_valid_syntax": true,  "is_disposable": false,  "is_role_account": false,  "can_connect_smtp": true,  "has_inbox_full": false,  "is_catch_all": true,  "is_deliverable": true,  "is_disabled": false,  "is_spamtrap": false,  "is_free_email": false,  "mx_accepts_mail": true,  "mx_records": ["mx.example.com"],  "verification_mode": "power"}

无法确认

{  "email": "name@example.com",  "status": "unknown",  "username": "name",  "domain": "example.com",  "is_valid_syntax": true,  "is_disposable": false,  "is_role_account": false,  "is_free_email": false,  "mx_accepts_mail": true,  "mx_records": ["mx.example.com"],  "verification_mode": "power"}

响应头

字段类型说明

X-Request-Id

string

本次调用的唯一请求 ID，排查问题时请提供该值。

X-Credits-Used

0 | 1

本次请求实际扣除的额度。

响应字段

不同邮件系统开放的信息不同，以下字段会根据实际检测结果返回。

字段类型说明

email

string

本次验证的邮箱地址。

status

string

邮箱验证状态，可能为 safe、invalid、disabled、disposable、inbox_full、catch_all、role_account、spamtrap 或 unknown。

overall_score

number

当前结果提供的验证评分。

username

string

邮箱地址中 @ 前面的部分。

domain

string

邮箱地址使用的域名。

is_safe_to_send

boolean

现有投递信号是否支持发送邮件。

is_valid_syntax

boolean

邮箱地址是否符合格式规则。

mx_accepts_mail

boolean

域名是否配置了可以接收邮件的服务器。

can_connect_smtp

boolean

是否成功连接到 SMTP 服务器。

has_inbox_full

boolean

收件箱是否已满。

is_deliverable

boolean

具体邮箱是否被报告为可投递。

is_disposable

boolean

是否属于临时邮箱服务。

is_role_account

boolean

是否属于 support@ 等角色邮箱。

is_catch_all

boolean

邮件服务器是否会接收可能不存在的地址。

is_disabled

boolean

邮箱是否已被禁用。

is_spamtrap

boolean

邮箱是否被识别为垃圾邮件陷阱。

is_free_email

boolean

是否属于常见的免费邮箱服务。

mx_records

string[]

该域名当前返回的邮件服务器记录。

verification_mode

"power"

本次请求使用的验证模式。

额度扣除

每次调用会先预留 1 次额度。只有完成验证并得到明确结果时才会实际扣除；没有获得结果时会自动退还。

字段类型说明

验证完成

扣除 1 次

验证完成，并返回可以使用的明确结果。

无法确认

不扣除

邮件服务器没有提供足够信息，无法形成明确结论。

请求失败

不扣除

请求被拒绝、验证服务不可用、执行失败或超时。

错误响应

错误响应使用相同的 JSON 格式，所有可能状态都在下表中直接展示。

{  "status": "error",  "reason": "invalid_api_key"}

HTTP	reason	说明
`400`	`invalid_email`	请求中没有有效的邮箱地址。
`401`	`invalid_api_key`	API 密钥缺失、无效或已被删除。
`403`	`subscription_required`	当前账号没有有效的付费套餐。
`405`	`method_not_allowed`	该接口必须使用 POST 请求。
`429`	`insufficient_credits`	当前账号没有足够的可用额度。
`500`	`verification_failed`	验证执行过程中发生未预期的错误。
`502`	`verification_unavailable`	本次未能获得邮箱验证结果。
`503`	`service_unavailable`	邮箱验证服务暂时不可用。
`504`	`verification_timeout`	验证未能在超时时间内完成。