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

響應

{
  "available": 9500,
  "used": 500,
  "total": 10000,
  "plan": "Professional",
  "resets_at": "2025-02-01T00:00:00Z",
  "rate_limit": {
    "requests_per_hour": 10000,
    "remaining": 9850
  }
}

檔案上傳驗證

上傳 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. 為批量任務實作 Webhook

不要持續輪詢；使用 Webhook：

// 使用 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. 為批量任務實作 WebhookSDK下一步