快速开始
在控制台创建 API Key，将它安全保存在服务端，并通过 Bearer 凭证发送。每个被受理的邮箱验证请求消耗 1 个额度。
请求
curl -sS -X POST 'https://api.verifyemail.net/api/v1/verifications' \
-H 'Authorization: Bearer ve_live_your_api_key' \
-H 'Content-Type: application/json' \
-d '{"address":"[email protected]"}'响应 · HTTP 200
{
"errcode": 0,
"address": "[email protected]",
"is_deliverable": true,
"status": 250,
"catch_all": false,
"disposable": false
}身份认证
在控制台创建 API Key： 控制台 → API 密钥
完整的 ve_live_… 密钥只会显示一次。
请将 API Key 保存在服务端密钥管理中。不要放入浏览器代码、URL 查询参数、公开仓库或客户端可见日志。
Authorization: Bearer ve_live_your_api_key
验证邮箱
POST
/verifications请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| address | string | 是 | 完整的邮箱地址。 |
返回参数
| 字段 | 类型 | 说明 |
|---|---|---|
| errcode | number | 0 表示请求成功；其他值请根据错误码表处理。 |
| address | string | 规范化后的邮箱地址。 |
| is_deliverable | boolean | 收件服务器是否接受该收件人。 |
| status | number | null | SMTP 数字响应码；未收到 SMTP 响应时为 null。 |
| catch_all | boolean | null | 域名是否接收任意收件人；无法可靠判断时为 null。 |
| disposable | boolean | 地址是否属于临时邮箱域。 |
250 · HTTP 200 · errcode 0
收件服务器接受该收件人。
550 · HTTP 200 · errcode 0
域名或收件服务器拒绝该收件人。
null · HTTP 422
邮箱地址无效或无法进行验证。
null · HTTP 503
当前无法得出可靠结论，请稍后重试。
也可以使用下面的 GET 接口。推荐使用 POST，避免邮箱地址进入代理访问日志或浏览器历史： /verifications?address=…
查询剩余额度
GET
/usage此请求不会消耗验证额度。同一用户的控制台会话和全部 API Key 共享一份额度。
请求
curl -sS 'https://api.verifyemail.net/api/v1/usage' \
-H 'Authorization: Bearer ve_live_your_api_key'响应 · HTTP 200
{
"errcode": 0,
"verification_limit": 100,
"verification_used": 1,
"remaining_verifications": 99,
"unlimited": false
}| 字段 | 类型 | 说明 |
|---|---|---|
| verification_limit | number | 当前总额度；0 表示不限量。 |
| verification_used | number | 已经使用的验证次数。 |
| remaining_verifications | number | null | 剩余验证次数；不限量时为 null。 |
| unlimited | boolean | 当前额度是否不限量。 |
不限量套餐返回 remaining_verifications: null, unlimited: true.
错误码
程序逻辑应使用数字 errcode；用于展示的 message 文案可能调整。
错误响应
{
"errcode": 10006,
"message": "request rate limit exceeded"
}| errcode | HTTP | 含义 |
|---|---|---|
| 0 | 2xx | 请求成功。 |
| 10000 | 400 | 请求格式错误，请检查 JSON、请求头和 HTTP 方法。 |
| 10001 | 400 / 422 | 参数或业务规则校验失败。 |
| 10002 | 401 | 凭证缺失、无效或已过期。 |
| 10003 | 403 | 当前账户无权访问该资源。 |
| 10004 | 404 | 请求的资源不存在。 |
| 10005 | 409 | 资源与当前状态冲突。 |
| 10006 | 429 | 超过每秒请求限制。 |
| 10007 | 429 | 邮箱验证额度已耗尽。 |
| 10008 | 429 | 服务并发容量已耗尽。 |
| 10009 | 500 | 服务内部发生错误。 |
| 10010 | 503 | 服务暂时不可用或尚未配置。 |
| 10011 | 502 | 上游服务返回错误。 |
限流响应头
Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset — 用于描述当前请求时间窗口。