BillionVerify LogoBillionVerify

API Reference

Complete email checker API reference. Endpoints, parameters, response codes for email verification and validation.

BillionVerify API 是一个 RESTful 服务，提供强大的邮箱验证功能。所有 API 请求都应通过 HTTPS 进行。

基础 URL

https://api.billionverify.com/v1

OpenAPI 规范

完整的 API 规范以 OpenAPI 3.0 格式提供：

您可以将 OpenAPI 规范导入 Postman、Insomnia 等工具，或用于生成客户端库。

身份验证

所有 API 请求都需要使用 BV-API-KEY 头进行身份验证：

BV-API-KEY: YOUR_API_KEY

从 BillionVerify 仪表板获取您的 API 密钥。

示例

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

速率限制

套餐每小时请求数每天请求数
Free1001,000
Starter1,00010,000
Professional10,000100,000
Enterprise自定义自定义

速率限制信息包含在响应头中：

响应头描述
X-RateLimit-Limit允许的最大请求数
X-RateLimit-Remaining当前窗口剩余请求数
X-RateLimit-Reset限制重置的 Unix 时间戳

当达到速率限制时，您将收到 429 Too Many Requests 响应：

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 3600
  }
}

端点

单个邮箱验证

验证单个邮箱地址并返回详细结果。

POST /verify/single

请求

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

参数

参数类型必需默认值描述
emailstring是-要验证的邮箱地址
smtp_checkboolean否true执行 SMTP 邮箱验证
timeoutinteger否5000请求超时时间（毫秒）（最大：30000）

响应

{
  "email": "user@example.com",
  "status": "valid",
  "result": {
    "deliverable": true,
    "valid_format": true,
    "valid_domain": true,
    "valid_mx": true,
    "disposable": false,
    "role": false,
    "catchall": false,
    "free": false,
    "smtp_valid": true
  },
  "score": 0.95,
  "reason": null,
  "credits_used": 1
}

响应字段

字段类型描述
emailstring已验证的邮箱地址
statusstring验证状态：valid、invalid、unknown、catchall
resultobject详细的验证结果
scorenumber置信度分数（0.0 - 1.0）
reasonstring无效/未知状态的原因（可为空）
credits_usedinteger消耗的积分数

结果对象字段

字段类型描述
deliverableboolean邮箱是否可以接收消息
valid_formatboolean邮箱是否具有有效语法
valid_domainboolean域名是否存在
valid_mxboolean域名是否有 MX 记录
disposableboolean邮箱是否来自一次性服务
roleboolean邮箱是否为角色邮箱（info@、support@）
catchallboolean域名是否接受所有邮件
freeboolean邮箱是否来自免费提供商
smtp_validbooleanSMTP 验证是否通过

批量邮箱验证

同步验证多个邮箱地址。适合小批量验证（最多 50 个邮箱）。

POST /verify/bulk

请求

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

参数

参数类型必需默认值描述
emailsarray是-邮箱地址数组（最多：50）
check_smtpboolean否true执行 SMTP 验证

响应

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "results": [
      {
        "email": "user1@example.com",
        "status": "valid",
        "score": 0.95,
        "is_deliverable": true,
        "is_disposable": false,
        "is_catchall": false,
        "is_role": false,
        "is_free": false,
        "domain": "example.com",
        "smtp_check": true,
        "reason": null,
        "credits_used": 1
      }
    ],
    "total_emails": 3,
    "valid_emails": 2,
    "invalid_emails": 1,
    "credits_used": 3,
    "process_time": 2500
  }
}

检查积分

获取当前积分余额和使用信息。

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"
  }
}

文件上传验证

上传 CSV 或 Excel 文件进行异步邮箱验证。适用于大型列表。

POST /verify/file

请求

curl -X POST https://api.billionverify.com/v1/verify/file \
  -H "BV-API-KEY: sk_your_api_key" \
  -F "file=@emails.csv"

参数

参数类型必填描述
filefile是CSV 或 Excel 文件（最大：20MB，100,000 行）
email_columnstring否包含邮箱的列名（未指定时自动检测）

支持的文件格式

  • CSV (.csv)
  • Excel (.xlsx, .xls)
  • 文本 (.txt) - 每行一个邮箱

响应

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

获取文件任务状态

检查文件验证任务的状态。

GET /verify/file/{job_id}

响应（进行中）

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "job_id": "7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "status": "processing",
    "file_name": "emails.csv",
    "total_emails": 1000,
    "processed_emails": 450,
    "progress_percent": 45,
    "valid_emails": 380,
    "invalid_emails": 50,
    "unknown_emails": 20,
    "created_at": "2026-02-04T10:30:00Z"
  }
}

响应（已完成）

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "job_id": "7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "status": "completed",
    "file_name": "emails.csv",
    "total_emails": 1000,
    "processed_emails": 1000,
    "progress_percent": 100,
    "valid_emails": 850,
    "invalid_emails": 100,
    "unknown_emails": 30,
    "role_emails": 15,
    "catchall_emails": 5,
    "disposable_emails": 0,
    "credits_used": 970,
    "process_time_seconds": 125.5,
    "result_file_path": "results/2026/02/04/result_xxx.csv",
    "download_url": "/v1/verify/file/7143874e-21c5-43c1-96f3-2b52ea41ae6a/results",
    "created_at": "2026-02-04T10:30:00Z",
    "completed_at": "2026-02-04T10:32:05Z"
  }
}

下载验证结果

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

GET /verify/file/{job_id}/results

查询参数

参数类型默认值描述
validboolean-包含有效邮箱
invalidboolean-包含无效邮箱
catchallboolean-包含全接收邮箱
roleboolean-包含角色邮箱
unknownboolean-包含未知邮箱

不带过滤参数时返回完整结果文件。带过滤参数时返回仅包含匹配邮箱的 CSV。

示例：下载可投递邮箱

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

验证状态

状态分数含义推荐操作
valid0.9+邮箱存在且可以接收消息安全发送
invalid0.1邮箱不存在或无法接收从列表中移除
unknown0.5无法确定有效性稍后重试或谨慎使用
risky0.4存在风险因素谨慎使用，监控退信
disposable0.3一次性邮箱地址考虑移除
catchall0.7域名接受所有邮件（全接收）监控退信
role0.6角色邮箱（如 info@、support@）通常可投递，但参与度可能较低

错误响应

所有错误都遵循一致的格式：

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional context (optional)"
  }
}

HTTP 状态码

状态码描述
200成功
400错误请求 - 参数无效
401未授权 - API 密钥无效或缺失
403禁止 - 权限不足
404未找到 - 资源不存在
429请求过多 - 超过速率限制
500内部服务器错误
503服务不可用

错误码

错误码HTTP 状态描述
INVALID_API_KEY401API 密钥无效或缺失
RATE_LIMIT_EXCEEDED429请求过多
INSUFFICIENT_CREDITS403积分不足
INVALID_EMAIL400邮箱格式无效
INVALID_REQUEST400请求体格式错误
JOB_NOT_FOUND404未找到批量任务 ID
TIMEOUT504验证超时

Webhooks

当文件验证任务完成时接收实时通知。

创建 Webhook

POST /webhooks

请求

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

参数

参数类型必填描述
urlstring是接收 webhook 通知的 HTTPS URL
eventsarray是订阅的事件类型

响应

{
  "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 仅在创建 webhook 时返回。请妥善保存 - 您需要它来验证 webhook 签名。

列出 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,
        "created_at": "2026-02-04T10:30:00Z",
        "updated_at": "2026-02-04T10:30:00Z"
      }
    ],
    "total": 1
  }
}

删除 Webhook

DELETE /webhooks/{webhook_id}

响应

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

Webhook 事件

事件描述
file.completed文件验证任务成功完成
file.failed文件验证任务失败

Webhook 载荷

当事件发生时，我们会向您的 webhook URL 发送 POST 请求：

{
  "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,
    "result_file_path": "results/2026/02/04/result_xxx.csv",
    "download_url": ""
  }
}

Webhook 请求头

请求头描述
X-Webhook-Event事件类型（例如 file.completed）
X-Webhook-Signature用于验证的 HMAC-SHA256 签名
X-Webhook-Timestamp发送 webhook 时的 Unix 时间戳
User-AgentBillionVerify-Webhook/1.0

验证 Webhook 签名

要验证 webhook 来自 BillionVerify，请计算 HMAC-SHA256 签名：

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' +
    crypto.createHmac('sha256', secret)
      .update(payload)
      .digest('hex');

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

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

最佳实践

1. 使用环境变量

切勿硬编码 API 密钥：

// 正确
const apiKey = process.env.BV_API_KEY;

// 错误 - 不要这样做
const apiKey = 'bv_live_xxx';

2. 处理速率限制

实现指数退避：

async function verifyWithRetry(email, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await verify(email);
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED') {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

3. 多个邮箱使用批量端点

验证超过 10 个邮箱时，使用批量端点：

// 正确 - 单次 API 调用
const job = await client.verifyBulk(emails);

// 错误 - 多次单独调用
for (const email of emails) {
  await client.verify(email);
}

4. 为批量任务实现 Webhooks

不要持续轮询；使用 webhooks：

// 提交时附带 webhook
const job = await client.verifyBulk(emails, {
  webhookUrl: 'https://your-app.com/webhook',
});

SDK

使用我们的官方 SDK 简化集成：

Node.js

Python

Go

PHP

Java

TypeScript

下一步

快速入门指南

5 分钟内开始使用

验证类型

理解结果类型

集成指南

特定平台的教程

Quickstart

Get started with email checker API in 5 minutes. Free API key, code examples, and email verification integration guide.

SDKs

Email checker SDKs for Python, Node.js, TypeScript, Go, Java, PHP. Easy email verification integration.

On this page

基础 URLOpenAPI 规范身份验证示例速率限制端点单个邮箱验证请求参数响应响应字段结果对象字段批量邮箱验证请求参数响应检查积分响应文件上传验证请求参数支持的文件格式响应获取文件任务状态响应（进行中）响应（已完成）下载验证结果查询参数示例：下载可投递邮箱验证状态错误响应HTTP 状态码错误码Webhooks创建 Webhook请求参数响应列出 Webhooks响应删除 Webhook响应Webhook 事件Webhook 载荷Webhook 请求头验证 Webhook 签名最佳实践1. 使用环境变量2. 处理速率限制3. 多个邮箱使用批量端点4. 为批量任务实现 WebhooksSDK下一步