開發人員

直接就能用的電子郵件驗證 API

即時驗證單一地址，或以批次傳送整份名單。所有請求都使用 HTTPS 並傳回 JSON。請在儀表板的「API 金鑰」中建立 API 金鑰。

REST 與 JSON
批次回呼
與儀表板共用點數

verify.sh

# Verify one addresscurl "https://bouncebell.com/api/v1/verify?email=rini.elizabeth@acme-foods.com" \  -H "Authorization: Bearer YOUR_API_KEY" { "status": "valid",  "reason": "mailbox_exists",  "did_you_mean": null }

身分驗證

每次請求時，請在 Authorization 標頭中以 Bearer 權杖的形式傳送您的 API 金鑰。請將金鑰保存在您的伺服器上，切勿放在瀏覽器程式碼或行動應用程式中。

Authorization: Bearer YOUR_API_KEY

所有端點的基本 URL 為 https://bouncebell.com/api/v1。

驗證單一地址

GET https://bouncebell.com/api/v1/verify

參數	必填	說明
`email`	是	要驗證的地址，請進行 URL 編碼。
`timeout`	否	等待郵件伺服器的秒數，範圍 3 到 30，預設為 10。逾時後狀態為 `unknown`，且不扣點數。

範例

curl "https://bouncebell.com/api/v1/verify?email=rini.elizabeth%40acme-foods.example" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "email": "rini.elizabeth@acme-foods.example",
  "status": "valid",
  "reason": "mailbox_exists",
  "domain": "acme-foods.example",
  "mx_record": "mx1.acme-foods.example",
  "disposable": false,
  "role": false,
  "free_provider": false,
  "catch_all": false,
  "did_you_mean": null,
  "checked_at": "2026-10-30T09:30:12Z",
  "credits_used": 1
}

結果欄位

欄位	類型	說明
`email`	string	您傳送的原始地址。
`status`	string	驗證結論。請參閱狀態。
`reason`	string	得出此結論的原因，例如 `mailbox_not_found` 或 `no_mail_server`。
`domain`	string	網域部分，以小寫表示。
`mx_record`	string or null	優先順序最高的郵件伺服器。
`disposable`	boolean	若網域為臨時信箱服務則為 true。
`role`	boolean	若為 info@ 或 support@ 等共用信箱則為 true。
`free_provider`	boolean	若為 Gmail 等免費信箱服務商則為 true。
`catch_all`	boolean	網域接收所有地址時為 true。
`did_you_mean`	string or null	網域疑似拼字錯誤時，提供修正後的地址。
`checked_at`	string	驗證執行的時間，採用 ISO 8601 UTC 格式。
`credits_used`	integer	1；狀態為 `unknown` 時為 0。

狀態

狀態	意義	建議動作
`valid`	信箱存在且可接收郵件。	送出
`invalid`	地址、網域或信箱不存在。	移除
`disposable`	臨時信箱服務。	移除
`catch_all`	此網域接收所有地址，因此無法確認信箱是否存在。	複查
`role`	存在的共用信箱。	複查
`unknown`	郵件伺服器未及時回覆。不扣點數。	稍後再試

批次處理

一次請求最多可傳送 100,000 個地址。批次會在背景執行；您可以輪詢其狀態，或提供 callback_url，批次完成後我們會呼叫該網址。

建立批次

POST https://bouncebell.com/api/v1/batches

curl -X POST "https://bouncebell.com/api/v1/batches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "October import", "emails": ["a@example.com", "b@example.com"],
       "callback_url": "https://yourapp.example/hooks/bouncebell"}'

{ "id": "bat_8f2k1q3m9x7w4p", "status": "queued", "total": 2, "done": 0 }

建立批次時，會為每個不重複的地址預扣點數；批次完成後，未知結果的點數會退還。回呼會收到一個包含 {"event": "batch.completed", "batch_id": "...", "status": "done", "counts": {...}} 的 POST 請求。回呼 URL 必須使用 HTTPS。

查看進度

GET https://bouncebell.com/api/v1/batches/{id}

{ "id": "bat_8f2k1q3m9x7w4p", "status": "running", "total": 2, "done": 1 }

狀態為 queued、running 或 done。狀態為 done 時，回應中還會包含依狀態統計的 counts。

下載結果

GET https://bouncebell.com/api/v1/batches/{id}/results

預設傳回 JSON。加上 ?format=csv 即可取得 CSV 檔案。每一列的欄位與單筆驗證相同。

點數

GET https://bouncebell.com/api/v1/credits

{ "credits_remaining": 33420 }

錯誤與限制

發生錯誤時會傳回 JSON 內容，其中包含 error 錯誤代碼與易讀的 message 說明。

HTTP 狀態碼	錯誤	處理方式
400	`bad_request`	參數缺少或有誤，請參閱錯誤訊息。
401	`invalid_key`	請確認金鑰正確且未被撤銷。
402	`no_credits`	請購買更多點數。
403	`email_not_confirmed`	請開啟註冊時我們以電子郵件寄給您的確認連結。
404	`not_found`	此批次不存在，或已在 30 天後刪除。
429	`rate_limited`	請放慢速度，並等待 `Retry-After` 標頭中的秒數。
500	`server_error`	請稍候再試。如果問題持續，請聯絡客服。

單筆驗證的速率上限為每個金鑰每秒 20 次請求。如需更高額度，請與我們聯絡。