首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API「邮箱地址校验」接口功能介绍

数据鱼API「邮箱地址校验」接口功能介绍

原创
作者头像
用户12862874
发布于 2026-11-21 21:26:55
发布于 2026-11-21 21:26:55
60
举报

接口简介

「邮箱地址校验」是数据鱼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平台统一提供。

核心端点详解

邮箱校验(GET/POST /validate)

用途:对单个邮箱地址做语法校验与一次性域名判断。

参数

类型

必填

默认

说明

email

string

否

—

待校验的邮箱地址

参数在文档中标注为非必填,但实际业务语义上必须提供。未传或传空字符串时,接口不会返回 4001,而是返回 code 为 0、valid 为 false、email 与 domain 均为空串的正常结构。这种设计把「没传」和「传了但不合法」在结果层做了统一,调用方需要自己区分这两种情况。

返回字段:valid 为布尔值,表示语法是否合法;email 为归一化后的地址(去空白、转小写);domain 为按第一个 @ 拆分出的域名部分;is_disposable 表示域名是否命中内置的一次性邮箱名单;queried_at 为服务器时间。

请求示例:

代码语言:javascript
复制
GET /api/email-validator/validate?api_key=YOUR_KEY&email=YOUR_EMAIL

响应中 email 会去除首尾空白并转为小写,domain 为拆分出的小写域名,valid 为 true。

POST 版本参数相同,放在 JSON body 中:

代码语言:javascript
复制
POST /api/email-validator/validate?api_key=YOUR_KEY
Content-Type: application/json

{"email":"YOUR_EMAIL"}

健康检查(GET /ping)

免鉴权、无参数,用于探活与部署确认。返回结构中 code 为 0、msg 为 pong,data 通常携带服务名与版本信息。

代码语言:javascript
复制
GET /api/email-validator/ping

数据与限制

  • 校验方式为语法规则匹配加内置域名名单比对,全程本地计算,无 DNS 查询、无 SMTP 探测、无外部请求。
  • 输入统一去除首尾空白并转为小写,域名按第一个 @ 之后的全部内容提取。
  • 一次性邮箱判定基于一份固定的内置名单,覆盖范围有限,名单之外的一次性邮箱不会被识别。
  • 单次请求只处理一个地址,没有批量端点;批量场景需在客户端循环调用并自行控制并发。
  • 结果即时返回,无缓存层;queried_at 为服务器本地时间,格式 Y-m-d H:i:s。
  • 接口不对地址做存在性、可达性或归属验证。数据鱼API把它定位为输入侧的第一道格式过滤,而不是投递前的最终检查。

典型使用场景

  • 注册表单在提交前调用校验,把语法明显错误的地址挡在写入用户表之前,减少后续退信。
  • 订阅与留资页面用 is_disposable 标记一次性邮箱,决定是拦截、降权还是仅做记录。
  • 数据清洗脚本批量遍历历史邮箱列表,统一大小写并筛出格式非法的记录。

注意事项

  • 「语法合法」不等于「邮箱可用」。本接口不验证域名是否解析、是否有 MX 记录、邮箱是否真实存在,通过校验只说明写法符合标准。若业务需要投递级验证,应另行接入邮件验证服务,二者不可互相替代。
  • 一次性域名名单是静态且有限的,is_disposable 为 false 不代表该邮箱一定不是临时邮箱;名单更新也不在接口调用方可控范围内。
  • 未传 email 时返回的是 code 0 加 valid false,而不是参数错误。若客户端只看 code 判断成功,会把空提交当成校验通过,务必以 valid 字段作为最终依据。
  • 域名提取逻辑按第一个 @ 切分,含有多个 @ 的畸形输入会得到不完整的域名片段,展示前请结合 valid 一起判断。
  • 本接口对邮箱域名的任何分类判断均为技术性识别,具体归类以邮箱服务商与收件人实际设置情况为准。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 邮箱校验(GET/POST /validate)
    • 健康检查(GET /ping)
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档