API Reference

BillionVerify API 完整参考文档，涵盖认证、邮箱验证、文件任务、结果下载、积分与 Webhooks。

BillionVerify API 是一个 RESTful 服务，提供实时邮箱验证、同步批量验证、异步文件处理、积分查询与 Webhook 通知。所有请求都必须通过 HTTPS 发送。

基础 URL

https://api.billionverify.com/v1

OpenAPI 规范

权威的机器可读契约在这里：

OpenAPI YAML: https://api.billionverify.com/openapi.yaml
交互式 API 文档: https://api.billionverify.com/docs

认证

请使用以下任一请求头传递 API Key，顺序与服务端优先级一致：

BILLIONVERIFY-API-KEY
BV-API-KEY
EV-API-KEY
EMAILVERIFY-API-KEY
Authorization: Bearer <api_key>

主推荐请求头：

BILLIONVERIFY-API-KEY: bv_live_...

可在 BillionVerify 仪表板获取 API Key。

示例

curl -X POST https://api.billionverify.com/v1/verify/single \
  -H "BILLIONVERIFY-API-KEY: bv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","check_smtp":false}'

速率限制

速率限制按 API Key 和端点类型分别计算。

端点	速率限制
单个验证 (`/verify/single`)	6,000 次/分钟
批量验证 (`/verify/bulk`)	1,500 次/分钟
文件上传 (`/verify/file`)	300 次/分钟
其他端点（`/credits`、`/webhooks` 等）	200 次/分钟

被限流时会返回 429 Too Many Requests：

{
  "success": false,
  "code": "4290",
  "message": "Rate limit exceeded",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  }
}

响应格式

成功响应：

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {}
}

错误响应：

{
  "success": false,
  "code": "4010",
  "message": "Unauthorized",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is invalid or missing"
  }
}

端点

单个邮箱验证

同步验证单个邮箱地址。

POST /verify/single

请求

{
  "email": "user@example.com",
  "check_smtp": false
}

参数

参数	类型	必填	默认值	描述
`email`	string	是	-	要验证的邮箱地址
`check_smtp`	boolean	否	`false`	是否执行实时 SMTP 邮箱验证

说明

check_smtp 省略时默认是 false。
当 check_smtp=false 时，请求不会执行实时 SMTP 网络检查。

响应

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "email": "user@example.com",
    "status": "valid",
    "score": 0.95,
    "is_deliverable": true,
    "is_disposable": false,
    "is_catchall": false,
    "is_role": false,
    "is_free": false,
    "has_gravatar": false,
    "gravatar_url": "",
    "domain": "example.com",
    "domain_age": 10,
    "mx_records": ["mail.example.com"],
    "domain_reputation": {
      "mx_ip": "192.0.2.1",
      "is_listed": false,
      "blacklists": [],
      "checked": true
    },
    "smtp_check": false,
    "reason": "accepted",
    "smtp_response": "",
    "error_message": "",
    "domain_suggestion": "",
    "response_time": 250,
    "credits_used": 1
  }
}

批量邮箱验证

同步验证多个邮箱地址，适合最多 100 个邮箱的小批量请求。

POST /verify/bulk

请求

{
  "emails": ["user1@example.com", "user2@example.com"],
  "check_smtp": false
}

参数

参数	类型	必填	默认值	描述
`emails`	array	是	-	邮箱地址数组，最大 `100` 个
`check_smtp`	boolean	否	`false`	是否执行实时 SMTP 邮箱验证

响应

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "results": [
      {
        "email": "user1@example.com",
        "status": "valid",
        "score": 0.95,
        "is_deliverable": true,
        "credits_used": 1
      },
      {
        "email": "user2@example.com",
        "status": "invalid",
        "score": 0,
        "is_deliverable": false,
        "credits_used": 0
      }
    ],
    "total_emails": 2,
    "valid_emails": 1,
    "invalid_emails": 1,
    "credits_used": 1,
    "process_time": 1500
  }
}

文件上传验证

上传 CSV、TXT、XLSX 或 XLS 文件，异步执行邮箱验证。

POST /verify/file

Multipart 字段

字段	类型	必填	默认值	描述
`file`	file	是	-	CSV、TXT、XLSX 或 XLS 文件
`check_smtp`	boolean	否	`false`	是否执行实时 SMTP 邮箱验证
`email_column`	string	否	自动检测	邮箱列名
`preserve_original`	boolean	否	`true`	是否保留原始列

限制

最大文件大小：20MB
单文件最多邮箱数：100,000

响应

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "task_id": "7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "file_name": "emails.csv",
    "file_size": 45678,
    "status": "pending",
    "message": "File uploaded successfully, parsing and processing email verification",
    "status_url": "https://api.billionverify.com/v1/verify/file/7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "created_at": "2026-02-04T10:30:00Z",
    "estimated_count": 1000,
    "unique_emails": 950,
    "total_rows": 1000,
    "email_column": "email"
  }
}

获取文件任务状态

获取文件任务的最新状态。

GET /verify/file/{job_id}

查询参数

参数	类型	必填	默认值	描述
`timeout`	integer	否	`0`	长轮询超时秒数，范围 `0-300`

下载链接语义

download_url 是稳定的 API 下载入口。
direct_download_url 是用于立即下载的签名存储地址。
direct_download_expires_at 表示该签名下载地址的过期时间。
result_file_url 与 result_file_path 不是公开 API 契约的一部分。

响应

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "task_id": "7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "status": "completed",
    "progress": 100,
    "email_progress": 100,
    "chunk_progress": 100,
    "progress_source": "email",
    "total_emails": 1000,
    "processed_emails": 1000,
    "valid_emails": 850,
    "invalid_emails": 100,
    "unknown_emails": 30,
    "role_emails": 15,
    "catchall_emails": 5,
    "risky_emails": 0,
    "disposable_emails": 0,
    "credits_used": 970,
    "download_url": "https://api.billionverify.com/v1/verify/file/7143874e-21c5-43c1-96f3-2b52ea41ae6a/results",
    "direct_download_url": "https://download.example.com/results_7143874e.csv?signature=...",
    "direct_download_expires_at": "2026-02-04T11:32:05Z",
    "started_at": "2026-02-04T10:30:00Z",
    "completed_at": "2026-02-04T10:32:05Z",
    "total_chunks": 10,
    "completed_chunks": 10,
    "failed_chunks": 0,
    "unique_emails": 950,
    "total_rows": 1000
  }
}

状态值

状态	描述
`pending`	任务排队中
`processing`	正在处理
`uploading`	正在汇总或收尾
`completed`	成功完成
`completed_with_warning`	已完成，但带有警告
`failed`	任务失败

下载文件结果

下载已完成文件任务的验证结果。

GET /verify/file/{job_id}/results

行为说明

不带过滤参数时，接口返回 307 Temporary Redirect 到完整结果文件。
带过滤参数时，接口直接返回动态生成的 CSV。
多个过滤参数之间是 OR 语义。

查询参数

参数	类型	描述
`valid`	boolean	包含有效邮箱
`invalid`	boolean	包含无效邮箱
`risky`	boolean	包含 risky 邮箱
`unknown`	boolean	包含未知邮箱
`catchall`	boolean	包含 catch-all 邮箱
`role`	boolean	包含角色邮箱
`disposable`	boolean	包含一次性邮箱

示例

curl -L -o filtered-results.csv \
  "https://api.billionverify.com/v1/verify/file/{job_id}/results?valid=true&catchall=true&role=true" \
  -H "BILLIONVERIFY-API-KEY: bv_live_xxx"

积分

查询当前认证账户的积分余额。

GET /credits

响应

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "account_id": "abc123",
    "api_key_id": "key_xyz",
    "api_key_name": "Default API Key",
    "credits_balance": 9500,
    "credits_consumed": 500,
    "credits_added": 10000,
    "last_updated": "2026-02-04T10:30:00Z"
  }
}

Webhooks

可用 Webhook 接收异步文件任务通知。

端点

POST /webhooks
GET /webhooks
DELETE /webhooks/{webhook_id}

支持的事件

file.completed
file.failed

verification.completed 不属于公开 Webhook 契约。

创建 Webhook

POST /webhooks

请求

{
  "url": "https://your-app.com/webhooks/billionverify",
  "events": ["file.completed", "file.failed"]
}

规则

url 必须使用 HTTPS
events 只能包含支持的事件名

响应

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "id": "673f3bff-81ea-4730-9cef-af1eb7f134bf",
    "url": "https://your-app.com/webhooks/billionverify",
    "events": ["file.completed", "file.failed"],
    "secret": "5c609e6893ab3b65ce8940549a030bc165762fe171e0b38f880bd570099619bf",
    "is_active": true,
    "created_at": "2026-02-04T10:30:00Z",
    "updated_at": "2026-02-04T10:30:00Z"
  }
}

secret 只会在创建时返回一次。请安全保存，后续验签要用到它。

列出 Webhooks

GET /webhooks

响应

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "webhooks": [
      {
        "id": "673f3bff-81ea-4730-9cef-af1eb7f134bf",
        "url": "https://your-app.com/webhooks/billionverify",
        "events": ["file.completed", "file.failed"],
        "is_active": true,
        "last_delivery_status": "success",
        "last_delivery_at": "2026-04-01T12:00:00Z",
        "last_error": null,
        "created_at": "2026-02-04T10:30:00Z",
        "updated_at": "2026-02-04T10:30:00Z"
      }
    ],
    "total": 1
  }
}

last_delivery_status 表示最近一次投递终态，取值为 success 或 failed。
last_delivery_at 表示最近一次投递终态发生的时间。
last_error 包含最近一次终态失败的错误信息；如果最近一次投递成功，则为 null。
对于从未发生过投递的 Webhook，这三个字段都为 null。

删除 Webhook

DELETE /webhooks/{webhook_id}

响应

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "message": "Webhook deleted successfully",
    "webhook_id": "673f3bff-81ea-4730-9cef-af1eb7f134bf"
  }
}

Webhook 请求头

请求头	描述
`Content-Type`	`application/json`
`X-Webhook-Event`	事件类型
`X-Webhook-Timestamp`	用于验签的时间戳
`X-Webhook-Signature`	`sha256=<hex_digest>`

Webhook 载荷

{
  "event": "file.completed",
  "timestamp": "2026-02-04T10:35:00Z",
  "data": {
    "job_id": "7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "file_name": "emails.csv",
    "total_emails": 1000,
    "valid_emails": 850,
    "invalid_emails": 100,
    "role_emails": 30,
    "catchall_emails": 10,
    "unknown_emails": 10,
    "disposable_emails": 0,
    "credits_used": 990,
    "process_time_seconds": 125.5,
    "download_url": "https://api.billionverify.com/v1/verify/file/7143874e-21c5-43c1-96f3-2b52ea41ae6a/results",
    "direct_download_url": "https://download.example.com/results_7143874e.csv?signature=...",
    "direct_download_expires_at": "2026-02-04T11:35:00Z"
  }
}

验证 Webhook 签名

Webhook 签名使用 HMAC-SHA256，对下面这个精确字符串进行计算：

{timestamp}.{raw_body}

签名请求头格式：

X-Webhook-Signature: sha256=<hex_digest>

推荐验签流程：

原样读取原始请求体。
读取 X-Webhook-Timestamp。
组装 {timestamp}.{raw_body}。
使用 webhook secret 计算 HMAC-SHA256。
与 X-Webhook-Signature 比较。
拒绝过旧时间戳，降低重放攻击风险。

const crypto = require('crypto');

function verifyWebhookSignature(rawBody, timestamp, signature, secret) {
  const signedPayload = `${timestamp}.${rawBody}`;
  const expectedSignature =
    'sha256=' +
    crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature),
  );
}

import hashlib
import hmac

def verify_webhook_signature(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    signed_payload = timestamp.encode() + b"." + raw_body
    expected = "sha256=" + hmac.new(
        secret.encode(),
        signed_payload,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

验证状态

状态	含义	建议操作
`valid`	邮箱存在且可接收邮件	可安全发送
`invalid`	邮箱不存在或无法接收	从名单中移除
`unknown`	暂时无法确认投递性	稍后重试或谨慎使用
`risky`	存在潜在投递风险	谨慎使用并监控退信
`disposable`	临时或一次性邮箱	通常建议移除
`catchall`	域名接受所有地址	关注实际退信情况
`role`	角色邮箱，如 `info@`、`support@`	通常可投递，但互动可能较低

错误码

代码	HTTP 状态	描述
`0`	200	成功
`4000`	400	错误请求
`4010`	401	API Key 缺失或无效
`4020`	402	积分不足
`4040`	404	资源不存在
`4130`	413	文件过大
`4290`	429	触发限流
`1000`	500	服务器内部错误

最佳实践

1. 不要把 API Key 写进源码

const apiKey = process.env.BV_API_KEY;

2. 正确选择批量与文件端点

使用场景	端点	限制
单个实时验证	`/verify/single`	1 个邮箱
小批量同步验证	`/verify/bulk`	100 个邮箱
大批量异步处理	`/verify/file`	100,000 个邮箱/文件

3. 文件任务优先使用 Webhook

轮询可用，但对长时间运行的文件验证任务，Webhook 更稳妥。

API Reference

Node.js

Python

Go

PHP

快速开始

验证类型

集成指南

On this page