Referência da API de verificação de e-mail

Autenticação

POST /v1/email/validate aceita uma chave publicável restrita por origem através do cabeçalho X-Api-Key — o mesmo tipo de chave e o mesmo modelo de origens permitidas que GET /v1/geo. Todos os outros endpoints desta página (lote, tarefas de lista, verificação de registo) aceitam muitos endereços ou um IP arbitrário, pelo que exigem a sua chave secreta através de Authorization: Bearer e só devem ser chamados a partir do seu back-end; uma chave publicável recebe um 403 nesses endpoints.

Exemplo

curl https://api.watch-ip.com/v1/email/validate \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "John.Doe+news@Gmial.com"}'

{
  "email": "John.Doe+news@Gmial.com",
  "domain": "gmial.com",
  "syntaxValid": true,
  "isDisposable": false,
  "normalizedEmail": "john.doe+news@gmial.com",
  "canonicalEmail": "john.doe@gmial.com",
  "disposableSource": null,
  "isFreeProvider": false,
  "isRoleAccount": false,
  "didYouMean": "john.doe+news@gmail.com",
  "mx": {
    "status": "none",
    "host": null
  },
  "verdict": "reject",
  "reasons": [
    "no_mail_server",
    "typo_suspected"
  ]
}

Veredictos e códigos de motivo

Cada condição define um veredicto mínimo; prevalece a mais grave, e reasons enumera todas, da mais grave para a menos grave. Se um endereço de um fornecedor gratuito é aceitável fica ao seu critério — nunca altera o veredicto.

Verificação em lote

POST/v1/email/batch

Verifica 1 a 100 endereços num único pedido, com as mesmas verificações e a mesma forma de resultado que POST /v1/email/validate, um resultado por endereço pela ordem de entrada. Envie { "emails": [...] }. Os endereços do mesmo domínio partilham uma única consulta DNS. Conta um pedido por endereço no limite mensal do seu plano; um lote que excederia o limite é rejeitado na totalidade com 429 monthly_limit_exceeded. Para o limite de taxa por minuto, a chamada inteira conta como um único pedido. Apenas com chave secreta.

curl https://api.watch-ip.com/v1/email/batch \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user@gmail.com", "someone@mailinator.com"]}'

{
  "results": [
    { "email": "user@gmail.com", "verdict": "accept", "reasons": [], ... },
    { "email": "someone@mailinator.com", "isDisposable": true, "disposableSource": "list", "verdict": "reject", "reasons": ["disposable_domain"], ... }
  ]
}

Tarefas de lista de e-mails

POST/v1/email/jobs

Verifica até 100 000 endereços em segundo plano. Envie JSON { "emails": [...], "filename": "..." } ou um corpo text/csv de 10 MB no máximo: é utilizada a coluna com o cabeçalho email (também e-mail, email address, email_address ou mail, sem distinção entre maiúsculas e minúsculas), ou a primeira coluna se nenhum cabeçalho a indicar; os separadores vírgula, ponto e vírgula e tabulação são detetados. A tarefa é cobrada no momento da criação — um pedido por endereço distinto (correspondência exata), pelo que os duplicados são verificados mas cobrados uma vez — e uma lista que excederia o seu limite mensal é rejeitada na totalidade. Se parte de uma tarefa não puder ser processada após novas tentativas, a tarefa é marcada como failed e os créditos da parte não processada são devolvidos. Responde 202 com o objeto da tarefa. Apenas com chave secreta; as mesmas tarefas também podem ser carregadas e transferidas a partir da página Email lists do painel.

curl https://api.watch-ip.com/v1/email/jobs \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @newsletter.csv

{
  "id": "5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11",
  "status": "queued",
  "source": "api",
  "filename": null,
  "total": 12840,
  "credits": 12512,
  "processed": 0,
  "summary": null,
  "createdAt": "2026-09-28T10:00:00.000Z",
  "completedAt": null,
  "expiresAt": "2026-10-05T10:00:00.000Z"
}

Estado da tarefa

GET/v1/email/jobs/{id}

Devolve o mesmo objeto da tarefa. Consulte-o periodicamente até status ser completed; as consultas não são cobradas.

Resultados da tarefa

GET/v1/email/jobs/{id}/results

Transfere um CSV com uma linha por cada linha submetida, pela ordem de submissão — incluindo duplicados. Colunas: email, normalized_email, verdict, reasons, syntax_valid, is_disposable, disposable_source, is_free_provider, is_role_account, did_you_mean, mx_status, mx_host. reasons é separado por ponto e vírgula, as células vazias significam null e mx_status fica vazio para endereços sintaticamente inválidos (nada foi consultado). Um endereço inválido que comece por =, +, - ou @ é precedido de um apóstrofo para que as folhas de cálculo não o executem como fórmula. 409 até a tarefa estar concluída, 410 depois de expirar. A transferência não é cobrada.

curl https://api.watch-ip.com/v1/email/jobs/5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11/results \
  -H "Authorization: Bearer YOUR_SECRET_KEY" -o results.csv

Verificação de registo

POST/v1/signup/check

Pontua um registo a partir do endereço de e-mail e do IP numa única chamada, a partir do seu back-end quando o formulário de registo é submetido (um veredicto calculado no navegador pode ser falsificado). Envie { "email": "...", "ip": "...", "userAgent": "..." } — userAgent é opcional. A resposta contém o resultado completo da verificação de e-mail (email), o país e o ASN do IP e — nos planos que incluem dados de segurança — os seus indicadores de VPN/Tor/centro de dados/ameaça (ip), a idade do domínio do e-mail em dias segundo os dados públicos de registo (RDAP) (emailDomainAgeDays, null quando desconhecida e para os grandes fornecedores de consumo), uma pontuação de 0 a 100 (a soma dos pesos dos motivos abaixo, com máximo de 100) e um veredicto: reject a partir de 60, review a partir de 25, caso contrário accept. Num plano sem dados de segurança, ip.security é null, a pontuação usa apenas os sinais do e-mail e reasons inclui ip_security_unavailable. Conta como um pedido. Apenas com chave secreta.

curl https://api.watch-ip.com/v1/signup/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@new-startup.io", "ip": "203.0.113.1"}'

{
  "email": { "email": "jane@new-startup.io", "verdict": "accept", "reasons": [], ... },
  "ip": {
    "ip": "203.0.113.1",
    "country": "US",
    "asn": 64500,
    "asOrganization": "Example Hosting",
    "security": { "isTor": false, "isVpn": false, "isDatacenter": true, "isThreat": false, "isSanctionedNetwork": false }
  },
  "emailDomainAgeDays": 12,
  "score": 45,
  "verdict": "review",
  "reasons": ["new_domain", "ip_datacenter"]
}

Limites

Cada endereço verificado conta como um pedido no limite mensal partilhado do seu plano — uma verificação individual, cada endereço de um lote, cada endereço distinto de uma tarefa de lista — e uma verificação de registo é um pedido. Os lotes e as tarefas de lista são admitidos ou rejeitados na totalidade, nunca executados parcialmente. O limite de taxa por minuto conta chamadas HTTP, não itens: um lote de até 100 IP ou endereços de e-mail conta como um único pedido, enquanto cada item continua a contar separadamente para o limite mensal de pedidos. Os carregamentos e resultados das tarefas de lista são eliminados 7 dias após a criação da tarefa. As consultas DNS têm um orçamento de tempo curto: quando uma falha ou excede o tempo limite, o resultado degrada-se para mx.status unknown e motivo dns_unavailable em vez de um erro. Os dados de domínios descartáveis resultam da fusão de três listas de código aberto mantidas pela comunidade, atualizadas de poucas em poucas horas e complementadas com os servidores de correio observados a servir domínios listados — consulte fontes de dados. Um fornecedor descartável muito recente pode ainda não ser assinalado. Todas as verificações são ao nível do domínio e do endereço: nenhuma caixa de correio é contactada, pelo que nenhum resultado estabelece que uma caixa de correio existe, quem é o titular ou que o correio lá chegará.