开发者

开箱即用的邮箱验证 API

实时验证单个地址，或以批量任务发送整份列表。所有请求均使用 HTTPS 并返回 JSON。请在控制台的“API 密钥”中创建 API 密钥。

REST 和 JSON
批量回调
与控制台共用积分

BounceBell 中的 API 密钥页面，显示启用中的密钥和创建新密钥的表单

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 次请求。如需更高额度，请联系我们。