Verificação de e-mails em massa via API: um fluxo prático de jobs em lote

Verificação de e-mails em massa via API: um fluxo prático de jobs em lote

A pergunta: você tem uma grande lista de endereços no seu próprio sistema. Como enviá-la pela API da FairValid em lotes, tratar erros com segurança e ler os resultados sem perder o controle dos créditos?

Resposta curta: comece no sandbox com uma chave de teste. Em seguida, divida a lista em jobs de até 5.000 endereços e atribua a cada job sua própria chave de idempotência. Envie cada job com uma chave Live, verifique o status e percorra os resultados por resultado obtido. Trate verificações pendentes, falhas técnicas e resultados Desconhecido como três situações distintas.

Evidências verificadas em 13 de novembro de 2026, com base na referência da API, no guia de resultados e nas regras de créditos da FairValid.

Etapa 1: desenvolva primeiro usando o sandbox

A referência da API orienta a criar uma chave de teste em Chaves de API, mantê-la no seu servidor e configurá-la no seu ambiente junto com a URL base. As chaves de teste funcionam com endereços reservados no domínio example.com. Elas não fazem chamadas a provedores e não consomem créditos. As chaves de teste acessam seus próprios jobs simulados.

Os jobs de teste retornam estados determinísticos: concluído, pendente, com falha ou cancelado. Consulte a referência da API para ver os endereços exatos do sandbox e use-os para confirmar que seu código trata esses estados. Esses casos mostram apenas os resultados para os quais foram criados. Eles não cobrem todos os caminhos da sua integração, então revise seus próprios fluxos de erro separadamente.

Etapa 2: passe para uma chave Live com os escopos corretos

Para produção, a referência da API informa que você precisa de uma chave Live com o escopo submit para criar jobs. Adicione o escopo read para ler o estado e os resultados dos jobs. As chaves Live também podem ter o escopo balance. O segredo completo da chave aparece apenas uma vez, então armazene-o com segurança no seu servidor ao criá-la. Uma chave revogada deixa de aceitar novas requisições.

Os jobs Live usam a fila de verificação e o saldo de créditos do seu workspace. Escopos de chave, limites de chave, acesso ao workspace e limites de processamento continuam valendo. Uma chave Live não oferece acesso ilimitado.

Etapa 3: divida a lista e envie os jobs

Cada job aceita de 1 a 5.000 endereços em JSON, até 2 MiB. Veja uma abordagem prática:

1. Divida sua lista em blocos. Como exemplo, 12.000 endereços se tornariam três jobs de 5.000, 5.000 e 2.000.
2. Atribua a cada bloco sua própria Idempotency-Key estável e registre quais das suas linhas entraram em cada bloco. Manter esse mapeamento do seu lado facilita associar os resultados aos seus registros.
3. Envie para o endpoint de jobs. Um novo job retorna HTTP 202 com um job_id UUID. Uma nova tentativa correspondente retorna HTTP 200 com o mesmo job. Ou seja, você pode reenviar a mesma requisição com a mesma chave após um timeout e receber de volta o job existente.

Etapa 4: trate os dois erros que parecem iguais

Ambas as respostas podem bloquear um envio, mas significam coisas diferentes:

• HTTP 503 live_verification_unavailable pode ser retornado durante uma pausa operacional. Segundo a referência da API, isso acontece sem reter créditos. Tente novamente mais tarde com a mesma Idempotency-Key.
• HTTP 402 key_cap_reached significa que uma nova requisição ultrapassaria o limite de gastos vitalício da chave. Esse limite soma os créditos já cobrados e os créditos reservados para identidades únicas aceitas. Nenhum job ou retenção é criado. Um limite vitalício não se renova com o tempo, então esperar não resolve. Revise o limite da chave nas configurações de chaves de API ou use uma chave com limite restante suficiente para o trabalho. Um limite de chave também não adiciona créditos ao workspace. Ele apenas restringe quanto essa chave pode gastar.

Registre essas duas respostas separadamente dos erros de permissão e dos limites de processamento, para que a pessoa certa receba o alerta certo.

Etapa 5: acompanhe o estado do job e depois pagine os resultados

O endpoint do job retorna o estado atual e o resumo de um job. O status pode ser na fila, em execução, pausado, cancelando, cancelado ou concluído. Se você solicitar o cancelamento, o trabalho que já estiver em andamento ainda poderá ser concluído.

O endpoint de resultados retorna até 50 resultados por vez, junto com um next_cursor assinado. Passe esse valor como o parâmetro de consulta cursor. Ele mantém o filtro e a busca originais. Os filtros são all, valid, invalid, catch_all, unknown, still_checking e not_checked. Você pode usá-los para obter apenas as linhas que exigem uma decisão, como tudo o que estiver marcado como unknown.

Etapa 6: transforme resultados em decisões

O guia de resultados descreve os resultados como evidências, não como garantia de entrega:

• Válido indica uma verificação positiva utilizável. Nunca garante a entrega na caixa de entrada.
• Inválido significa que o endereço não passou na verificação.
• Catch-all significa que o domínio pode aceitar muitos endereços, então uma conclusão sobre a caixa de correio específica pode ser menos certa. Leia os detalhes antes de usar o endereço.
• Desconhecido significa que a verificação não conseguiu retornar uma resposta confiável.
• Ainda verificando significa que ainda não há resposta final. Continue consultando e não trate como Desconhecido.

Falhas técnicas e itens não processados são uma categoria à parte. As regras de créditos da FairValid dizem que eles não são reclassificados como Desconhecido.

Etapa 7: entenda as reservas de créditos

A referência da API informa que os créditos do workspace são reservados à medida que as verificações são admitidas para processamento. Os resultados seguem as mesmas regras de cobrança e devolução do painel. Segundo as regras de créditos, um resultado Válido ou Inválido concluído custa um crédito. Resultados Desconhecido e Catch-all não resolvidos não geram cobrança líquida: nenhum crédito é descontado ao final, porque os créditos retidos são liberados ou devolvidos. Pendente não é um resultado final. Falhas técnicas e trabalhos não processados também não geram cobrança líquida. Os créditos devolvidos mantêm as regras de lote e validade originais.

O endpoint de saldo informa os créditos disponíveis e retidos do workspace Live. Quando o campo free_allowance_held é true, a franquia gratuita está retida e não é contabilizada em available_credits nem em free_available. Os créditos pagos continuam disponíveis. A conta original recebe 300 créditos gratuitos todo mês na data de cadastro, e os créditos gratuitos não usados não são acumulados para o mês seguinte. Workspaces adicionais não recebem franquia gratuita extra. Os créditos gratuitos são usados primeiro, e os créditos pagos não expiram enquanto a conta estiver aberta.

Um checklist simples

• Teste com uma chave de teste e os casos de sandbox documentados.
• Use uma chave Live com os escopos submit e read e um limite adequado ao trabalho previsto.
• Mantenha cada bloco com 5.000 endereços ou menos, com uma chave de idempotência estável para cada bloco.
• Tente novamente um 503 mais tarde com a mesma chave. Não espere um 402 passar; ajuste o limite.
• Percorra os resultados com o cursor assinado, filtrando por resultado.
• Mantenha pendente, falha técnica e Desconhecido separados nos seus dados.

Se quiser experimentar este fluxo, você pode criar uma chave de teste e executar um job no sandbox sem consumir créditos antes do seu primeiro envio Live. A referência da API traz todos os detalhes dos endpoints.