API de validação de e-mail

Visão geral

Todas as rotas ficam em https://api.mailchecker.dev/v1, respondem JSON em UTF-8 (exceto o download de resultados, em CSV) e exigem uma chave de API. Crie e revogue chaves no portal, em API keys; a chave completa aparece uma única vez.

A especificação OpenAPI 3.1 fica em https://api.mailchecker.dev/v1/openapi.json.

Autenticação

Envie a chave (mc_live_…) no cabeçalho Authorization: Bearer ou, para compatibilidade com o ZeroBounce, no parâmetro api_key da query. Prefira o cabeçalho: URLs costumam parar em logs.

# Cabeçalho (recomendado)
curl "https://api.mailchecker.dev/v1/credits" \
  -H "Authorization: Bearer mc_live_…"

# Ou na query, como no ZeroBounce
curl "https://api.mailchecker.dev/v1/credits?api_key=mc_live_…"

Endpoints

Verifica um endereço e devolve um Verdict. Parâmetro: email (obrigatório).

curl "https://api.mailchecker.dev/v1/validate?email=joao.silva@gmail.com" \
  -H "Authorization: Bearer mc_live_…"

{
  "address": "joao.silva@gmail.com",
  "status": "valid",
  "sub_status": "",
  "account": "joao.silva",
  "domain": "gmail.com",
  "did_you_mean": null,
  "free_email": true,
  "role_based": false,
  "disposable": false,
  "mx_found": true,
  "mx_record": "gmail-smtp-in.l.google.com",
  "smtp_provider": "google",
  "domain_age_days": 11318,
  "processed_at": "2026-11-07T12:34:56Z",
  "domain_score": 100,
  "domain_reasons": ["dmarc_none", "free_email"]
}

Corpo {"emails": [...]} com até 100 endereços. Devolve um Verdict por endereço e o custo total do lote; repetidos no mesmo lote não são cobrados.

curl -X POST "https://api.mailchecker.dev/v1/validate/batch" \
  -H "Authorization: Bearer mc_live_…" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["ana@empresa.com.br", "joao@gmial.com"]}'

{
  "results": [ /* um Verdict por endereço */ ],
  "cost": 2
}

Multipart com file (CSV ou XLSX, até 1 milhão de linhas), column (opcional: a coluna do e-mail) e name. Responde 201 com a lista no estado queued.

curl -X POST "https://api.mailchecker.dev/v1/files" \
  -H "Authorization: Bearer mc_live_…" \
  -F "file=@clientes.csv" -F "column=2" -F "name=Clientes novembro"

O estado da lista: uploaded, queued, running, done, failed ou cancelled, com os totais por status. Consulte de tempos em tempos até done.

{
  "id": "0193f1c2-…",
  "name": "Clientes novembro",
  "original_filename": "clientes.csv",
  "state": "running",
  "total": 12480, "unique_count": 12011, "duplicates": 469,
  "processed": 8300,
  "counts": { "valid": 6904, "invalid": 811, "catch-all": 402, "unknown": 183 },
  "cost": 8117,
  "error": null,
  "created_at": "2026-11-07T12:00:00Z", "started_at": "2026-11-07T12:00:02Z", "finished_at": null
}

O resultado em CSV. filter=all (padrão) traz tudo, valid só os válidos, no_invalid tudo menos os inválidos.

Saldo do time: {"balance": 1840}.

Uso diário por status, com datas AAAA-MM-DD: {"days": [{"day", "status", "count", "cost"}]}.

O resultado (Verdict)

Cada endereço verificado vira um objeto com estes campos:

Motivos da reputação do domínio

Cada motivo tira pontos de 100; os marcados "sem penalidade" são só informativos. Domínios de e-mail grátis (Gmail, Outlook…) só perdem pontos por blocklist.

Status e sub-status

O mesmo vocabulário do ZeroBounce.

Erros

Todo erro vem no mesmo formato: um código estável em error, uma mensagem legível em message e, nos erros de validação, os campos com problema em fields.

{
  "error": "validation",
  "message": "O campo email é obrigatório.",
  "fields": { "email": ["obrigatório"] }
}

Limites

• Requisições: limite por chave, em balde de fichas (token bucket); o padrão é 10 requisições por segundo. Precisa de mais? Fale com a gente.
• Lote síncrono: até 100 endereços por POST /v1/validate/batch.
• Arquivos: CSV ou XLSX com até 1 milhão de linhas.
• Retenção: resultados ficam disponíveis por 30 dias e depois são apagados (LGPD).

Cobrança

O débito acontece junto com a gravação do resultado: 1 crédito por endereço, inclusive catch-all. unknown custa 0 e endereços repetidos na mesma lista ou lote também. Consulte o saldo em GET /v1/credits e veja os preços.

Migrando do ZeroBounce

Desenhamos a API para que a migração seja curta:

• Mesmos status e sub-status, com os mesmos nomes.
• Mesmos nomes nos campos principais do resultado (address, status, sub_status, account, domain, did_you_mean, free_email, mx_found, mx_record, smtp_provider, domain_age_days, processed_at).
• Chave aceita em ?api_key=.
• Mesmas regras de cobrança: unknown e duplicatas não cobram.

# ZeroBounce
GET https://api.zerobounce.net/v2/validate?api_key=SUA_CHAVE&email=ana@empresa.com.br

# mailchecker: troque a base e a chave
GET https://api.mailchecker.dev/v1/validate?api_key=mc_live_…&email=ana@empresa.com.br

Veja também a comparação completa.