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 1 linha

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

curl -G "https://app.emailchecker.email/api/v1/validate" \
  -H "Authorization: Bearer ec_live_..." \
  --data-urlencode "email=joao@empresa.com.br"

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.

GET /v1/validate

Validar 1 email

Validação síncrona de um único email. Cobra 1 crédito por chamada — exceto quando result === "unknown" (refund automático).

Query parameters

Param	Tipo	Obrigatório	Descrição
`email`	string	Sim	Email pra validar (RFC 5322).

Response 200

{
  "data": {
    "id": "ec_a1b2c3d4...",
    "email": "joao@empresa.com.br",
    "username": "joao",
    "domain": "empresa.com.br",
    "mx_record": "mx1.empresa.com.br",
    "score": 95,
    "isv_format": true,
    "isv_domain": true,
    "isv_mx": true,
    "isv_noblock": true,
    "isv_nocatchall": true,
    "isv_nogeneric": true,
    "is_free": false,
    "result": "deliverable",
    "reason": "accepted_email"
  },
  "error": null
}

Result codes

Código	Significado	Cobra crédito?
`deliverable`	Caixa existe + servidor aceita.	Sim
`risky`	Catch-all, role-based (admin@, info@), domínio descartável temporário — pode bouncear.	Sim
`undeliverable`	Caixa não existe ou domínio sem MX.	Sim
`unknown`	Greylist, timeout, provider bloqueou probe.	Não (refund auto)

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.