「域名健康度体检」是数据鱼API平台面向邮件送达能力的评分接口,Base 路径 /api/domain-health,共 3 个端点。它围绕一个域名的三项邮件基础设施配置做布尔判定:是否存在 SPF 所依赖的 TXT 记录、DMARC 专用子域上是否有 TXT 记录、主域是否配置 MX,并用固定权重合成 0–100 的分数,同时给出检查时间。
这个接口输出的是结论而不是明细:不返回每条 TXT 的原文,也不返回 MX 主机与优先级,只回答「配没配」和「总分多少」。因此它适合放在资产台账与巡检报表里,作为一列状态字段;需要查看具体记录内容时,应改用按记录类型返回明细的解析查询能力。
评分口径固定:SPF 项 33 分、DMARC 项 33 分、MX 项 34 分,满分 100。三项都为真时得 100,全缺失时为 0,不存在部分扣分或人工加权。检查通过系统 DNS 解析完成,不访问网页、不探测端口,也不涉及证书与域名注册信息——这些不属于本接口的检查范围。
方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
GET | /api/domain-health/ping | 健康检查,返回服务版本与时间 | 免鉴权 |
GET | /api/domain-health/check | 查询参数方式执行体检 | 需要 |
POST | /api/domain-health/check | 请求体方式执行体检,参数同名 | 需要 |
鉴权使用 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011、无效返回 4013。响应为 {code, msg, data} 三段结构,code 为 0 表示成功;ping 的成功消息是 pong,check 的是 success。参数类错误包括 4001 缺少必填参数、4002 格式非法、4003 取值不在支持列表、4004 查询目标未收录;4040 为路由不存在,4050 为方法不允许,5000/5001 为服务内部错误,5031/5032 表示上游依赖不可用且不会以占位数据冒充结果。同一路径的 GET 与 POST 共用一套参数名,POST 支持 JSON body 或表单。这是数据鱼API平台开发工具类接口的共同约定。
用途:对单个域名执行三项配置判定并返回评分。
参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
domain | string | 是 | — | 待体检的域名,原样回显 |
API.md 把 domain 标为可选,但实现中为空即返回 4001 Missing domain,两种调用方式都必须携带。接口不做格式预校验:传入不符合域名规范的字符串不会得到 4002,而是三项判定全部为假、得分 0——「域名无效」与「配置全缺」在响应上不可区分,调用方需在本地先校验格式。
返回字段要点:domain 为请求原值;spf_configured、dmarc_configured、mx_configured 为三个布尔判定;score 为整数评分,按 33/33/34 加权;last_checked 为服务端检查时间,格式 Y-m-d H:i:s,无时区标记。响应中不含单项扣分原因,也不含原始记录。
GET /api/domain-health/check?api_key=YOUR_KEY&domain=YOUR_DOMAINPOST /api/domain-health/check?api_key=YOUR_KEY
Content-Type: application/json
{"domain":"YOUR_DOMAIN"}两种方式返回结构完全一致,可任选其一;批量场景由调用方循环调用,接口本身不接受域名数组。
用途:探活与版本核对。无参数、免鉴权,返回 data.version(当前 1.0.0)与 data.time。适合作为监控探针,或在上线前确认实例版本。
GET /api/domain-health/pinglast_checked 由服务端在响应时生成。score 与三个布尔值写入表格,按季度对比配置变化。score 低于阈值或某一项由真变假作为触发条件,纳入既有监控。domain 标注为可选,实际必填并返回 4001;ping 示例携带了 Key,但端点声明为免鉴权。以实测行为为准。spf_configured 的判定只看该域是否存在任意 TXT 记录,不解析记录内容是否以 v=spf1 开头。存在一条无关的 TXT(例如站点验证串)就会判为真,因此该字段不能等同于「SPF 策略有效」。p= 策略,也不判断记录是否语法正确;p=none 与 p=reject 得到相同结果。last_checked 无时区标识,跨时区汇总时需约定按服务端时区解释。原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。