> ## 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 de validación de email

> Mejore la llegada a la bandeja de entrada y mantenga sus listas de correo saludables con la API de validación de email de Cleariflow, la mejor de su clase.

## Inicio rápido

Para hacer una solicitud, indique su `api_key` única y el `email` que desea verificar; no se requiere nada más:

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

La solicitud se completa correctamente y devuelve toda la información disponible sobre la dirección:

<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>

### Parámetros de solicitud

<ParamField query="api_key" type="string" required>
  Su credencial API personal. Las claves están limitadas por producto de Cleariflow, por lo que una clave de validación de email no autorizará solicitudes a, por ejemplo, la API de geolocalización IP.
</ParamField>

<ParamField query="email" type="String" required>
  La dirección de email que desea verificar.
</ParamField>

<ParamField query="auto_correct" type="Boolean">
  Indicador opcional para desactivar la autocorrección. Establezca `auto_correct=false` para desactivarla. Está habilitada de forma predeterminada.
</ParamField>

### Parámetros de respuesta

Las respuestas se devuelven en [JSON](https://www.json.org/json-en.html) compacto y estandarizado.

<ResponseField name="email" type="String">
  Devuelve el `email` enviado en la solicitud.
</ResponseField>

<ResponseField name="auto_correct" type="String">
  Corrección sugerida cuando se detecta un posible error tipográfico (p. ej., [johnsmith@gmial.com](mailto:johnsmith@gmial.com) => [johnsmith@gmail.com](mailto:johnsmith@gmail.com)). Vacío si no hay sugerencia.
</ResponseField>

<ResponseField name="deliverability" type="String">
  Evaluación de Cleariflow sobre si la dirección puede recibir correo. Valores posibles: `DELIVERABLE`, `UNDELIVERABLE`, `UNKNOWN`. `DELIVERABLE` requiere una verificación SMTP exitosa; si existen registros MX pero SMTP no puede confirmar el buzón (común en grandes proveedores), el resultado es `UNKNOWN`. Todos los planes ejecutan las mismas comprobaciones; los gratuitos solo difieren en cuota mensual y límites de velocidad (véase códigos 422 y 429).
</ResponseField>

<ResponseField name="quality_score" type="Float">
  Puntuación decimal (0,01–0,99) que indica nuestra confianza en la calidad y entregabilidad de la dirección.
</ResponseField>

<ResponseField name="is_valid_format" type="Boolean">
  Verdadero cuando la dirección coincide con el patrón estándar `local@domain.tld`. Elementos faltantes o caracteres no válidos devuelven `false`.
</ResponseField>

<ResponseField name="is_free_email" type="Boolean">
  Verdadero si el dominio pertenece a un proveedor de email gratuito (p. ej., Gmail, Yahoo).
</ResponseField>

<ResponseField name="is_disposable_email" type="Boolean">
  Verdadero si el dominio está en nuestra lista de proveedores de buzones desechables/temporales (p. ej., Mailinator, Yopmail).
</ResponseField>

<ResponseField name="is_role_email" type="Boolean">
  Verdadero si la parte local parece ser una cuenta de rol en lugar de un individuo, p. ej., `team@`, `sales@`, `info@`.
</ResponseField>

<ResponseField name="is_catchall_email" type="Boolean">
  Verdadero si el dominio está configurado como [catch‑all](https://www.corporatecomm.com/faqs/other-questions/what-is-a-catch-all-account).
</ResponseField>

<ResponseField name="is_mx_found" type="Boolean">
  Verdadero cuando existen [registros MX](https://en.wikipedia.org/wiki/MX_record) para el dominio.
</ResponseField>

<ResponseField name="is_smtp_valid" type="Boolean">
  Verdadero si la verificación [SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol) tiene éxito. Si SMTP falla pero otras comprobaciones pasan, el resultado puede ser `UNKNOWN`. No recomendamos bloquear registros o envíos de formularios únicamente por fallos SMTP.
</ResponseField>

## Ejemplos de solicitud

### Ejemplo: posible error tipográfico

Este ejemplo muestra una solicitud en la que se detecta un posible error tipográfico en la dirección enviada.

Incluso cuando se encuentra un posible error tipográfico, todas las demás comprobaciones (p. ej., email gratuito, dominio desechable) se realizan sobre la dirección enviada originalmente, no sobre la corrección sugerida.

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

Una respuesta exitosa tiene este aspecto:

```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"
  }
}
```

### Ejemplo: formato no válido

Este ejemplo demuestra una dirección que no supera el formato básico. Cuando `is_valid_format` es `false`, las comprobaciones posteriores (p. ej., `is_free_email`, `is_role_email`) se omiten y se informan como `false`.

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

Una respuesta exitosa tiene este aspecto:

```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"
  }
}
```

## Carga masiva (CSV)

¿Prefiere no llamar a la API directamente? Use el cargador masivo CSV: los resultados se le enviarán por email cuando finalice el procesamiento.

Al cargar un CSV, siga estas directrices:

* Coloque las direcciones de email en la primera columna.
* Elimine las filas en blanco.
* Use una dirección por fila.
* Limite los archivos a un máximo de 50.000 filas.

## Códigos de respuesta y error

Los errores se devuelven en JSON con un código y una descripción legible. Los códigos más comunes se enumeran a continuación.

| Code | Type                  | Details                                                                                 |
| ---- | --------------------- | --------------------------------------------------------------------------------------- |
| 200  | OK                    | Solicitud completada correctamente.                                                     |
| 400  | Bad request           | Solicitud mal formada o no válida.                                                      |
| 401  | Unauthorized          | Autenticación fallida, generalmente por una clave API faltante o no válida.             |
| 422  | Quota reached         | Cuota agotada (p. ej., créditos insuficientes en planes gratuitos).                     |
| 429  | Too many requests     | Límite de velocidad superado (los planes gratuitos permiten hasta 1 solicitud/segundo). |
| 500  | Internal server error | Error inesperado en nuestro lado.                                                       |
| 503  | Service unavailable   | Servicio temporalmente no disponible.                                                   |

## Otras notas

Nota sobre planes: todos los planes (gratuitos y de pago) ejecutan las mismas comprobaciones, incluidas MX, SMTP y detección catch-all.

Nota de facturación: cada email evaluado consume un crédito por solicitud, independientemente del resultado. Enviar una dirección no válida (p. ej., "fda3346ds") sigue contando como un crédito.