API REFERENCE

EmailChecker API

REST simples com Bearer auth. Resposta 100% compatível com mails.so — drop-in replacement: troque a base URL e a API key, mantenha o resto do código igual.

Começo rápido

Validação em lote

Você precisa de uma API key (crie em /dashboard → API keys) e o endpoint base https://app.emailchecker.email/api/v1.

# 1) Submete a lista
curl -X POST "https://app.emailchecker.email/api/v1/batch" \
  -H "Authorization: Bearer ec_live_..." \
  -H "Content-Type: application/json" \
  -d '{"emails":["joao@empresa.com.br","maria@empresa.com.br"]}'
# -> { "id": "...", "status": "pending" }

# 2) Consulta o resultado (faça poll até status == "completed")
curl "https://app.emailchecker.email/api/v1/batch/BATCH_ID" \
  -H "Authorization: Bearer ec_live_..."

Autenticação

Bearer API key

Inclua o header Authorization em toda requisição. O segredo aparece uma única vez ao criar a key — armazene em variável de ambiente, nunca no código.

Authorization: Bearer ec_live_<seu_segredo>

Resposta 401 = key ausente, inválida ou revogada.

POST /v1/batch

Submeter lote de emails

Envia até 100.000 emails de uma vez. Retorna um id usado pra pollar status. Validação é assíncrona — leva de segundos a minutos dependendo do volume.

curl -X POST https://app.emailchecker.email/api/v1/batch \
  -H "Authorization: Bearer ec_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["a@b.com", "c@d.com", "e@f.com"],
    "name": "lista-junho-2026"
  }'

Response 201

{
  "id": "9c2e8...",
  "name": "lista-junho-2026",
  "created_at": "2026-06-15T10:30:00.000Z",
  "user_id": "5b4c...",
  "size": 3
}

GET /v1/batch/:id

Buscar status do lote

Polling com backoff exponencial recomendado (3s → 6s → 12s → 30s max). Quando finished_at != null, o lote está pronto e o array emails vem populado.

curl https://app.emailchecker.email/api/v1/batch/9c2e8... \
  -H "Authorization: Bearer ec_live_..."

Response 200 (completed)

{
  "id": "9c2e8...",
  "status": "completed",
  "created_at": "2026-06-15T10:30:00.000Z",
  "finished_at": "2026-06-15T10:31:23.000Z",
  "size": 3,
  "emails": [
    {
      "email": "a@b.com",
      "result": "deliverable",
      "reason": "accepted_email",
      "score": 95,
      "isv_format": true,
      "isv_domain": true,
      "isv_mx": true,
      "isv_noblock": true,
      "isv_nocatchall": true,
      "isv_nogeneric": true,
      "is_free": false
    }
  ]
}

Status values

`pending`	Na fila, ainda não começou.
`processing`	Sendo validado. `processed_emails` incrementa em tempo real.
`completed`	Pronto. `emails` array vem populado.
`failed`	Erro. Veja `error_message`.

Rate limits

Cotas por API key

Janela	Limite default	Reset
Por minuto	300 requests	Sliding window
Por hora	10.000 requests	Sliding window

Headers de resposta: x-rate-limit-remaining-minute, x-rate-limit-remaining-hour. Quando estourar: 429 Too Many Requests + retry-after em segundos.

Limites maiores disponíveis pra contas enterprise — fala com a gente.

Códigos de erro

HTTP status reference

Status	Quando ocorre
`400`	Body / params inválidos.
`401`	API key ausente, inválida ou revogada.
`402`	Saldo insuficiente. Compre créditos em `/dashboard/comprar`.
`404`	Batch ID não encontrado (ou pertence a outra conta).
`429`	Rate limit excedido. Veja header `retry-after`.
`502`	Erro upstream (provider de validação). Crédito não cobrado.
`500`	Erro interno. Reporte pro suporte.

Migrando do mails.so

Drop-in replacement

Se você já usa mails.so, a migração é trivial. Os endpoints, params e response shapes são idênticos. Só troca:

Base URL https://api.mails.so/v1 → https://app.emailchecker.email/api/v1
Header de auth: x-mails-api-key → Authorization: Bearer ec_live_...
Pronto. Mesmos métodos, mesmas respostas.

Nosso router internamente delega gmail pro mails.so e o resto pro nosso engine SMTP próprio — accuracy igual ou melhor, custo menor.