适用场景邮箱地址检测接口在用户准备时的反垃圾邮箱过滤、邮件营销列表清洗、KYC 风控辅助等场景中扮演重要角色。一次请求即可完成 RFC 5322 格式校验、临时邮箱检测、MX 记录验证、拼写纠正、服务商识别和综合风险评分减少开发者自行组合多个数据源的维护维护复杂度。接口能力边界接口基于 GET 方法地址为https://v1.apizero.cn/api/email-checkQPS 上限为 10 次/秒。实现以下六项检测RFC 5322 格式校验检查邮箱字符串是否符合标准电子邮件格式。临时/一次性邮箱检测基于 72,345 条开源域名库三数据源合并去重判断是否来自临时邮箱服务。MX 记录验证通过 AliDNS DoH 查询域名 MX 记录避免 PHPgetmxrr的不稳定性。拼写纠正检测常见输入错误例如gmial.com→ 提示gmail.com。服务商识别支持 QQ邮箱、Gmail、网易、Outlook 等 40 主流邮箱服务商。综合风险评分输出 0–100 的整数分数附带详细原因清单。请求参数与鉴权Query 参数参数类型必填说明emailstring是待检测的邮箱地址最长 254 字符RFC 上限Header 参数参数类型必填说明X-API-Keystring否API Key不传时使用匿名额度请参考文档确认额度限制注意匿名额度可能有限制生产环境建议携带有效的 API Key。curl 接入示例以下命令演示如何使用 curl 发起检测请求curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/email-check?emailtestgmial.com请将环境变量$APIZERO_API_KEY替换为真实的 API Key或将-H字段直接替换为X-API-Key: your_key_here。返回结果如下经缩略处理{ code: 0, msg: 成功, request_id: mota..., data: { input: testgmial.com, email: testgmial.com, local: test, domain: gmial.com, valid_format: true, has_mx: false, mx_records: [], is_disposable: false, disposable_match: null, is_trusted: false, provider: null, spelling_suggestion: gmail.com, risk_score: 5, risk_level: invalid, reasons: [ ⚠️ 域名无 MX 记录无法接收邮件, ⚠️ 域名疑似拼写错误建议用 gmail.com, ⚠️ 本地部分含测试/系统类关键词 ] } }响应字段详解字段类型说明codeinteger业务状态码0 表示成功msgstring状态码对应的说明文字request_idstring请求唯一标识可用于日志对账data.inputstring原始输入邮箱data.emailstring规范化后的邮箱多数情况与 input 一致data.localstring邮箱的本地部分 之前data.domainstring邮箱域名部分 之后data.valid_formatboolean是否符合 RFC 5322 格式data.has_mxboolean域名是否存在 MX 记录data.mx_recordsstring[]MX 记录列表若无则为空数组data.is_disposableboolean是否为临时/一次性邮箱data.disposable_matchstring/null命中的临时邮箱域名或 nulldata.is_trustedboolean是否被认定为可信通常为知名服务商data.providerstring/null邮箱服务商名称未知时为 nulldata.spelling_suggestionstring/null拼写修正建议无错误时为 nulldata.risk_scoreinteger综合风险评分0-100越高越危险data.risk_levelstring风险等级valid/low/medium/high/invaliddata.reasonsstring[]风险原因描述列表常见错误与排错指南错误 1请求返回 401 Unauthorized现象HTTP 状态码 401body 中 code 为非 0 值。原因X-API-Key缺失或无效。排查步骤确认 curl 请求中-H参数格式正确如-H X-API-Key: sk-xxxx。检查 API Key 是否被正确复制注意前后无多余空格。若使用匿名请求确认匿名额度余量以官方文档为准。错误 2格式校验失败valid_format: false现象返回valid_format: false且risk_level常为invalid。原因邮箱字符串不符合 RFC 5322例如缺少 、包含空格、多级域名段过长等。排查步骤使用echo email确认实际传入值是否包含不可见字符如回车。检查 URL 编码特殊字符如、#需要正确编码。邮箱长度是否超过 254 字符超出则被截断或直接返回格式错误。错误 3MX 记录查询结果与预期不符现象has_mx为 false但域名其实存在正规邮箱服务。原因域名 DNS 解析临时异常或 AliDNS DoH 不可达。域名使用较新的子域名邮箱MX 记录配置未更新。排查步骤在本地运行dig domain MX或nslookup -typemx domain验证。若本地能查到但接口查不到间隔几秒重试一次确认是否为瞬态故障。检查域名网络环境某些内网域名可能被外部 DoH 拦截。错误 4临时邮箱检测漏报或误报现象某临时邮箱返回is_disposable: false或正规邮箱被标记为临时。原因开源域名库更新滞后或存在冲突。排查步骤查看reasons字段是否包含临时邮箱判断依据。收集该域名自行比对https://github.com/disposable-email-domains等权威列表。若为误报可考虑在业务层对特定域名做白名单覆盖。错误 5拼写纠正提示不准确现象spelling_suggestion给出的域名不适用于当前业务场景。原因拼写纠正基于编辑距离算法可能受到短域名或域名拓扑影响。排查步骤检查domain与spelling_suggestion的相似度若相差较大可忽略该提示。对于gmial→gmail这种常见错误通常准确率较高但如abc.com→ab.com可能误判建议结合自己的域名白名单二次确认。错误 6风险评分不符合业务预期现象某邮箱在业务中被确认为正常用户但risk_score偏高如 70。原因评分模型可能因本地部分含测试关键词如test、admin或域名无 MX 记录而扣分但不代表邮箱不可用。排查步骤逐条阅读reasons评估每一条是否有业务冲突。例如测测试户使用testexample.com时reasons会提示“本地部分含测试/系统类关键词”此时可以人工放行。设置业务阈值如果风险risk_level为invalid则拒绝其余可放行或结合其他风控信号综合判断。工程化注意事项QPS 控制接口 QPS 上限为 10 次/秒。批量任务建议引入队列或限流器如令牌桶避免超过限制导致 429 错误。重试策略对于网络超时、HTTP 5xx 错误可实施指数退避重试初始间隔 1s最多 3 次。注意判断幂等性GET 请求天然幂等重复调用不会产生副作用。缓存对于同一邮箱的重复检测建议缓存结果TTL 根据业务敏感度设定如 24 小时既降低调用量又提升响应速度。日志记录记录每次请求的request_id、输入邮箱、耗时和核心字段risk_score、risk_level便于事后审计和问题追踪。异常处理API 可能返回非 JSON 内容如网关错误解析时需做 try/catch 并打印原始响应体以辅助排查。参考文档接口文档https://apizero.cn/aidocs/email-check原始 API 定义https://apizero.cn/aidocs/email-check/raw.md
