跳转到主要内容
GET
/
v1
邮箱验证 API
curl --request GET \
  --url https://emailvalidation.cleariflow.com/v1
{
  "email": "jane.doe@acme-corp.com",
  "autocorrect": "",
  "deliverability": "DELIVERABLE",
  "quality_score": 0.85,
  "is_valid_format": {
    "value": true,
    "text": "TRUE"
  },
  "is_free_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_disposable_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_role_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_catchall_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_mx_found": {
    "value": true,
    "text": "TRUE"
  },
  "is_smtp_valid": {
    "value": true,
    "text": "TRUE"
  }
}

​
快速开始

发起请求时，只需提供您的唯一 api_key 和要检查的 email——无需其他参数： 
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = jane.doe@acme-corp.com
请求成功后，将返回该地址的所有可用分析结果： 
{
  "email": "jane.doe@acme-corp.com",
  "autocorrect": "",
  "deliverability": "DELIVERABLE",
  "quality_score": 0.85,
  "is_valid_format": {
    "value": true,
    "text": "TRUE"
  },
  "is_free_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_disposable_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_role_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_catchall_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_mx_found": {
    "value": true,
    "text": "TRUE"
  },
  "is_smtp_valid": {
    "value": true,
    "text": "TRUE"
  }
}

​
请求参数

​
api_key
string
必填
您的个人 API 凭证。密钥按 Cleariflow 产品划分范围，因此邮箱验证密钥无法授权 例如 IP 地理定位 API 的请求。
​
email
String
必填
您要验证的邮箱地址。
​
auto_correct
Boolean
可选标志，用于禁用自动纠错。设置 auto_correct=false 可关闭此功能。 默认启用。

​
响应参数

响应以紧凑、标准化的 JSON 格式返回。
​
email
String
返回请求中提交的 email。
​
auto_correct
String
检测到可能的拼写错误时建议的修正（例如 johnsmith@gmial.com => johnsmith@gmail.com）。无建议时为空。
​
deliverability
String
Cleariflow 对该地址能否接收邮件的评估。可能的值： DELIVERABLE、UNDELIVERABLE、UNKNOWN。DELIVERABLE 需要 SMTP 验证成功；若存在 MX 记录但 SMTP 无法确认邮箱（大型服务商常见），结果为 UNKNOWN。所有计划执行相同的 验证；免费计划仅在月度配额和速率限制上有所不同（见错误代码 422、429）。
​
quality_score
Float
反映地址质量的十进制分数，范围 0 至 0.99。一次性地址上限约 0.05；未通过 SMTP 确认时最高 0.55。
​
is_valid_format
Boolean
当地址符合标准格式 local@domain.tld 时为 true。 缺少元素或包含无效字符时返回 false。
​
is_free_email
Boolean
若域名属于免费邮箱提供商（如 Gmail、Yahoo）则为 true。
​
is_disposable_email
Boolean
若域名在我们的一次性/临时收件箱提供商列表中 （如 Mailinator、Yopmail）则为 true。
​
is_role_email
Boolean
若本地部分似乎是角色账户而非个人账户则为 true， 例如 team@、sales@、info@。
​
is_catchall_email
Boolean
若域名配置为 全收（catch-all） 则为 true。
​
is_mx_found
Boolean
当域名的 MX 记录 存在时为 true。
​
is_smtp_valid
Boolean
当 SMTP 验证成功时为 true。若 SMTP 失败但其他检查通过，结果可能为 UNKNOWN。我们建议不要仅因 SMTP 失败而阻止注册或表单提交。

​
请求示例

​
示例：可能的拼写错误

此示例展示检测到提交地址中可能存在拼写错误的情况。 即使发现可能的拼写错误，所有其他检查（如免费邮箱、 一次性域名）仍针对原始提交的地址执行——而非建议的修正地址。 
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith@gmial.con
成功响应如下： 
{
  "email": "johnsmith@gmial.con",
  "autocorrect": "johnsmith@gmail.com",
  "deliverability": "UNKNOWN",
  "quality_score": 0.4,
  "is_valid_format": {
    "value": true,
    "text": "TRUE"
  },
  "is_free_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_disposable_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_role_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_catchall_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_mx_found": {
    "value": false,
    "text": "FALSE"
  },
  "is_smtp_valid": {
    "value": false,
    "text": "FALSE"
  }
}

​
示例：无效格式

此示例演示格式检查失败的地址。当 is_valid_format 为 false 时，后续检查（如 is_free_email、 is_role_email）将被跳过并报告为 false。 
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith
成功响应如下： 
{
  "email": "johnsmith",
  "autocorrect": "",
  "deliverability": "UNDELIVERABLE",
  "quality_score": 0.0,
  "is_valid_format": {
    "value": false,
    "text": "FALSE"
  },
  "is_free_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_disposable_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_role_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_catchall_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_mx_found": {
    "value": false,
    "text": "FALSE"
  },
  "is_smtp_valid": {
    "value": false,
    "text": "FALSE"
  }
}

​
批量上传（CSV）

不想直接调用 API？可使用 CSV 批量上传工具——处理完成后结果将通过邮件发送给您。 上传 CSV 时请遵循以下准则：
  • 将邮箱地址放在第一列。
  • 删除所有空白行。
  • 每行一个地址。
  • 文件最多 50,000 行。

​
响应和错误代码

错误以 JSON 格式返回，包含代码和可读描述。常见代码如下。
CodeTypeDetails
200OK请求成功完成。
400Bad request请求格式错误或无效。
401Unauthorized身份验证失败——通常是 API 密钥缺失或无效。
422Quota reached配额已用尽（例如免费计划积分不足）。
429Too many requests超出速率限制（免费计划最多 1 次请求/秒）。
500Internal server error我方发生意外错误。
503Service unavailable服务暂时不可用。

​
其他说明

计划说明：所有计划（免费和付费）执行相同的验证，包括 MX、SMTP 和 catch-all 检测。 计费说明：每验证一个邮箱消耗一次请求积分——无论结果如何。提交无效地址（如 “fda3346ds”）仍计为一次积分。