即時 Email 驗證 API：開發者指南

即時電子郵件驗證會在使用者仍停留於表單時檢查地址。它會在「Submit」與下一個畫面之間的幾百毫秒內執行，並回答一個問題：這個地址是否應該進入您的資料庫？即時電子郵件驗證 API 會替您做出這項判斷。它會檢查語法、網域及其 MX 記錄、一次性電子郵件與角色型信箱訊號、萬用收件行為，以及在您要求時檢查信箱本身。接著，它會傳回結構化結果，讓您的程式碼能夠據此採取行動。

本指南適用於要將這道關卡加入註冊、結帳或潛在客戶表單的開發人員。內容涵蓋這些檢查的作用、如何呼叫 API、如何將每個狀態轉換為產品決策，以及郵件伺服器回應緩慢時如何維持速度。範例使用 BillionVerify 電子郵件驗證 API，但其中的設計建議適用於任何供應商。

什麼是即時電子郵件驗證？

即時電子郵件驗證是在輸入地址的當下執行的檢查，而不是等到幾天後行銷活動寄出時才進行。使用者輸入地址。您的前端或後端會將其傳送給電子郵件檢查 API。API 會回傳 valid、invalid 或 catchall 等狀態，以及背後的判斷訊號。接著，您的應用程式會允許註冊、封鎖註冊，或要求使用者修正拼字錯誤。

重點在於時機。像 gmial.com 這樣的拼字錯誤，在使用者仍停留於表單時修正不會造成任何損失。但歡迎電子郵件退信後，同樣的錯誤就會讓您失去客戶。錯誤地址也會損害您的寄件者信譽，因為每次硬退信都會告訴信箱服務提供者，您正在向未確認的地址寄送郵件。即時電子郵件驗證能在入口處就阻擋這些地址。

它也有助於防範詐欺：即時檢查可以在帳號建立前，標記一次性收件匣。

即時與批次 Email 驗證

兩種方式都使用相同的檢查。差異在於執行時機，以及可用的處理時間。

即時與批次比較即時單一地址檢查與清單驗證

即時驗證一次處理一個地址，在使用者提出請求時執行。它有嚴格的時間限制，通常遠低於 1 秒，因為載入緩慢的表單會導致使用者放棄註冊。它能防止錯誤資料進入系統。
批次驗證會在背景中處理整份清單。這可能需要幾分鐘或幾小時，而且沒有人需要盯著畫面等待。它能清理系統中既有的資料，例如在大型行銷活動前，或從 CRM 匯入資料後執行。

大多數團隊兩者都需要。即時檢查能保持新資料乾淨，而定期執行批次驗證則能找出隨時間失效的地址，例如已離職員工的地址。如需更深入的比較，請參閱即時與批次 Email 驗證。

即時檢查實際測試什麼

電子郵件驗證 API 會依序執行一系列檢查，從成本低到成本高。每項檢查都會排除一種不同類型的無效地址。

語法

第一項檢查是格式。是否剛好有一個 @？本機部分是否由允許的字元組成？網域看起來像網域嗎？語法會拒絕明顯的垃圾內容，例如 john@@example 或 jane.example.com。這項檢查速度快，也不需要網路呼叫。但語法完美並不能說明信箱是否存在。

網域與 MX 記錄

接著，API 會在 DNS 中查詢網域。沒有 MX 記錄的網域無法接收電子郵件，因此即使地址看起來多麼乾淨，也沒有用。這能抓出拼寫錯誤的網域與已失效的公司網域。BillionVerify 會將找到的 MX 主機回傳在 mx_records 中，而當網域看起來像常見網域的拼寫錯誤時，domain_suggestion 可以提供可能的修正結果。

一次性、角色與免費供應商訊號

有些地址確實存在，但仍不適合你的產品：

一次性 地址來自臨時收件匣服務，通常幾小時內就會停止運作。請參閱一次性電子郵件偵測方式。
角色地址，例如 info@ 或 support@，會寄到團隊而非個人。這些地址通常可以投遞，但互動率往往較低。
免費供應商 地址，例如 Gmail，對消費者而言很常見，但在 B2B 表單中值得記錄。

API 會將這些結果回報為旗標（is_disposable、is_role、is_free），讓你能依產品需求決定處理方式。

萬用網域

有些郵件伺服器會接受寄往其網域下任何地址的郵件，無論地址是否真實。對這些萬用網域而言，信箱檢查無法證明特定收件匣是否存在。萬用網域結果不代表結果不好，而是表示確定性較低，因此分數比標籤更重要。萬用電子郵件偵測說明了其運作方式與重要性。

SMTP 信箱檢查

最深入的檢查會透過 SMTP 詢問收件者的郵件伺服器，確認信箱是否會接受訊息，但不會實際寄出訊息。它能找出位於真實網域、但已不再存在的地址，例如前員工的信箱。這也是最慢的步驟，因為它取決於其他人的伺服器。在 BillionVerify 中，這項功能由 check_smtp 參數控制。如果省略此參數，API 會執行 SMTP 檢查；傳送 check_smtp: false 即可略過。

網域信譽

BillionVerify 也可以回傳 domain_reputation 物件，其中包含網域郵件伺服器 IP 的黑名單結果。此資訊僅供參考：不會改變狀態、分數或費用。

如何呼叫即時 Email 驗證 API

使用 BillionVerify，單次即時檢查只需發出一個 HTTPS 請求。基礎 URL 是 https://api.billionverify.com/v1，而您的 API 金鑰應放在 BV-API-KEY 標頭中。請將該金鑰保存在您的伺服器上。切勿將其放入瀏覽器程式碼中。

以下是根據 API 參考文件建立的最簡請求：

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

此請求包含三個參數：

參數	預設值	功能
`email`	必填	要驗證的地址
`check_smtp`	開啟	設定為 `false` 可略過即時 SMTP 信箱檢查
`force_refresh`	`false`	略過快取結果；重新取得的結果會按照新檢查計費

成功的回應會將結果包裝在標準信封中。以下是可投遞地址的簡化範例：

{
  "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,
    "domain": "example.com",
    "mx_records": ["mail.example.com"],
    "check_smtp": true,
    "reason": "smtp_deliverable",
    "domain_suggestion": "",
    "response_time": 250,
    "credits_used": 1
  }
}

如果您偏好使用 SDK，BillionVerify 為 Node.js、Python、TypeScript、Go、PHP 和 Java 提供官方套件。在 Node.js 中，npm install billionverify-sdk 會提供包含 verify 方法的用戶端；在 Python 中，套件名稱是 billionverify。

閱讀回應：狀態、分數與原因

status 欄位是大多數程式碼分支判斷的依據。以下是各個狀態的含義，以及註冊表單可採用的合理預設值：

狀態	含義	註冊表單預設值
`valid`	信箱存在且可以接收郵件	接受
`invalid`	地址不存在或無法接收郵件	阻擋並要求提供其他地址
`disposable`	臨時信箱	阻擋，或在有限制的情況下接受
`catchall`	網域接受所有地址	接受並監控
`role`	共用信箱，例如 `info@`	接受，也可以標記以供銷售使用
`unknown`	無法確認可傳遞性	接受，稍後重新檢查

score 會在 0 到 1 之間提供更精細的訊號。粗略來說，valid 結果的分數介於 0.85 到 1.0，catchall 約為 0.55 到 0.75，unknown 為 0.3 到 0.6，disposable 為 0，而 invalid 為 0。role 結果會保留底層檢查的分數。你可以使用分數為邊界案例設定自己的門檻，例如在高價值表單中，只接受分數高於特定值的 catch-all 地址。

reason 欄位會說明判定結果。invalid 結果可能伴隨 invalid_syntax、no_mx_records 或 mailbox_not_found，而每個原因都對應給使用者的不同訊息。語法問題表示「請檢查格式」。信箱不存在表示「此信箱不存在」。驗證原因頁面列出所有原因，並說明哪些 unknown 原因值得重試。

有兩個欄位可以直接協助使用者：domain_suggestion 可以用來提供「你是不是要輸入 gmail.com？」的提示，而 is_disposable 則會說明為何拒絕一次性地址。

圍繞延遲預算設計註冊流程

困難之處在於，如何將檢查加入表單，同時不讓流程變慢。先設定預算。例如，在送出時，決定最多願意讓使用者等待 300 到 500 毫秒。其他一切都由這個數字延伸而來。

BillionVerify 的產品文案指出，快取結果低於 200 毫秒，而完整的 SMTP 檢查平均需要 1–3 秒。這個差距讓你有兩種不錯的設計：

搭配逾時的完整檢查。 開啟 SMTP，並設定 2–3 秒的逾時時間來呼叫 API。大多數結果都能及時回傳，並清楚顯示 valid 或 invalid。如果發生逾時，則允許流程繼續，之後再重新檢查。
立即快速檢查，稍後進行深入檢查。 使用 check_smtp: false 呼叫 API。這只能確認明確的情況：語法錯誤、沒有 MX 記錄的網域、一次性與角色型地址。使用正常運作網域的地址會以 unknown 回傳，原因為 smtp_unverifiable，這是預期結果。先接受該地址，然後從背景工作使用開啟 SMTP 的設定進行第二次呼叫。如果信箱不存在，請標記該帳號，並要求使用者確認其地址。

幾個前端習慣也能提供幫助：

在失去焦點或送出時驗證，而不是每次按鍵都驗證。 檢查 j、jo、joh 會浪費呼叫次數與額度。
先執行本機語法檢查， 避免為明顯錯誤多發送一次請求。
從後端呼叫 API。 你的伺服器負責保存 API 金鑰並記錄結果；瀏覽器只顯示結果。

如需瞭解文字內容、錯誤位置及何時顯示提示等 UX 細節，請參閱註冊期間的電子郵件驗證。

失敗時關閉還是失敗時開放？處理逾時與未知狀況

大多數產品適用的模式是：明確錯誤時失敗時關閉，不確定時失敗時開放。

失敗時關閉表示阻擋註冊。當 API 表示該地址明確無效時採用此方式：invalid 搭配 invalid_syntax 或 no_mx_records，或是在拋棄式帳號會造成損害的表單上遇到 disposable 地址。
失敗時開放表示先讓使用者通過，之後再跟進處理。當結果不確定時採用此方式：unknown 狀態、萬用收件網域，或是在 API 回覆前自行觸發的逾時。

為什麼不也阻擋不確定的地址？許多真實使用者都在這些地址後方。企業郵件伺服器經常會對 SMTP 檢查採用灰名單或速率限制，因此阻擋它們會讓你失去真正的註冊。先接受、為該筆記錄加上標籤，之後再重新檢查。

在 API 呼叫上設定符合延遲預算的用戶端逾時。逾時觸發時，將結果視為 unknown：接受、儲存旗標，並將重新檢查工作排入背景佇列。稍後再重試 unknown 結果，不要在請求內重試。

範例：在 Node.js 註冊時驗證 Email

以下範例展示註冊處理常式中的快速檢查（設計 2）。它使用文件中記載的 REST endpoint 和回應欄位、逾時設定，以及上述的開放或封閉失敗規則。請依照您的框架調整名稱。

const BLOCK = new Set(['invalid', 'disposable']);

async function checkEmail(email) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 400);

  try {
    const response = await fetch('https://api.billionverify.com/v1/verify/single', {
      method: 'POST',
      headers: {
        'BV-API-KEY': process.env.BV_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email, check_smtp: false }),
      signal: controller.signal,
    });
    const body = await response.json();
    if (!body.success) return { allow: true, recheck: true };

    const { status, reason, domain_suggestion } = body.data;
    if (BLOCK.has(status)) {
      return { allow: false, reason, suggestion: domain_suggestion };
    }
    return { allow: true, recheck: status === 'unknown' || status === 'catchall' };
  } catch {
    // Timeout or network error: fail open and re-check in the background.
    return { allow: true, recheck: true };
  } finally {
    clearTimeout(timer);
  }
}

在沒有 SMTP 的情況下，大多數真實地址會回傳 unknown，並取得 recheck 標記。儲存帳號後，背景工作會針對每筆標記為 recheck 的記錄，開啟 SMTP 並呼叫相同的 endpoint。Node.js 教學會逐步介紹更完整的設定，包括官方 SDK。相同的請求也能從 Python 或任何具備 HTTP 用戶端的語言發出。

速率限制、快取與成本

即時檢查位於您的註冊流程中，因此它的限制也會成為您的限制。請提前規劃。

速率限制。 BillionVerify 透過每個帳號的限制來保護其容量。當您達到限制時，API 會回傳 HTTP 429，並附帶代碼 1003 與 Retry-After 標頭。請退避並重試，同時維持您自己的故障開放規則，確保限制永遠不會阻擋真正的使用者。

快取。 結果會被快取，這就是為什麼重複檢查能快速完成。重新檢查您的帳號在過去 24 小時內驗證過的地址不會產生費用。只有在確實需要最新結果時，才使用 force_refresh: true，因為這會略過快取，並按照新檢查計費。

成本。 單次檢查通常使用 1 點額度，顯示於 credits_used 中。每個 unknown 結果都是免費的，語法錯誤也不會收費。請在提交時驗證，而不是每次按鍵時都驗證；也不要重新檢查近期已驗證過的地址。BillionVerify 每天登入時提供 20 點免費額度，每月最多 600 點，足以建立並測試整合。付費額度套件列於定價頁面。

超越表單：批次、檔案與 Webhooks

即時驗證會逐一檢查新的地址。對於其他需求，同一個 API 還提供其他入口：

小型批次。 POST /verify/bulk 可在單一請求中檢查最多 50 個地址，適合 CRM 同步或匯入畫面。
大型清單。 POST /verify/file 接受 CSV、TXT 或 XLSX 檔案，並在背景中處理。
Webhooks。 不必輪詢檔案工作，註冊 webhook 以接收 file.completed 和 file.failed 事件。請參閱電子郵件驗證 Webhooks 指南，了解簽章檢查與重試機制。
僅檢查一次性地址。 POST /verify/disposable 僅回答是否為一次性地址，且不會使用額度。

常見的設定方式是：在每個表單上進行即時檢查，對標記為 recheck 的記錄執行每晚批次處理，並在大型行銷活動前執行檔案工作。

即時 Email 驗證檢查清單

上線前，請逐項檢查以下清單：

驗證檢查清單顯示伺服器端檢查、逾時處理與不確定結果

API 金鑰儲存在伺服器上，絕不放在瀏覽器中。
在呼叫 API 前，先於本機檢查語法。
請求路徑使用 check_smtp: false，並設定符合延遲預算的逾時時間。
invalid 和 disposable 都有清楚且具體的錯誤訊息。
unknown、catchall 和逾時採用開放式失敗處理，並排入佇列以便重新檢查。
domain_suggestion 用於提供拼字錯誤提示。
429 回應會進行退避處理，不會阻擋使用者。
結果會與使用者記錄一同儲存，之後即可衡量退信率。

常見問題

什麼是即時 Email 驗證 API？

即時 Email 驗證 API 會在使用者提交表單時檢查單一 Email 位址，並在不到一秒的時間內回傳判定結果。它會執行語法、網域、MX、一次性、角色型及 catch-all 檢查，並可選擇執行 SMTP 信箱檢查，讓您的應用程式能在該位址進入資料庫前接受、封鎖或標記它。

即時 Email 驗證與大量驗證有何不同？

即時 Email 驗證會在使用者請求中一次檢查一個位址，並且必須快速回應。大量驗證則會在背景中檢查完整清單，可能需要更長時間。使用即時檢查來維持新資料的乾淨，並使用大量檢查來清理您現有的資料。

我應該在每次註冊時都執行 SMTP 檢查嗎？

這取決於您的延遲預算。SMTP 檢查用來確認信箱，因此若沒有執行，大多數真實位址都會回傳 unknown。如果您可以等待 2–3 秒，請在提交時搭配逾時設定執行。如果不行，請使用 check_smtp: false 執行快速檢查，並在背景工作中執行 SMTP 檢查。

我該如何處理 catch-all 與 unknown 結果？

接受這些結果，稍後再重新檢查。catch-all 網域會接受所有位址，因此信箱檢查無法證明收件匣存在；而 unknown 結果表示檢查尚未完成。封鎖這些使用者會流失真實註冊；標記他們並重新檢查，能在不影響轉換率的情況下維持資料乾淨。

我可以從瀏覽器呼叫 Email 檢查 API 嗎？

不行。這會暴露您的 API 金鑰。請從後端呼叫 API，並只回傳判定結果。

即時 Email 驗證有多快？

使用 BillionVerify 時，快取結果會在 200 ms 內回傳，而完整 SMTP 檢查平均需要 1–3 秒。這就是為什麼不含 SMTP 的快速檢查應放在請求流程中，而 SMTP 檢查則應放在背景執行。

Email 驗證 API 的費用是多少？

在 BillionVerify 中，單次檢查通常會使用 1 點額度，而每個 unknown 結果都免費。您每天登入即可獲得 20 點免費額度，每月最多 600 點；付費額度方案則列於價格頁面。force_refresh 會略過快取，並按照新的檢查計費。

即時開始驗證電子郵件

即時電子郵件驗證意味著更少的退信、更少的虛假帳號，以及更少因拼寫錯誤而流失的使用者。在請求路徑中加入快速檢查，將耗時的檢查移至背景執行，並讓明確的失敗結果阻擋請求，同時讓不確定的結果通過。建立免費的 BillionVerify 帳號、取得 API 金鑰，並從上方文件中進行首次電子郵件驗證 API 呼叫。