零基础接入邮箱地址检测 API：参数、请求与返回字段详解

邮箱地址检测接口是一个综合性邮箱质量评估接口一次 GET 请求即可完成六项检测。对于需要在用户注册时过滤垃圾邮箱、在发送邮件前清洗列表的场景它比单纯的正则校验更有实际意义。本文从零开始说明第一次调用需要准备什么、最小请求怎么发、返回值怎么看。适用场景与能力边界典型用例有三类用户注册表单提交后判断邮箱是否值得接受邮件列表发送前剔除一次性域名与拼写错误地址KYC 或风控流程中作为辅助信号评估联系方式质量。接口一次请求完成六项检测RFC 5322 格式校验临时/一次性邮箱检测基于 72,345 条开源域名库合并 3 个数据源去重MX 记录验证使用 AliDNS DoH 查询规避 PHPgetmxrr不稳定的问题拼写纠正例如将gmial.com提示为gmail.com服务商识别覆盖 QQ 邮箱、Gmail、网易、Outlook 等 40 余个主流服务商综合风险评分 0-100并附带详细原因清单能力边界需要说清楚接口判断的是邮箱地址层面的质量不验证该地址是否真实属于某个用户也不做发信验证。风险评分是启发式评估结果不是确定性结论业务侧应结合自身规则使用。调用前的准备需要两样东西一个待检测的邮箱地址以及一个 API Key。API Key 通过极数本源平台的账号密钥页面获取。接口兼容多种传参形式推荐在请求头中使用Authorization: Bearer API_KEY也兼容X-API-Key请求头或 Query 中的key参数。本文示例使用 Query 参数形式便于 curl 直接复制。最小请求curl 示例把YOUR_API_KEY替换为实际 Key、testgmial.com替换为待检测地址即可在终端执行curl https://v1.apizero.cn/api/email-check?emailtestgmial.comkeyYOUR_API_KEY使用请求头鉴权的写法curl -H Authorization: Bearer YOUR_API_KEY \ https://v1.apizero.cn/api/email-check?emailtestgmial.com接口方法为 GET唯一必填参数是email。如果邮箱包含、等特殊字符务必做 URL 编码否则 Query String 解析会出错。Python 接入示例下面封装一个带超时、编码与业务码判断的调用函数import os import requests def check_email(email: str, api_key: str | None None) - dict: url https://v1.apizero.cn/api/email-check params {email: email} headers {} key api_key or os.environ.get(APIZERO_KEY) if key: headers[Authorization] fBearer {key} resp requests.get(url, paramsparams, headersheaders, timeout15) resp.raise_for_status() payload resp.json() if payload.get(code) ! 0: raise RuntimeError(f接口返回错误: code{payload.get(code)}, msg{payload.get(msg)}) return payload[data] result check_email(testgmial.com) print(result.get(score), result.get(suggestion))注意requests会自动对params做 URL 编码手工拼接字符串则不会。返回字段解读成功响应中code 0表示业务成功核心数据在data内。以下结构与字段名以文档为准常见字段含义如下字段含义email回显被检测的地址valid_formatRFC 5322 格式是否通过is_disposable是否命中临时/一次性邮箱域名库mx_validMX 记录是否可解析provider识别出的服务商名称suggestion拼写纠正建议无建议时为空score综合风险评分 0-100reasons风险原因清单逐条说明扣分依据建议的读取顺序先看valid_format格式不合法可以直接短路不必关心后续字段再看is_disposable与mx_valid这两项决定邮箱能否正常收信suggestion非空时可提示用户“您是不是想输入 gmail.com”最后用score与reasons做综合判定。评分的用法需要谨慎。素材未给出分档阈值具体阈值应以文档为准或由业务方根据自身样本自行标定。不建议把分数直接等同于“可用/不可用”的二元结论。常见错误与排查现象可能原因排查方向code非 0提示鉴权失败Key 无效、缺失或未正确传递检查 Header 或 Query 中的 Keycode非 0提示参数错误email为空或未做 URL 编码确认参数存在并对特殊字符编码HTTP 429 或限流提示超出调用频率限制控制并发QPS 以文档为准mx_valid为 false 但格式正确域名无有效 MX 记录属于正常检测结果不是接口故障工程化注意事项Key 保存在服务端。邮箱检测通常发生在注册或登录流程中务必由后端代理调用前端不接触密钥。加缓存。同一邮箱在短时间内重复检测意义不大可按邮箱地址做短 TTL 缓存降低请求量并加快响应。区分“检测失败”与“检测结果为差”。接口报错网络异常、非 0 业务码应走降级逻辑不能当成“邮箱有风险”直接拒绝用户后者是业务判断前者是系统故障。评分不要单点决策。结合格式、一次性域名、MX 三项硬性结果做主要判断评分作为加权信号避免误伤正常用户。注意隐私。邮箱属于个人信息日志中记录时应脱敏不要明文落盘。参考文档接口文档接口地址