Referência da API de verificação de email

Comece agora

Crie uma chave de teste em Chaves de API, mantenha-a no seu servidor e defina FAIRVALID_API_KEY e FAIRVALID_BASE_URL. As chaves de teste funcionam com endereços @example.com reservados. Elas não fazem chamadas ao provedor e não usam créditos.

curl -X POST "$FAIRVALID_BASE_URL/api/v1/jobs" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY" \
  -H "Idempotency-Key: my-import-2026-10-05" \
  -H "Content-Type: application/json" \
  -d '{"emails":["deliverable@example.com","pending@example.com"]}'

Para produção, crie uma chave Live com escopo submit e use /api/v1/jobs ou /api/v1/verifications. Adicione o escopo read para ler o estado e os resultados dos jobs.

Um novo job retorna HTTP 202 e um UUID job_id. Uma nova tentativa correspondente retorna HTTP 200 com o mesmo job. As respostas incluem version: v1, brand: FairValid e cabeçalhos no-store.

Chaves e limites de gastos

Passe Authorization: Bearer fv_live_… ou Bearer fv_test_… a partir de um servidor. Os segredos completos aparecem apenas uma vez. Chaves de produção podem ter os escopos submit, read e balance. Uma chave revogada deixa de aceitar novas solicitações. Chaves de teste acessam suas próprias tarefas simuladas.

O limite vitalício de uma chave Live considera os créditos já debitados mais os créditos reservados para identidades únicas aceitas. Ele não pode adicionar créditos ao espaço de trabalho. Uma nova solicitação acima do limite retorna HTTP 402 key_cap_reached sem criar um job nem uma reserva. Reduzir o limite bloqueia novos trabalhos; os trabalhos aceitos continuam.

Os jobs de produção usam a fila de verificação e o saldo de créditos do seu espaço de trabalho. Escopos de chave, limites de chave, acesso ao espaço de trabalho e limites de processamento continuam valendo. Os créditos do espaço de trabalho são reservados à medida que as verificações são admitidas para processamento; os resultados seguem as mesmas regras de débito e devolução do painel.

Durante uma pausa operacional, um novo envio em produção pode retornar HTTP 503 live_verification_unavailable sem reservar créditos. Tente novamente mais tarde com o mesmo Idempotency-Key.

Jobs e resultados

Método	Caminho	Finalidade
`POST`	`/api/v1/jobs`	Envie de 1 a 5.000 endereços em JSON, com até 2 MiB.
`POST`	`/api/v1/verifications`	Envie um endereço real ou use o simulador original de endereço único.
`GET`	`/api/v1/jobs/{id}`	Ler o estado atual e o resumo do job.
`GET`	`/api/v1/jobs/{id}/results`	Ler até 50 resultados e um cursor seguinte assinado.
`POST`	`/api/v1/jobs/{id}/cancel`	Solicitar cancelamento; o trabalho em andamento pode ser concluído.
`GET`	`/api/v1/balance`	Ler os créditos disponíveis e reservados do espaço de trabalho em produção.

curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"
curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID/results" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"

Passe next_cursor como parâmetro de consulta cursor. Ele mantém o filtro e a pesquisa originais. Os filtros são all, valid, invalid, catch_all, unknown, still_checking e not_checked. Os estados de resultados e créditos em produção correspondem ao snapshot do painel. O status da tarefa pode ser queued, running, paused, canceling, canceled ou completed. Tarefas de teste retornam estados determinísticos completed, pending, failed ou cancelled.

Erros e novas tentativas seguras

Envie uma Idempotency-Key de 8 a 128 caracteres permitidos (letras, dígitos, pontos, dois-pontos, sublinhados ou hífens) em cada envio de job e em cada envio de endereço único em produção. Repita uma resposta incerta com a mesma chave de API, a mesma chave de idempotência e o mesmo corpo normalizado. A repetição é restrita à chave de API; substituir essa credencial e reenviar pode criar outra execução. Reutilizar a chave de idempotência com um corpo alterado retorna HTTP 409 idempotency_conflict. Use uma nova chave apenas quando quiser uma nova execução, que pode consumir créditos.

HTTP 401 significa que a chave está ausente, foi revogada ou não tem o escopo necessário. HTTP 422 abrange endereços inválidos ou limites de lista. Jobs em massa de teste retornam HTTP 429 após 20 novos jobs por workspace por hora ou 100 a cada 30 dias; novas tentativas idênticas continuam retornando o job original. HTTP 503 significa que a solicitação está temporariamente indisponível; um 503 após um envio incerto não confirma que o job não existe, portanto tente novamente com a mesma chave de idempotência. Os erros contêm um código, uma mensagem e um ID de solicitação.

Sandbox gratuito

As chaves de teste aceitam somente estes endereços: deliverable@example.com, undeliverable@example.com, risky@example.com, unknown@example.com, pending@example.com e error@example.com. Elas simulam resultados válido, inválido, catch-all, desconhecido, pendente e indisponível. Jobs de teste em massa permitem consultar status e resultados, cancelar e reenviar sem afetar a verificação real nem o registro de créditos.

Tarefas em lote do sandbox e seus registros de repetição são mantidos por 30 dias. Após esse período, use uma nova chave de idempotência para um novo teste.

O simulador original de chave de teste /api/v1/verifications usa a versão de resposta anterior 2026-10-01 e campos em camelCase. Use /api/v1/jobs para o simulador em massa com versionamento.

Webhooks assinados

As funções Proprietário e Gerente configuram endpoints HTTPS para job.completed e job.canceled. Um ping de teste usa test.ping. Os payloads de jobs contêm um ID de evento estável, ID do job, estado, resumo sem endereços, contagens de créditos debitados e devolvidos e uma URL de resultados. Eles nunca incluem endereços de e-mail nem dados de provedores.

Leia FairValid-Webhook-Id, FairValid-Webhook-Timestamp e FairValid-Webhook-Signature. A assinatura é fv1= seguido do hex HMAC-SHA256 em minúsculas calculado sobre os bytes brutos de fv1\n{event ID}\n{Unix timestamp}\nseguidos imediatamente pelo corpo JSON bruto. Use uma comparação em tempo constante. Rejeite timestamps com diferença superior a cinco minutos em relação ao seu relógio e elimine duplicatas pelo ID do evento em armazenamento durável.

Retorne qualquer 2xx em até 10 segundos. Entregas com falha ou incertas são reenviadas até oito vezes com o mesmo ID de evento; consulte o histórico de 30 dias ou reenvie manualmente. Redirecionamentos e destinos privados são recusados. Após a rotação, novas tentativas usam o novo segredo. Mantenha o segredo anterior por 24 horas para verificar as assinaturas de tentativas em andamento.

Exemplos executáveis

O repositório inclui packages/contracts/examples/job.mjse packages/contracts/examples/webhook-receiver.mjs. Execute o exemplo de job com Node 22 e uma chave de teste. O receptor verifica os bytes exatos do corpo bruto e tanto o segredo atual quanto o anterior durante a rotação. Coloque HTTPS na frente dele e substitua o conjunto de IDs de eventos em memória por um armazenamento atômico durável antes de usá-lo em produção.

FAIRVALID_API_KEY=... FAIRVALID_BASE_URL=https://YOUR_FAIRVALID_HOST \
  node packages/contracts/examples/job.mjs