API de Validação de Email em Tempo Real: Guia do Dev

A validação de e-mail em tempo real verifica um endereço enquanto o usuário ainda está no seu formulário. Ela é executada nas poucas centenas de milissegundos entre “Enviar” e a tela seguinte e responde a uma pergunta: este endereço deve entrar no seu banco de dados? Uma API de validação de e-mail em tempo real toma essa decisão por você. Ela verifica a sintaxe, o domínio e seus registros MX, sinais de endereços descartáveis e de função, o comportamento de catch-all e, quando solicitado, a própria caixa de correio. Em seguida, retorna um resultado estruturado que seu código pode usar.

Este guia é para desenvolvedores que estão adicionando essa barreira a um formulário de cadastro, checkout ou captação de leads. Ele aborda o que as verificações fazem, como chamar uma API, como transformar cada status em uma decisão de produto e como manter a velocidade quando um servidor de e-mail está lento. Os exemplos usam a API de validação de e-mail da BillionVerify, mas as orientações de design se aplicam a qualquer provedor.

O Que É a Validação de Email em Tempo Real?

A validação de email em tempo real é uma verificação executada no momento em que um endereço é inserido, não dias depois, quando uma campanha é enviada. O usuário digita um endereço. Seu frontend ou backend o envia para uma API de verificação de email. A API responde com um status como valid, invalid ou catchall, além dos sinais por trás dele. Em seguida, sua aplicação permite o cadastro, bloqueia-o ou pede ao usuário que corrija um erro de digitação.

O ponto principal é o momento. Um erro de digitação como gmial.com não custa nada para corrigir enquanto o usuário ainda está no formulário. Depois que o email de boas-vindas retorna, o mesmo erro custa o cliente. Endereços inválidos também prejudicam sua reputação de remetente, porque cada hard bounce informa aos provedores de caixas de entrada que você envia mensagens para endereços não confirmados. A verificação de email em tempo real impede que eles avancem.

Ela também ajuda contra fraudes: uma verificação em tempo real pode sinalizar uma caixa de entrada descartável antes que a conta exista.

Validação de E-mails em Tempo Real vs. em Massa

Ambas as abordagens usam as mesmas verificações. Elas diferem em quando são executadas e quanto tempo têm.

• A validação em tempo real é executada em um endereço por vez, dentro de uma solicitação do usuário. Ela tem um limite de tempo rigoroso, geralmente bem inferior a um segundo, porque um formulário lento perde cadastros. Ela impede que dados incorretos entrem.
• A validação em massa é executada em uma lista inteira, em segundo plano. Pode levar minutos ou horas, e ninguém fica esperando diante de uma tela. Ela limpa dados que já estão no seu sistema, por exemplo, antes de uma grande campanha ou após uma importação para o CRM.

A maioria das equipes precisa de ambas. As verificações em tempo real mantêm os dados novos limpos, e uma verificação periódica em massa identifica endereços que se tornaram inválidos com o tempo, como os de funcionários que deixaram uma empresa. Para uma comparação mais detalhada, consulte validação de e-mails em tempo real vs. em massa.

O que uma verificação em tempo real realmente testa

Uma API de validação de email executa uma série de verificações, das mais simples às mais dispendiosas. Cada uma elimina um tipo diferente de endereço inválido.

Sintaxe

A primeira verificação é o formato. Há exatamente um @? A parte local é composta por caracteres permitidos? O domínio parece um domínio? A sintaxe rejeita lixo óbvio, como john@@example ou jane.example.com. É rápida e não requer uma chamada de rede. Mas uma sintaxe perfeita não diz nada sobre a existência da caixa de correio.

Registos de domínio e MX

Em seguida, a API procura o domínio no DNS. Um domínio sem registos MX não pode receber emails, portanto um endereço nesse domínio é inútil, por mais correto que pareça. Isto deteta domínios escritos incorretamente e domínios de empresas inativos. BillionVerify devolve os hosts MX encontrados em mx_records, e domain_suggestion pode conter uma correção provável quando o domínio parece um erro de digitação de um domínio comum.

Indicadores de endereços descartáveis, de função e de provedores gratuitos

Alguns endereços existem, mas ainda assim não são ideais para o seu produto:

• Endereços descartáveis vêm de serviços de caixas de entrada temporárias e normalmente deixam de funcionar em poucas horas. Consulte como funciona a deteção de emails descartáveis.
• Endereços de função, como info@ ou support@, são destinados a uma equipa, não a uma pessoa. Normalmente são entregáveis, mas tendem a gerar menos interação.
• Endereços de provedores gratuitos, como o Gmail, são normais para consumidores, mas vale a pena registá-los num formulário B2B.

A API comunica estes dados como flags (is_disposable, is_role, is_free) para que possa decidir de acordo com cada produto.

Domínios catch-all

Alguns servidores de email aceitam mensagens para qualquer endereço no respetivo domínio, exista ou não. Nestes domínios catch-all, uma verificação da caixa de correio não consegue provar que uma caixa de entrada específica existe. Um resultado catch-all não é um resultado negativo. Significa que a certeza é menor, pelo que a pontuação é mais importante do que o rótulo. A deteção de emails catch-all explica como isto funciona e por que é importante.

Verificação SMTP da caixa de correio

A verificação mais profunda pergunta ao servidor de email do destinatário, através de SMTP, se a caixa de correio aceitaria uma mensagem, sem enviar nenhuma. Encontra endereços em domínios reais que já não existem, como a caixa de entrada de um antigo funcionário. É também a etapa mais lenta, porque depende do servidor de outra pessoa. No BillionVerify, é controlada pelo parâmetro check_smtp. Se o omitir, a API executa a verificação SMTP; envie check_smtp: false para ignorá-la.

Reputação do domínio

BillionVerify também pode devolver um objeto domain_reputation com resultados de listas negras para o IP do servidor de email do domínio. Serve apenas para informação: não altera o estado, a pontuação nem o custo.

Como chamar uma API de validação de e-mail em tempo real

Com BillionVerify, uma única verificação em tempo real é uma solicitação HTTPS. A URL base é https://api.billionverify.com/v1, e sua chave de API deve ser enviada no cabeçalho BV-API-KEY. Mantenha essa chave no seu servidor. Nunca a inclua no código do navegador.

Aqui está uma solicitação mínima, baseada na referência da API:

curl -X POST https://api.billionverify.com/v1/verify/single \
  -H "BV-API-KEY: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","check_smtp":true}'

A solicitação aceita três parâmetros:

Uma resposta bem-sucedida envolve o resultado em um envelope padrão. Veja um exemplo abreviado para um endereço entregável:

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "email": "user@example.com",
    "status": "valid",
    "score": 0.95,
    "is_deliverable": true,
    "is_disposable": false,
    "is_catchall": false,
    "is_role": false,
    "is_free": false,
    "domain": "example.com",
    "mx_records": ["mail.example.com"],
    "check_smtp": true,
    "reason": "smtp_deliverable",
    "domain_suggestion": "",
    "response_time": 250,
    "credits_used": 1
  }
}

Se preferir um SDK, BillionVerify disponibiliza SDKs oficiais para Node.js, Python, TypeScript, Go, PHP e Java. No Node.js, npm install billionverify-sdk fornece um cliente com um método verify; em Python, o pacote é billionverify.

Lendo a Resposta: Status, Pontuação e Motivo

O campo status é o que orienta a maioria dos fluxos de código. Veja o que cada status significa e um padrão sensato para um formulário de cadastro:

O score fornece um sinal mais preciso entre 0 e 1. Como orientação geral, resultados valid têm pontuação de 0,85 a 1,0, catchall cerca de 0,55 a 0,75, unknown de 0,3 a 0,6, disposable 0,1 e invalid 0. Um resultado role mantém a pontuação da verificação subjacente. Você pode usar a pontuação para definir seu próprio limite para casos limítrofes, por exemplo, aceitando endereços catch-all apenas acima de determinada pontuação em um formulário de alto valor.

O campo reason explica o veredito. Um resultado invalid pode vir acompanhado de invalid_syntax, no_mx_records ou mailbox_not_found, e cada um indica uma mensagem diferente para o usuário. Um problema de sintaxe significa “verifique o formato”. Uma caixa de entrada ausente significa “esta caixa de entrada não existe”. A página de motivos da verificação lista todos os motivos e informa quais motivos unknown valem a pena tentar novamente.

Dois campos ajudam diretamente o usuário: domain_suggestion pode gerar uma sugestão como “Você quis dizer gmail.com?”, e is_disposable explica por que um endereço descartável foi recusado.

Projetando o fluxo de cadastro em torno de um orçamento de latência

A parte difícil é incluir a verificação em um formulário sem deixá-lo mais lento. Comece definindo um orçamento. Decida por quanto tempo você está disposto a manter o usuário aguardando, por exemplo, de 300 a 500 milissegundos ao enviar. Todo o resto parte desse número.

O texto do produto da BillionVerify indica resultados em cache em menos de 200 ms e uma verificação SMTP completa em 1–3 segundos, em média. Essa diferença deixa você com dois bons projetos:

1. Verificação completa com tempo limite. Chame a API com SMTP ativado e um tempo limite de 2–3 segundos. A maioria das respostas chega a tempo e fornece um valid ou invalid claro. Se o tempo limite for atingido, permita o cadastro e verifique novamente mais tarde.
2. Verificação rápida agora, verificação profunda depois. Chame a API com check_smtp: false. Isso resolve apenas casos claros: sintaxe inválida, um domínio sem registros MX e endereços descartáveis ou de função. Um endereço em um domínio ativo retorna como unknown com o motivo smtp_unverifiable, o que é esperado. Aceite-o e execute uma segunda chamada com SMTP ativado a partir de um job em segundo plano. Se a caixa de correio não existir, marque a conta e peça ao usuário para confirmar o endereço.

Alguns hábitos no frontend também ajudam:

• Valide ao sair do campo ou ao enviar, não a cada tecla pressionada. Verificar j, jo, joh desperdiça chamadas e créditos.
• Execute primeiro as verificações locais de sintaxe para economizar uma ida e volta em erros óbvios.
• Chame a API pelo seu backend. Seu servidor mantém a chave da API e registra o resultado; o navegador apenas exibe o resultado.

Para detalhes de UX, como texto, posicionamento de erros e quando mostrar uma dica, consulte verificação de email durante o cadastro.

Falhar Fechado ou Falhar Aberto? Lidando com Timeouts e Incertezas

O padrão que funciona para a maioria dos produtos é: falhar fechado diante de erros claros e falhar aberto diante da incerteza.

• Falhar fechado significa bloquear o cadastro. Faça isso quando a API indicar que o endereço é claramente inválido: invalid com invalid_syntax ou no_mx_records, ou um endereço disposable em um formulário no qual contas descartáveis causam problemas.
• Falhar aberto significa permitir o acesso do usuário e fazer o acompanhamento posteriormente. Faça isso quando a resposta for incerta: um status unknown, um domínio catch-all ou o seu próprio timeout sendo acionado antes de a API responder.

Por que não bloquear também os endereços incertos? Muitas pessoas reais estão por trás deles. Servidores de e-mail corporativos frequentemente aplicam greylisting ou limitam a taxa das verificações SMTP, portanto bloqueá-los custa cadastros reais. Aceite, marque o registro e verifique novamente mais tarde.

Defina um timeout no lado do cliente para sua chamada à API que corresponda ao seu orçamento de latência. Quando ele for acionado, trate o resultado como unknown: aceite, armazene uma sinalização e enfileire uma nova verificação em segundo plano. Tente novamente os resultados unknown mais tarde, em vez de fazê-lo dentro da solicitação.

Exemplo: Validar um Email no Cadastro em Node.js

O exemplo abaixo mostra a verificação rápida (design 2) em um handler de cadastro. Ele usa o endpoint REST documentado e os campos de resposta, um tempo limite e as regras de falha aberta ou fechada acima. Adapte os nomes ao seu framework.

const BLOCK = new Set(['invalid', 'disposable']);

async function checkEmail(email) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 400);

  try {
    const response = await fetch('https://api.billionverify.com/v1/verify/single', {
      method: 'POST',
      headers: {
        'BV-API-KEY': process.env.BV_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email, check_smtp: false }),
      signal: controller.signal,
    });
    const body = await response.json();
    if (!body.success) return { allow: true, recheck: true };

    const { status, reason, domain_suggestion } = body.data;
    if (BLOCK.has(status)) {
      return { allow: false, reason, suggestion: domain_suggestion };
    }
    return { allow: true, recheck: status === 'unknown' || status === 'catchall' };
  } catch {
    // Timeout or network error: fail open and re-check in the background.
    return { allow: true, recheck: true };
  } finally {
    clearTimeout(timer);
  }
}

Sem SMTP, a maioria dos endereços reais retorna unknown e recebe a flag recheck. Depois que a conta é salva, um job em segundo plano chama o mesmo endpoint com SMTP ativado para cada registro marcado com recheck. O tutorial de Node.js apresenta uma configuração mais completa, incluindo o SDK oficial. A mesma solicitação funciona em Python ou em qualquer linguagem com um cliente HTTP.

Limites de taxa, cache e custo

Uma verificação em tempo real ocorre no seu fluxo de cadastro, então os limites dela tornam-se os seus limites. Planeje-se para isso.

Limites de taxa. BillionVerify protege sua capacidade com limites por conta. Quando você atinge um deles, a API retorna HTTP 429 com o código 1003 e um cabeçalho Retry-After. Diminua o ritmo e tente novamente, mantendo sua própria regra de fail-open para que um limite nunca bloqueie um usuário real.

Cache. Os resultados são armazenados em cache, e é por isso que as verificações repetidas são rápidas. Verificar novamente um endereço que sua conta validou nas últimas 24 horas é gratuito. Use force_refresh: true somente quando realmente precisar de uma resposta atualizada, pois isso ignora o cache e é cobrado como uma nova verificação.

Custo. Uma única verificação normalmente usa 1 crédito, indicado em credits_used. Todo resultado unknown é gratuito, assim como as falhas de sintaxe. Valide ao enviar, em vez de validar a cada tecla pressionada, e não verifique novamente um endereço que você validou recentemente. BillionVerify oferece 20 créditos gratuitos todos os dias em que você faz login, até 600 por mês, o que é suficiente para criar e testar uma integração. Os pacotes de créditos pagos estão listados na página de preços.

Além do Formulário: Lotes, Arquivos e Webhooks

A validação em tempo real verifica novos endereços um por um. Para todo o resto, a mesma API oferece outros pontos de entrada:

• Lotes pequenos. POST /verify/bulk verifica até 50 endereços em uma única solicitação, o que é adequado para uma sincronização com um CRM ou uma tela de importação.
• Listas grandes. POST /verify/file aceita um arquivo CSV, TXT ou XLSX e o processa em segundo plano.
• Webhooks. Em vez de consultar repetidamente um trabalho de arquivo, registre um webhook para os eventos file.completed e file.failed. Consulte o guia sobre webhooks de verificação de e-mail para verificações de assinatura e novas tentativas.
• Verificações apenas de endereços descartáveis. POST /verify/disposable responde apenas à pergunta sobre ser descartável e não usa créditos.

Uma configuração comum: verificações em tempo real em cada formulário, um lote noturno para registros marcados como recheck e um trabalho de arquivo antes de grandes campanhas.

Checklist de Validação de Email em Tempo Real

Antes de publicar, percorra esta lista:

• A chave da API fica no servidor, nunca no navegador.
• A sintaxe é verificada localmente antes da chamada à API.
• O caminho da solicitação usa check_smtp: false e um timeout adequado ao seu orçamento de latência.
• invalid e disposable têm mensagens de erro claras e específicas.
• unknown, catchall e timeouts permitem prosseguir e são colocados em fila para uma nova verificação.
• domain_suggestion alimenta uma sugestão para corrigir erros de digitação.
• As respostas 429 recuam sem bloquear os usuários.
• Os resultados são armazenados com o registro do usuário, para que você possa medir as taxas de rejeição posteriormente.

Perguntas frequentes

O que é uma API de validação de e-mail em tempo real?

Uma API de validação de e-mail em tempo real verifica um único endereço de e-mail enquanto o usuário envia um formulário e retorna uma decisão em uma fração de segundo. Ela executa verificações de sintaxe, domínio, MX, descartável, função e catch-all, além de uma verificação opcional da caixa postal via SMTP, para que seu aplicativo possa aceitar, bloquear ou sinalizar o endereço antes que ele chegue ao banco de dados.

Qual é a diferença entre validação de e-mail em tempo real e validação em massa?

A validação de e-mail em tempo real verifica um endereço por vez dentro de uma solicitação do usuário e precisa responder rapidamente. A validação em massa verifica uma lista inteira em segundo plano e pode levar muito mais tempo. Use verificações em tempo real para manter novos dados limpos e verificações em massa para limpar os dados que você já possui.

Devo executar a verificação SMTP em cada cadastro?

Depende do seu limite de latência. A verificação SMTP é o que confirma uma caixa postal; sem ela, a maioria dos endereços reais retorna unknown. Se você puder esperar 2–3 segundos, execute-a no envio com um tempo limite. Caso contrário, execute a verificação rápida com check_smtp: false e faça a verificação SMTP em um processo em segundo plano.

O que devo fazer com resultados catch-all e unknown?

Aceite-os e verifique-os novamente mais tarde. Um domínio catch-all aceita qualquer endereço, portanto uma verificação da caixa postal não consegue provar que a caixa de entrada existe, e um resultado unknown significa que a verificação não pôde ser concluída. Bloquear esses usuários faz você perder cadastros reais; marcá-los e verificá-los novamente mantém seus dados limpos sem prejudicar a conversão.

Posso chamar a API de verificação de e-mail pelo navegador?

Não. Isso expõe sua chave de API. Chame a API pelo seu backend e retorne apenas a decisão.

Qual é a velocidade da verificação de e-mail em tempo real?

Com BillionVerify, os resultados armazenados em cache retornam em menos de 200 ms, e uma verificação SMTP completa leva em média de 1 a 3 segundos. Por isso, a verificação rápida sem SMTP deve ficar no caminho da solicitação, enquanto a verificação SMTP deve ser executada em segundo plano.

Quanto custa uma API de validação de e-mail?

No BillionVerify, uma verificação única normalmente usa 1 crédito, e todo resultado unknown é gratuito. Você recebe 20 créditos gratuitos todos os dias em que fizer login, até 600 por mês, e os pacotes de créditos pagos estão na página de preços. force_refresh ignora o cache e é cobrado como uma nova verificação.

Comece a Validar E-mails em Tempo Real

A validação de e-mails em tempo real significa menos rejeições, menos contas falsas e menos usuários perdidos por um erro de digitação. Faça uma verificação rápida no caminho da requisição, mova a verificação lenta para o segundo plano e permita que falhas claras sejam bloqueadas, enquanto resultados incertos passem. Crie uma conta gratuita no BillionVerify, obtenha uma chave de API e faça sua primeira chamada à API de validação de e-mail usando a documentação acima.