批量清洗一份邮箱名单

你将构建： 一条「提交并取回」的流水线：把一份地址名单作为单个批量任务核验，然后取回带评级的结果 —— 不需要你自己维护轮询循环。

分类	服务端工作流
使用的操作	`POST /v1/data/workflows/clean-list:estimatePOST /v1/bulk/jobsGET /v1/bulk/jobs/{job_id}/result`
积分	1 每个已核验地址 (最坏情况)
测试密钥可用	否 —— 需要正式密钥
预计耗时	~15 分钟
前置条件	一把有余额的 qk_live_ 密钥，以及以数组或 CSV 文本形式提供的地址名单。

把名单作为一个任务提交

将操作与你的地址提交到批量端点，可以用 queries 数组，也可以用 csv_text。你会立即拿到一个任务 id，而不必为整份名单一直保持连接。

submit.sh

# Exactly one input source: queries[] or csv_text.
curl -X POST https://api.qannasapi.com/v1/bulk/jobs \
  -H "Authorization: Bearer $QANNAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "action": "verify_email",
        "queries": ["jane@acme.example", "sam@acme.example"],
        "webhook_url": "https://yourapp.example/hooks/qannas"
      }'

# < 200  { "status": "OK", "data": { /* job id */ } }

取回结果

先查询任务查看状态，完成后再取回结果。提交时提供 webhook_url，我们就会主动回调你 —— 对于几百个地址以上的名单，这才是更合适的形态。

collect.sh

# Poll the job …
curl https://api.qannasapi.com/v1/bulk/jobs/$JOB_ID \
  -H "Authorization: Bearer $QANNAS_API_KEY"

# … then pull the graded results once it has finished.
curl https://api.qannasapi.com/v1/bulk/jobs/$JOB_ID/result \
  -H "Authorization: Bearer $QANNAS_API_KEY"

# Supplying webhook_url on submission skips this loop entirely.

看评级，而不只是结论

核验为每个地址返回一个评级，而不是简单的是或否。阈值由你自己定：给一个评为「有风险」的地址发信，是可送达性上的取舍，而不是 API 的决定。

定期重新核验

随着人们更换工作，地址质量会衰减。每季度重跑一次名单并比对评级，能得出属于你自己数据的衰减率，这通常比任何单次核验更有价值。

decay.py

# Re-run quarterly and diff the grades. Your own decay rate is
# more useful than any single verification pass.
previous = load_grades("2026-Q2")
current = load_grades("2026-Q3")

decayed = [e for e in previous
           if ok(previous[e]) and not ok(current.get(e))]

print(f"{len(decayed) / len(previous):.1%} decayed this quarter")

小结

模式	做法
提交	POST /v1/bulk/jobs，带 action 以及 queries 或 csv_text
轮询	GET /v1/bulk/jobs/{job_id}
取回	GET /v1/bulk/jobs/{job_id}/result
免去轮询	提交时传入 webhook_url
成本形态	按判定出的地址计费，而非按提交的地址

上线检查清单

几百个地址以上的名单请使用 webhook。
存评级而不是布尔值 —— 你以后会想重新设定阈值。
提交大名单之前先为这次运行报价。
每季度重新核验，并跟踪你自己的衰减率。

下一步

范例 04

构建潜客名单

搜索、找到邮箱、核验邮箱 —— 一次调用取代三次，按步计费。

范例 03

处理无结果与重试

区分「没找到」和「失败」，只重试真正该重试的那一类。

先运行预估。它不花任何费用，用的正是计量器将要套用的那套算术。

获取你的 API 密钥阅读 API 参考文档