PARA DESENVOLVEDORES

API de verificação de e-mails.

Use a verificação de um endereço em formulários ou tarefas assíncronas para listas de clientes. Mantenha seu provedor de e-mail atual.

COMECE COM UM ENDEREÇO

Sua primeira requisição.

Use o endpoint de demonstração gratuito sem chave. Ele tem limite de requisições e serve para experimentar o serviço.

curl -X POST https://api.zbounce.net/v1/demo \
  -H 'Content-Type: application/json' \
  -d '{"email":"hello@example.com"}'

Para verificações pagas, compre um pacote e use /v1/fast-verify com sua chave em X-API-Key. Não inclua chaves em URLs, repositórios de código ou ferramentas de análise.

curl -X POST https://api.zbounce.net/v1/fast-verify \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"email":"hello@example.com"}'

Exemplo em Python

import os, requests

response = requests.post(
    "https://api.zbounce.net/v1/fast-verify",
    headers={"X-API-Key": os.environ["ZBOUNCE_API_KEY"]},
    json={"email": "hello@example.com"},
    timeout=35,
)
response.raise_for_status()
print(response.json())

Exemplo em Node.js

const response = await fetch("https://api.zbounce.net/v1/fast-verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.ZBOUNCE_API_KEY,
  },
  body: JSON.stringify({ email: "hello@example.com" }),
  signal: AbortSignal.timeout(35000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

ENVIE UMA LISTA, RECEBA OS RESULTADOS

Verifique uma lista maior.

POST /v1/tasks

Envie até 10.000 endereços por tarefa. Guarde o ID da tarefa retornado e confira accepted, skipped e invalids: nem toda entrada é necessariamente colocada na fila. Duplicatas, endereços malformados e endereços suprimidos podem ser removidos, e um saldo baixo pode causar aceitação parcial.

curl -X POST https://api.zbounce.net/v1/tasks \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"emails":["hello@example.com","contact@example.org"]}'

Consulte o status e depois busque cada página de resultados. Uma resposta contendo apenas entradas inválidas pode ter um ID de tarefa vazio; não consulte esse ID.

curl "https://api.zbounce.net/v1/tasks/$TASK_ID" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

curl "https://api.zbounce.net/v1/tasks-results/$TASK_ID?page=1&per_page=100" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

Os resultados de tarefas concluídas são JSON. Continue buscando as páginas até recuperar toda a lista aceita. Para receber a conclusão automaticamente, informe um webhook com mode: "completed" ao criar a tarefa.

{
  "emails": ["hello@example.com"],
  "webhook": {
    "url": "https://your-app.example/hooks/verification",
    "mode": "completed",
    "secret": "YOUR_PRIVATE_WEBHOOK_SECRET"
  }
}

Consulte o esquema de configuração do webhook e de verificação de assinatura antes de ativá-lo em produção.

ENTENDA A RESPOSTA

Formato não significa existência.

São sinais distintos. Um endereço bem formado pode não existir, ser descartável ou impossível de confirmar.

Campo	Significado
`valid`	O endereço passou na validação de sintaxe. Isso, por si só, não confirma sua caixa de e-mail.
`exists`	Resultado da consulta à caixa. Interprete-o junto com os erros e os sinais de catch-all.
`disposable`	O domínio foi reconhecido como um provedor de e-mail temporário.
`accept_all`	O servidor aceita endereços arbitrários; a caixa específica não pode ser confirmada com segurança.
`error_category`	Explica uma falha ou um risco, como no_mx, risky ou um problema temporário no servidor.
`permanent_error`	Uma falha permanente foi retornada durante a verificação. Uma falha temporária não deve ser tratada como rejeição permanente.
`ttl`	Uma indicação de prazo para nova tentativa ou cache, em segundos, quando retornada.

A verificação não garante a entrega, não elimina reclamações nem comprova a propriedade de uma caixa de e-mail.

Conheça seu saldo.

GET /v1/me

curl https://api.zbounce.net/v1/me \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

A resposta inclui os créditos restantes, reservados e usados, o tipo de chave e a expiração. Uma verificação padrão usa um crédito; a filtragem e a cobrança reais dependem da rota e da aceitação da tarefa. Confira a resposta antes de considerar toda uma lista enviada como processada.

Uma resposta 429 indica que as requisições estão sendo limitadas. Aguarde antes de tentar novamente. Outros erros da API atual podem ser retornados como JSON ou texto; não interprete erros HTTP como resultados de verificação.

A especificação da verificação.

Baixar JSON OpenAPI

A especificação pública cobre demonstração, verificação rápida, tarefas, status das tarefas, resultados e saldo. Endpoints de envio e administração estão fora desta referência de verificação.

Precisa de ajuda para conectar sua plataforma? support@zbounce.net