Verificador de entregabilidade de email API

Escolha um tipo de tarefa por envio: email_check para entregabilidade ou email_avatar para avatares. Ambos usam o fluxo assíncrono em lote abaixo.

Verificador de entregabilidade (email_check)

Verifica se os endereços de email estão ativos e podem receber mensagens. Suporta apenas Gmail, Yandex, Mail.ru, iCloud, Outlook e Yahoo.

Verificador de avatar (email_avatar)

Verifica se os endereços de email têm um avatar público e retorna a URL. Suporta apenas Gmail, Yandex e Mail.ru.

Endereços fora dos provedores indicados e seus domínios alternativos compatíveis são excluídos do processamento, dos resultados e da cobrança.

Formato de entrada

Envie um arquivo de texto com um endereço de email compatível por linha.

user@gmail.com
another@yandex.com

Criar uma tarefa

POST https://api.numberchecker.ai/v1/tasks

curl --location 'https://api.numberchecker.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./input.txt"' \
--form 'task_type="email_check"'

Verificador de avatar (email_avatar)

curl --location 'https://api.numberchecker.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./input.txt"' \
--form 'task_type="email_avatar"'

A API retorna um ID de tarefa. Guarde esse ID e use-o para consultar o status.

Resposta do upload

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 5000,
  "estimated_amount": {
    "amount": "0.500000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

Verificar status da tarefa

POST https://api.numberchecker.ai/v1/gettasks

curl --location 'https://api.numberchecker.ai/v1/gettasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'task_id="d4g8o46p2jvh04o9uolg"'

Consulte até que status se torne exported. Não trate pending ou processing como resultado concluído.

Resposta em processamento

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 5000,
  "success": 2500,
  "failure": 0
}

Resposta exportada

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 5000,
  "success": 5000,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "2.000000",
    "currency": "USD"
  }
}

Campos do resultado

Verificador de entregabilidade (email_check)

Campo	Descrição	Exemplo
email	Endereço de e-mail do arquivo enviado.	user@gmail.com
activated	Indica se a entrada foi detectada como ativa ou registrada.	yes

Verificador de avatar (email_avatar)

Campo	Descrição	Exemplo
email	Endereço de e-mail de entrada do arquivo enviado.	user@gmail.com
activated	Indica se o endereço tem avatar público.	yes
avatar	URL da imagem do avatar quando disponível; vazio quando a conta usa o placeholder padrão.	https://…
name	Nome de exibição quando o provedor o expõe; caso contrário, vazio.	John Doe

Tratamento do arquivo de resultado

Baixe o arquivo por result_url somente após a tarefa ser exportada. Preserve os nomes das colunas retornados ao processar o arquivo.

Campos da resposta

Campo	Descrição
created_at	Data e hora de criação da tarefa.
updated_at	Data e hora da última atualização de status.
task_id	Identificador exclusivo da tarefa.
status	pending, processing, exported ou failed.
total	Total de valores de entrada processados.
success	Valores processados com sucesso.
failure	Valores cujo processamento falhou.
result_url	URL de download quando a tarefa é exportada.
actual_amount	Valor final liquidado, quando disponível.
estimated_amount	Valor estimado retornado ao criar a tarefa.

Códigos de status

Status	Descrição
200	Solicitação bem-sucedida.
202	Tarefa criada com sucesso e cobrança estimada aplicada.
400	Arquivo inválido, tipo de tarefa não compatível ou poucas entradas válidas.
401	Chave de API ausente ou inválida.
402	Saldo insuficiente.
403	Produto indisponível para sua conta (descontinuado ou restrito à lista de permissões); entre em contato com o suporte.
404	Tarefa não encontrada.
413	O arquivo enviado é grande demais.
500	Erro interno do servidor; tente novamente mais tarde.
503	Produto temporariamente indisponível (pausado para manutenção); nada é cobrado, tente novamente mais tarde.

Observações operacionais

• A tarefa é assíncrona; use o ID da tarefa para consultar o status.
• Verifique os limites de entrada do produto antes do upload.
• As linhas com falha aparecem no resultado exportado e são refletidas nos contadores.
• Os campos acima são baseados no sample atual e podem mudar quando o esquema de exportação upstream mudar.