> ## 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 validação de email

> Valide endereços de email com verificação completa de sintaxe, domínio e caixa de correio. Reduza devoluções, melhore a entregabilidade e proteja a sua plataforma contra spam.

## Início rápido

Para fazer um pedido, forneça o seu `api_key` único e o `email` que pretende verificar — nada mais é necessário:

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

O pedido é bem-sucedido e devolve todas as informações disponíveis sobre o endereço:

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

<ParamField query="api_key" type="string" required>
  As suas credenciais pessoais de API. As chaves são limitadas por produto Cleariflow, pelo que uma
  chave de validação de email não autorizará pedidos a, por exemplo, a API de geolocalização IP.
</ParamField>

<ParamField query="email" type="String" required>
  O endereço de email que pretende verificar.
</ParamField>

<ParamField query="auto_correct" type="Boolean">
  Flag opcional para desativar a autocorreção. Defina `auto_correct=false` para a desligar.
  Está ativada por predefinição.
</ParamField>

### Parâmetros de resposta

As respostas são devolvidas como [JSON](https://www.json.org/json-en.html) compacto e padronizado.

<ResponseField name="email" type="String">
  Repete o `email` enviado no pedido.
</ResponseField>

<ResponseField name="auto_correct" type="String">
  Correção sugerida quando é detetado um provável erro de escrita (por exemplo,
  [johnsmith@gmial.com](mailto:johnsmith@gmial.com) => [johnsmith@gmail.com](mailto:johnsmith@gmail.com)). Vazio se não houver sugestão.
</ResponseField>

<ResponseField name="deliverability" type="String">
  Avaliação da Cleariflow sobre se o endereço pode receber correio. Valores
  possíveis: `DELIVERABLE`, `UNDELIVERABLE`, `UNKNOWN`. `DELIVERABLE` exige verificação
  SMTP bem-sucedida; se existirem registros MX mas o SMTP não confirmar a caixa (comum
  em grandes provedores), o resultado é `UNKNOWN`. Todos os planos executam as mesmas
  verificações; os gratuitos diferem apenas na quota mensal e nos limites de taxa (ver
  códigos 422 e 429).
</ResponseField>

<ResponseField name="quality_score" type="Float">
  Pontuação decimal de `0` a `0.99` que reflete a qualidade do endereço. Endereços
  descartáveis ficam limitados a cerca de `0.05`; sem confirmação SMTP, máximo `0.55`.
</ResponseField>

<ResponseField name="is_valid_format" type="Boolean">
  `true` quando o endereço corresponde ao padrão `local@domain.tld`.
  Elementos em falta ou caracteres inválidos resultam em `false`.
</ResponseField>

<ResponseField name="is_free_email" type="Boolean">
  `true` se o domínio pertence a um fornecedor de email gratuito (por exemplo, Gmail, Yahoo).
</ResponseField>

<ResponseField name="is_disposable_email" type="Boolean">
  `true` se o domínio está na nossa lista de fornecedores de caixas de correio
  descartáveis/temporárias (por exemplo, Mailinator, Yopmail).
</ResponseField>

<ResponseField name="is_role_email" type="Boolean">
  `true` se a parte local parece ser uma conta de função e não de um
  indivíduo, por exemplo `team@`, `sales@`, `info@`.
</ResponseField>

<ResponseField name="is_catchall_email" type="Boolean">
  `true` se o domínio 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">
  `true` quando existem [registos MX](https://en.wikipedia.org/wiki/MX_record) para o
  domínio.
</ResponseField>

<ResponseField name="is_smtp_valid" type="Boolean">
  `true` se a verificação
  [SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol)
  for bem-sucedida. Se o SMTP falhar mas outras verificações passarem, o resultado pode ser
  `UNKNOWN`. Não recomendamos bloquear registos ou submissões de formulários apenas com base em
  falhas SMTP.
</ResponseField>

## Exemplos de pedidos

### Exemplo: provável erro de escrita

Este exemplo mostra um pedido em que é detetado um provável erro de escrita no endereço
enviado.

Mesmo quando é encontrado um provável erro de escrita, todas as outras verificações (por exemplo, email gratuito,
domínio descartável) são realizadas sobre o endereço originalmente enviado — não sobre a
correção sugerida.

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

Uma resposta bem-sucedida tem este aspeto:

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

### Exemplo: formato inválido

Este exemplo demonstra um endereço que falha a formatação básica. Quando
`is_valid_format` é `false`, verificações subsequentes (por exemplo, `is_free_email`,
`is_role_email`) são ignoradas e reportadas como `false`.

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

Uma resposta bem-sucedida tem este aspeto:

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

## Carregamento em massa (CSV)

Prefere não chamar a API diretamente? Utilize o carregador em massa CSV — os resultados serão
enviados por email assim que o processamento terminar.

Ao carregar um CSV, siga estas orientações:

* Coloque os endereços de email na primeira coluna.
* Elimine quaisquer linhas em branco.
* Utilize um endereço por linha.
* Limite os ficheiros a um máximo de 50.000 linhas.

## Códigos de resposta e erro

Os erros são devolvidos em JSON com um código e descrição legível. Os códigos
comuns estão listados abaixo.

| Code | Type                  | Details                                                                   |
| ---- | --------------------- | ------------------------------------------------------------------------- |
| 200  | OK                    | Pedido concluído com sucesso.                                             |
| 400  | Bad request           | Pedido malformado ou inválido.                                            |
| 401  | Unauthorized          | Autenticação falhou — normalmente uma chave API em falta ou inválida.     |
| 422  | Quota reached         | Quota esgotada (por exemplo, créditos insuficientes em planos gratuitos). |
| 429  | Too many requests     | Limite de taxa excedido (planos gratuitos permitem até 1 pedido/segundo). |
| 500  | Internal server error | Erro inesperado do nosso lado.                                            |
| 503  | Service unavailable   | Serviço temporariamente indisponível.                                     |

## Outras notas

Nota sobre planos: todos os planos (gratuitos e pagos) executam as mesmas verificações, incluindo MX, SMTP e deteção catch-all.

Nota de faturação: cada email avaliado consome um crédito por pedido — independentemente do
resultado. Enviar um endereço inválido (por exemplo, "fda3346ds") ainda conta como um
crédito.