Verificação de E-mail em Tempo Real

POST/v1/realtime/check/email

Verifique de forma síncrona um endereço de e-mail em um a dez produtos de e-mail de tempo real. O motor, o contrato de cobrança e o formato da resposta são idênticos aos do endpoint de telefone; apenas a série e o formato do identificador mudam.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
identifier	string	Sim	Um endereço de e-mail, por exemplo user@example.com.
country	string	Não	Deve ser omitido para e-mail. Enviar um código de país com um produto de e-mail é rejeitado.
product_ids	array<int>	Sim	Um array de 1 a 10 IDs de produtos de e-mail de tempo real.

País deve ficar vazio

E-mail não tem dimensão de país. country é opcional no endpoint de telefone, mas não é aceito aqui — uma requisição que o inclua falha na validação antes de qualquer envio ou cobrança.

Idempotência obrigatória

Idempotency-Key é obrigatório em cada chamada. Tentar novamente a mesma requisição com a mesma chave não cobra duas vezes; alterar o payload retorna 409. Consulte Idempotência e novas tentativas.

Escolha dos produtos

Produtos de e-mail e de telefone são séries diferentes e não podem ser combinados em uma requisição. Leia o id de uma entrada cujo mode seja realtime e cuja série seja e-mail em Produtos de tempo real, que é alimentado por GET /v1/products. Passar um slug nunca funciona aqui, e um ID de produto de telefone em uma chamada de e-mail é rejeitado como série incompatível.

Exemplo de Resposta

{
  "request_id": "b7d2a1c4-9f3e-4a1b-8c5d-2e6f7a8b9c0d",
  "identifier": "user@example.com",
  "series": "email",
  "status": "succeeded",
  "request_status": "completed",
  "replayed": false,
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "results": [
    {
      "product_id": 49,
      "product": "insemailvalid-rt",
      "result": "valid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-13T10:00:00Z",
      "error_code": null
    }
  ]
}

Os valores de product_id acima são exemplos — confirme os IDs atuais de produtos de e-mail em Produtos de tempo real antes de enviar uma requisição real. request_id é um UUID, e cached fica dentro de cada resultado, não no nível superior.

Exemplo com cURL

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/email" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"user@example.com","product_ids":[49]}'

Erros específicos de e-mail

HTTP	code	Significado
400	invalid_realtime_request	O endereço está malformado, country foi enviado, os IDs pertencem a outra série ou nenhum ID foi informado. Nada é enviado e nada é cobrado.
400	idempotency_key_required	Cabeçalho Idempotency-Key ausente.
402	insufficient_balance	O saldo não cobre a reserva; nenhum item é iniciado.
409	request_in_progress / idempotency_conflict	Mesma chave, ainda em execução, ou mesma chave com payload diferente.

Os demais códigos de status — 401, 403, 429, 503, 500 — se comportam exatamente como documentado no endpoint de telefone.