「邮箱地址校验」是数据鱼API平台提供的邮箱地址格式校验接口,Base 路径 /api/email-validator,共 3 个端点。它的职责范围很窄:判断一个邮箱地址是否符合标准语法,拆出其中的域名部分,并对照内置的一次性邮箱域名名单给出「是否为临时邮箱」的标记。适合放在注册、订阅、留资等表单的提交链路上做第一道过滤。
需要明确的是,这个接口做的是语法层面的校验,不是投递层面的验证。它不查询 DNS 记录,不探测 MX 主机是否存在,也不与会话式验证服务器握手,因此无法回答「这个邮箱真实存在吗」「现在能收信吗」这类问题。它能回答的是「写法是否合法」「域名是否在已知的一次性邮箱名单里」。把这两类能力混为一谈,是集成时最常见的误解。
接口的判定基于标准邮箱语法规则与一份内置域名清单,全部在服务端本地完成,不依赖外部网络,因此响应稳定、延迟低,也不会因为上游服务不可用而失败。对于需要在用户输入瞬间给出反馈的表单场景,这种确定性比覆盖更多边缘情况更重要。
输入会被统一去除首尾空白并转为小写后再判断,返回结果中同时回显处理后的地址与拆分出的域名,便于调用方直接落库或做后续统计。
方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
GET | /api/email-validator/ping | 健康检查(免鉴权) | 免鉴权 |
GET | /api/email-validator/validate | 通过查询参数校验邮箱地址 | 需要 |
POST | /api/email-validator/validate | 通过请求体校验邮箱地址 | 需要 |
鉴权使用 X-API-Key 请求头或 ?api_key= 查询参数,全站统一 Key:缺失返回 4011,无效返回 4013。响应统一为 {code, msg, data} 三段结构,code 为 0 表示成功。本接口使用的错误码较少:4001 表示缺少参数,4002 表示参数非法,4004 表示目标不存在,5032 表示上游服务不可用。由于校验在本地完成,5032 实际很少触发。
GET 与 POST 两个端点指向同一路径、共用同一套参数与返回结构,区别只在参数所在的位置。表单场景用 GET 拼接查询参数最省事,参数较长或含有特殊字符时改用 POST 请求体更稳妥。以上约定由数据鱼API平台统一提供。
用途:对单个邮箱地址做语法校验与一次性域名判断。
参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
string | 否 | — | 待校验的邮箱地址 |
参数在文档中标注为非必填,但实际业务语义上必须提供。未传或传空字符串时,接口不会返回 4001,而是返回 code 为 0、valid 为 false、email 与 domain 均为空串的正常结构。这种设计把「没传」和「传了但不合法」在结果层做了统一,调用方需要自己区分这两种情况。
返回字段:valid 为布尔值,表示语法是否合法;email 为归一化后的地址(去空白、转小写);domain 为按第一个 @ 拆分出的域名部分;is_disposable 表示域名是否命中内置的一次性邮箱名单;queried_at 为服务器时间。
请求示例:
GET /api/email-validator/validate?api_key=YOUR_KEY&email=YOUR_EMAIL响应中 email 会去除首尾空白并转为小写,domain 为拆分出的小写域名,valid 为 true。
POST 版本参数相同,放在 JSON body 中:
POST /api/email-validator/validate?api_key=YOUR_KEY
Content-Type: application/json
{"email":"YOUR_EMAIL"}免鉴权、无参数,用于探活与部署确认。返回结构中 code 为 0、msg 为 pong,data 通常携带服务名与版本信息。
GET /api/email-validator/ping@ 之后的全部内容提取。queried_at 为服务器本地时间,格式 Y-m-d H:i:s。is_disposable 标记一次性邮箱,决定是拦截、降权还是仅做记录。is_disposable 为 false 不代表该邮箱一定不是临时邮箱;名单更新也不在接口调用方可控范围内。email 时返回的是 code 0 加 valid false,而不是参数错误。若客户端只看 code 判断成功,会把空提交当成校验通过,务必以 valid 字段作为最终依据。@ 切分,含有多个 @ 的畸形输入会得到不完整的域名片段,展示前请结合 valid 一起判断。原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。