Documentação da API

Valide e-mails via HTTP: formato + domínio descartável + MX do domínio. Cada e-mail consome 1 crédito.

O que a API entrega — e o que ela não entrega

Ela confirma que o e-mail tem formato válido, que o domínio não é descartável(mailinator, 10minutemail…) e que o domínio tem servidor de e-mail (MX). Isso pega e-mails malformados, domínios falsos/com typo e caixas temporárias.

Ela não confirma se a caixa específica existe. Provedores como Gmail/Outlook aceitam qualquer endereço no SMTP (anti-harvesting), então qualquercoisa@gmail.com aparece como válido. Para garantir que a pessoa existe, use double opt-in(envie um link de confirmação).

status	Significa
valid	Formato ok + domínio recebe e-mail + não descartável
disposable	Domínio descartável/temporário
no_mx	Domínio não existe / não tem servidor de e-mail
invalid_format	Não é um e-mail bem-formado

Autenticação

Crie uma chave em Dashboard → API keys e envie no header Authorization: Bearer <sua_chave> (ou x-api-key).

Verificar um e-mail

POST /api/v1/verify

curl -X POST https://<host>/api/v1/verify \
  -H "Authorization: Bearer ek_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "email": "contato@mailinator.com" }'

Resposta

{
  "email": "contato@mailinator.com",
  "status": "disposable",
  "isValid": true,
  "isDisposable": true,
  "domain": "mailinator.com",
  "confidence": 100,
  "reason": "dominio_descartavel",
  "mxChecked": false,
  "hasMx": null,
  "creditsRemaining": 499
}

O MX é checado por padrão. Passe "mx": false para pular (mais rápido, mas não detecta domínio inexistente).

Verificar em batch

Envie um array em emails (até 1000 por requisição).

curl -X POST https://<host>/api/v1/verify \
  -H "Authorization: Bearer ek_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["a@gmail.com", "b@10minutemail.com"], "mx": false }'

Resposta

{
  "results": [
    { "email": "a@gmail.com", "isValid": true, "isDisposable": false, "domain": "gmail.com", "reason": null },
    { "email": "b@10minutemail.com", "isValid": true, "isDisposable": true, "domain": "10minutemail.com", "reason": "dominio_descartavel" }
  ],
  "summary": { "total": 2, "valid": 2, "invalid": 0, "disposable": 1, "creditsCharged": 2, "creditsRemaining": 497 }
}

Checagem de MX

Ligada por padrão: domínios sem servidor de e-mail (inexistentes/typo) voltam com status: "no_mx" e hasMx: false. Envie "mx": false para desligar.

Saldo de créditos

GET /api/v1/me

curl https://<host>/api/v1/me -H "Authorization: Bearer ek_live_xxx"
# → { "email": "...", "credits": 497, "totalChecks": 3, "memberSince": "..." }

Erros

HTTP	code	Quando
401	missing_api_key / invalid_api_key	Chave ausente, inválida ou revogada
400	invalid_body / invalid_json	Corpo malformado ou sem email/emails
402	insufficient_credits	Créditos insuficientes para a requisição
500	internal_error	Falha inesperada ao validar