// post /v1/bulk/verifier
批量邮箱验证器 API
借助一条专为大规模发件人打造的异步验证流程，清洗大批量邮箱列表并为其评分。
Email addresses最多 20,000 行
curl -X POST "https://api.tomba.io/v1/bulk/verifier" \
-H "X-Tomba-Key: $TOMBA_API_KEY" \
-H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Email Verifier job","list":"richard@piedpiper.com\njohn@example.com","launch":true,"webhook_url":"https://hooks.example.com/tomba"}'const res = await fetch("https://api.tomba.io/v1/bulk/verifier", {
method: "POST",
headers: {
"X-Tomba-Key": process.env.TOMBA_API_KEY,
"X-Tomba-Secret": process.env.TOMBA_SECRET_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({
"name": "Email Verifier job",
"list": "richard@piedpiper.com\njohn@example.com",
"launch": true,
"webhook_url": "https://hooks.example.com/tomba"
})
});
const { data } = await res.json(); // { id }import os, requests
res = requests.post(
"https://api.tomba.io/v1/bulk/verifier",
headers={
"X-Tomba-Key": os.environ["TOMBA_API_KEY"],
"X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"],
},
json={
"name": "Email Verifier job",
"list": "richard@piedpiper.com\njohn@example.com",
"launch": True,
"webhook_url": "https://hooks.example.com/tomba"
},
)
job_id = res.json()["data"]["id"]// 01 · 请求
批量Email Verifier只需一个 HTTPS 请求
使用您的密钥和密钥密码发送参数。每个 SDK、CLI 和 MCP 服务器都发出相同的调用。
- type
- verifier
- list | data | file
- Email addresses
- launch
- 设为 true 即立即启动任务
- webhook_url
- 任务结束时接收已签名的事件
- rows
- 每个任务最多 20,000 行
curl -X POST "https://api.tomba.io/v1/bulk/verifier" \
-H "X-Tomba-Key: $TOMBA_API_KEY" \
-H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Email Verifier job","list":"richard@piedpiper.com\njohn@example.com","launch":true,"webhook_url":"https://hooks.example.com/tomba"}'const res = await fetch("https://api.tomba.io/v1/bulk/verifier", {
method: "POST",
headers: {
"X-Tomba-Key": process.env.TOMBA_API_KEY,
"X-Tomba-Secret": process.env.TOMBA_SECRET_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({
"name": "Email Verifier job",
"list": "richard@piedpiper.com\njohn@example.com",
"launch": true,
"webhook_url": "https://hooks.example.com/tomba"
})
});
const { data } = await res.json(); // { id }import os, requests
res = requests.post(
"https://api.tomba.io/v1/bulk/verifier",
headers={
"X-Tomba-Key": os.environ["TOMBA_API_KEY"],
"X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"],
},
json={
"name": "Email Verifier job",
"list": "richard@piedpiper.com\njohn@example.com",
"launch": True,
"webhook_url": "https://hooks.example.com/tomba"
},
)
job_id = res.json()["data"]["id"]// 02 · 响应
返回的内容
JSON，在任何语言中都相同。Tomba 不知道的字段为 null，绝不猜测。
GET
/email-verifierdata.email.resultstring- deliverable, risky or undeliverable; empty for a disposable domain
data.email.statusstring- valid, accept_all, invalid, unknown or disposable (compare case-insensitively: a live check can return Valid)
data.email.scoreinteger- Confidence: 99 for valid, 77 or more for accept_all, 2 for disposable
data.email.smtp_providerstring | null- Mail provider from the MX records, such as Google
data.email.mx.recordsarray | null- The domain's MX hosts
data.email.mx_check, data.email.smtp_checkboolean- The domain has MX records (smtp_check is the same check; status says whether the mailbox exists)
data.email.accept_all, data.email.greylisted, data.email.blockboolean- Catch-all domain, check deferred, check refused by the server
data.email.disposable, data.email.webmail, data.email.gibberish, data.email.regexboolean- Disposable or webmail domain, random-looking address, valid syntax
data.sources[]array- Where the address was found
data.phone_data[]array | null- Phone numbers, when you send enrich_mobile
POST /bulk/verifier
201 Created
{
"data": {
"id": 1042
}
}每一行，与 GET /email-verifier 返回的内容相同
200 OK
{
"data": {
"email": {
"email": "richard@piedpiper.com",
"result": "deliverable",
"status": "valid",
"score": 99,
"smtp_provider": "Google",
"mx": {
"records": [
"aspmx.l.google.com",
"alt1.aspmx.l.google.com"
]
},
"mx_check": true,
"smtp_server": true,
"smtp_check": true,
"accept_all": false,
"greylisted": false,
"block": false,
"gibberish": false,
"disposable": false,
"webmail": false,
"regex": true,
"whois": {
"registrar_name": null,
"referral_url": null,
"created_date": null
}
},
"sources": [
{
"uri": "https://piedpiper.com/blog/engineering",
"website_url": "piedpiper.com",
"extracted_on": "2024-06-01T09:14:07+01:00",
"last_seen_on": "2025-01-10T17:02:44+01:00",
"still_on_page": true
}
],
"phone_data": null
}
}// 03 · 费用和限制
调用的费用
仅在满足以下条件时才对调用收费。速率限制取决于您的套餐。
// 费用
1 verification credit per row, except disposable addresses. Plus 5 search credits per row with phone data.
Charged once, at the first download; later downloads are free
- Jobs created: 15 per day for each type
- Running jobs: 2 per type
- Downloads: 25 per day for each job
- Request size: 4 MB (CSV, list or rows)
上传邮箱地址列表以创建批量操作，然后启动该操作。API 会通过多层检查异步验证所有邮箱。使用 webhook 或轮询来监控进度。
每次批量操作最多可验证 20,000 个邮箱地址。列表更大时，请创建多个批量操作。
每个邮箱都会经过语法校验、MX 记录检查、SMTP 验证、一次性邮箱检测、catch-all 检测和可送达性评分。
如果 Tomba 返回为 valid 的地址发生硬退信，积分将根据数据质量保证返还（验证结果为 deliverable 或查找得分不低于 60，并在 30 天内从配置了 SPF、DKIM 和 DMARC 的域名发送）。
速度取决于列表大小以及每个邮件服务器的响应速度。轮询任务或设置 webhook，即可在任务完成时收到通知。
每条结果包含邮箱、验证状态（valid、invalid、accept_all、unknown）、置信度得分、一次性邮箱标记、SMTP 服务商和 MX 记录。
处理完成后，使用下载端点以 CSV 或 JSON 格式获取结果。结果包含每个邮箱的全部验证数据。
支持。配置一个 webhook URL，即可在批量验证完成或处理过程中出错时收到通知。
accept-all 域名的邮箱可能有效，但风险更高。请优先处理置信度得分较高的记录，并考虑对这些记录采用分段发送策略。
在临近发送时验证列表，屏蔽无效和一次性地址，并定期重新验证旧列表，以保持可送达性。