Saltar para o conteúdo principal
GET
/
v1
API de validação de email
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"
  }
}

​
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: 
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: 
{
  "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"
  }
}

​
Parâmetros de pedido

​
api_key
string
obrigatório
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.
​
email
String
obrigatório
O endereço de email que pretende verificar.
​
auto_correct
Boolean
Flag opcional para desativar a autocorreção. Defina auto_correct=false para a desligar. Está ativada por predefinição.

​
Parâmetros de resposta

As respostas são devolvidas como JSON compacto e padronizado.
​
email
String
Repete o email enviado no pedido.
​
auto_correct
String
Correção sugerida quando é detetado um provável erro de escrita (por exemplo, johnsmith@gmial.com => johnsmith@gmail.com). Vazio se não houver sugestão.
​
deliverability
String
Avaliação da Cleariflow sobre se o endereço pode receber correio. Valores possíveis: DELIVERABLE, UNDELIVERABLE, UNKNOWN. Em planos pagos, 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. Em planos gratuitos o valor é UNKNOWN, exceto para endereços claramente não entregáveis (formato inválido ou domínio descartável).
​
quality_score
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.
​
is_valid_format
Boolean
true quando o endereço corresponde ao padrão local@domain.tld. Elementos em falta ou caracteres inválidos resultam em false.
​
is_free_email
Boolean
true se o domínio pertence a um fornecedor de email gratuito (por exemplo, Gmail, Yahoo).
​
is_disposable_email
Boolean
true se o domínio está na nossa lista de fornecedores de caixas de correio descartáveis/temporárias (por exemplo, Mailinator, Yopmail).
​
is_role_email
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@.
​
is_catchall_email
Boolean
true se o domínio está configurado como catch-all. Disponível apenas em planos pagos; devolve null/UNKNOWN em planos gratuitos.
​
is_mx_found
Boolean
true quando existem registos MX para o domínio. Disponível apenas em planos pagos; devolve null/UNKNOWN em planos gratuitos.
​
is_smtp_valid
Boolean
true se a verificação SMTP 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. Disponível apenas em planos pagos; devolve null/UNKNOWN em planos gratuitos.

​
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. 
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith@gmial.con
Uma resposta bem-sucedida tem este aspeto: 
{
  "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": null,
    "text": "UNKNOWN"
  },
  "is_mx_found": {
    "value": null,
    "text": "UNKNOWN"
  },
  "is_smtp_valid": {
    "value": null,
    "text": "UNKNOWN"
  }
}

​
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. 
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith
Uma resposta bem-sucedida tem este aspeto: 
{
  "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.
CodeTypeDetails
200OKPedido concluído com sucesso.
400Bad requestPedido malformado ou inválido.
401UnauthorizedAutenticação falhou — normalmente uma chave API em falta ou inválida.
422Quota reachedQuota esgotada (por exemplo, créditos insuficientes em planos gratuitos).
429Too many requestsLimite de taxa excedido (planos gratuitos permitem até 1 pedido/segundo).
500Internal server errorErro inesperado do nosso lado.
503Service unavailableServiço temporariamente indisponível.

​
Outras notas

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.