> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 邮箱验证 API

> 通过全面的语法、域名和邮箱验证来校验邮箱地址。减少退信，提升送达率，并保护您的平台免受垃圾信息影响。

## 快速开始

发起请求时，只需提供您的唯一 `api_key` 和要检查的 `email`——无需其他参数：

```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = jane.doe@acme-corp.com
```

请求成功后，将返回该地址的所有可用分析结果：

<ResponseExample>
  ```json theme={"system"}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### 请求参数

<ParamField query="api_key" type="string" required>
  您的个人 API 凭证。密钥按 Cleariflow 产品划分范围，因此邮箱验证密钥无法授权
  例如 IP 地理定位 API 的请求。
</ParamField>

<ParamField query="email" type="String" required>
  您要验证的邮箱地址。
</ParamField>

<ParamField query="auto_correct" type="Boolean">
  可选标志，用于禁用自动纠错。设置 `auto_correct=false` 可关闭此功能。
  默认启用。
</ParamField>

### 响应参数

响应以紧凑、标准化的 [JSON](https://www.json.org/json-en.html) 格式返回。

<ResponseField name="email" type="String">
  返回请求中提交的 `email`。
</ResponseField>

<ResponseField name="auto_correct" type="String">
  检测到可能的拼写错误时建议的修正（例如
  [johnsmith@gmial.com](mailto:johnsmith@gmial.com) => [johnsmith@gmail.com](mailto:johnsmith@gmail.com)）。无建议时为空。
</ResponseField>

<ResponseField name="deliverability" type="String">
  Cleariflow 对该地址能否接收邮件的评估。可能的值：
  `DELIVERABLE`、`UNDELIVERABLE`、`UNKNOWN`。`DELIVERABLE` 需要 SMTP 验证成功；若存在
  MX 记录但 SMTP 无法确认邮箱（大型服务商常见），结果为 `UNKNOWN`。所有计划执行相同的
  验证；免费计划仅在月度配额和速率限制上有所不同（见错误代码 422、429）。
</ResponseField>

<ResponseField name="quality_score" type="Float">
  反映地址质量的十进制分数，范围 `0` 至 `0.99`。一次性地址上限约 `0.05`；未通过 SMTP 确认时最高 `0.55`。
</ResponseField>

<ResponseField name="is_valid_format" type="Boolean">
  当地址符合标准格式 `local@domain.tld` 时为 true。
  缺少元素或包含无效字符时返回 `false`。
</ResponseField>

<ResponseField name="is_free_email" type="Boolean">
  若域名属于免费邮箱提供商（如 Gmail、Yahoo）则为 true。
</ResponseField>

<ResponseField name="is_disposable_email" type="Boolean">
  若域名在我们的一次性/临时收件箱提供商列表中
  （如 Mailinator、Yopmail）则为 true。
</ResponseField>

<ResponseField name="is_role_email" type="Boolean">
  若本地部分似乎是角色账户而非个人账户则为 true，
  例如 `team@`、`sales@`、`info@`。
</ResponseField>

<ResponseField name="is_catchall_email" type="Boolean">
  若域名配置为
  [全收（catch-all）](https://www.corporatecomm.com/faqs/other-questions/what-is-a-catch-all-account)
  则为 true。
</ResponseField>

<ResponseField name="is_mx_found" type="Boolean">
  当域名的 [MX 记录](https://en.wikipedia.org/wiki/MX_record) 存在时为 true。
</ResponseField>

<ResponseField name="is_smtp_valid" type="Boolean">
  当
  [SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol)
  验证成功时为 true。若 SMTP 失败但其他检查通过，结果可能为
  `UNKNOWN`。我们建议不要仅因 SMTP 失败而阻止注册或表单提交。
</ResponseField>

## 请求示例

### 示例：可能的拼写错误

此示例展示检测到提交地址中可能存在拼写错误的情况。

即使发现可能的拼写错误，所有其他检查（如免费邮箱、
一次性域名）仍针对原始提交的地址执行——而非建议的修正地址。

```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith@gmial.con
```

成功响应如下：

```json theme={"system"}
{
  "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`。

```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith
```

成功响应如下：

```json theme={"system"}
{
  "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 格式返回，包含代码和可读描述。常见代码如下。

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

## 其他说明

计划说明：所有计划（免费和付费）执行相同的验证，包括 MX、SMTP 和 catch-all 检测。

计费说明：每验证一个邮箱消耗一次请求积分——无论结果如何。提交无效地址（如 "fda3346ds"）仍计为一次积分。