BillionVerify LogoBillionVerify

API Reference

BillionVerify API 完整參考文件，涵蓋認證、電郵驗證、檔案任務、結果下載、積分與 Webhooks。

BillionVerify API 是一個 RESTful 服務，提供即時電郵驗證、同步批量驗證、非同步檔案處理、積分查詢與 Webhook 通知。所有請求都必須透過 HTTPS 傳送。

基礎 URL

https://api.billionverify.com/v1

OpenAPI 規範

權威的機器可讀契約在這裡：

認證

請使用以下任一請求標頭傳遞 API Key，順序與伺服器端優先順序一致：

  1. BILLIONVERIFY-API-KEY
  2. BV-API-KEY
  3. EV-API-KEY
  4. EMAILVERIFY-API-KEY
  5. 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
}

參數

參數類型必填預設值描述
emailstring是-要驗證的電郵地址
check_smtpboolean否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
}

參數

參數類型必填預設值描述
emailsarray是-電郵地址陣列，最大 100 個
check_smtpboolean否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 欄位

欄位類型必填預設值描述
filefile是-CSV、TXT、XLSX 或 XLS 檔案
check_smtpboolean否false是否執行即時 SMTP 信箱驗證
email_columnstring否自動偵測電郵欄位名稱
preserve_originalboolean否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}

查詢參數

參數類型必填預設值描述
timeoutinteger否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 語義。

查詢參數

參數類型描述
validboolean包含有效電郵
invalidboolean包含無效電郵
riskyboolean包含 risky 電郵
unknownboolean包含未知電郵
catchallboolean包含 catch-all 電郵
roleboolean包含角色電郵
disposableboolean包含一次性電郵

範例

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-Typeapplication/json
X-Webhook-Event事件類型
X-Webhook-Timestamp用於驗簽的時間戳
X-Webhook-Signaturesha256=<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>

建議驗簽流程：

  1. 原樣讀取原始請求主體。
  2. 讀取 X-Webhook-Timestamp。
  3. 組裝 {timestamp}.{raw_body}。
  4. 使用 webhook secret 計算 HMAC-SHA256。
  5. 與 X-Webhook-Signature 比較。
  6. 拒絕過舊時間戳，降低重放攻擊風險。
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 狀態描述
0200成功
4000400錯誤請求
4010401API Key 缺失或無效
4020402積分不足
4040404資源不存在
4130413檔案過大
4290429觸發限流
1000500伺服器內部錯誤

最佳實踐

1. 不要把 API Key 寫進原始碼

const apiKey = process.env.BV_API_KEY;

2. 正確選擇批量與檔案端點

使用場景端點限制
單筆即時驗證/verify/single1 個電郵
小批量同步驗證/verify/bulk100 個電郵
大批量非同步處理/verify/file100,000 個電郵/檔案

3. 檔案任務優先使用 Webhook

輪詢可用，但對長時間執行的檔案驗證任務，Webhook 更穩妥。

SDK

Node.js

Python

Go

PHP

下一步

快速開始

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 規範認證範例速率限制回應格式端點單個電郵驗證請求參數說明回應批量電郵驗證請求參數回應檔案上傳驗證Multipart 欄位限制回應取得檔案任務狀態查詢參數下載連結語義回應狀態值下載檔案結果行為說明查詢參數範例積分回應Webhooks端點支援的事件建立 Webhook請求規則回應列出 Webhooks回應刪除 Webhook回應Webhook 請求標頭Webhook 載荷驗證 Webhook 簽章驗證狀態錯誤碼最佳實踐1. 不要把 API Key 寫進原始碼2. 正確選擇批量與檔案端點3. 檔案任務優先使用 WebhookSDK下一步