Detete e-mails de registo descartáveis, mal escritos ou sem servidor de correio

Dê ao seu formulário de registo uma verificação antecipada de cada endereço: sintaxe, domínios descartáveis/temporários conhecidos, se o domínio tem sequer um servidor de correio, gralhas prováveis e endereços funcionais — devolvida como um veredicto accept, review ou reject com os respetivos motivos. Chame POST /v1/email/validate a partir do JavaScript do seu formulário, ou verifique listas em lote a partir do seu back-end ou do painel.

Ler a referência de verificação de e-mail Ver o fluxo de prevenção de abuso de registo →

Pedido e autenticação

Envie um corpo JSON { "email": "user@example.com" } para POST /v1/email/validate com uma chave publicável restrita por origem no cabeçalho X-Api-Key — o mesmo tipo de chave e o mesmo modelo de origens permitidas que GET /v1/geo, pelo que é seguro chamá-lo diretamente a partir de um formulário de registo enquanto o visitante escreve ou ao submeter. Do lado do servidor, a sua chave secreta desbloqueia POST /v1/email/batch (até 100 endereços por pedido), tarefas de lista assíncronas até 100 000 endereços (API ou página Email lists do painel, com CSV de entrada e de saída) e POST /v1/signup/check, que combina a verificação de e-mail com os indicadores de rede do IP que se regista numa única pontuação.

Leia o veredicto e depois os motivos

verdict é o resultado mais grave: reject para sintaxe inválida, um domínio inexistente, um domínio sem servidor de correio ou um domínio descartável; review para uma gralha suspeita, um endereço funcional como info@, um domínio com apenas um servidor de correio implícito ou uma consulta DNS que não foi concluída; caso contrário, accept. reasons enumera todas as condições verificadas, para que o seu formulário possa mostrar uma mensagem específica — e, quando didYouMean estiver preenchido, ofereça a correção em vez de um erro.

Quando chamar

Chame-o ao sair do campo ou ao submeter, e não a cada tecla — verificar um endereço ainda incompleto a cada carácter acrescenta pedidos sem sinal útil e pode fazer piscar uma mensagem de erro enquanto o visitante ainda está a escrever. Cada chamada conta como um pedido.

Se o pedido falhar

Falhe em aberto: deixe o registo prosseguir se o pedido de rede falhar ou exceder o tempo limite, em vez de bloquear todos os visitantes por causa de uma falha do lado do cliente. Do lado do servidor, uma consulta DNS que falha é indicada com o motivo dns_unavailable (veredicto review), nunca como erro ou reject. Preserve o que o visitante já escreveu para que uma verificação falhada nunca lhe custe o que introduziu.

Como são detetados os domínios descartáveis

Os domínios descartáveis/temporários conhecidos resultam da fusão de três listas de código aberto mantidas pela comunidade (consulte fontes de dados), atualizadas de poucas em poucas horas, com uma lista de permissões para que uma entrada errada na origem nunca possa assinalar um grande fornecedor. Os subdomínios de um domínio listado também correspondem. Os novos domínios descartáveis que ainda não constam de nenhuma lista são frequentemente detetados pelo seu servidor de correio: os serviços descartáveis apontam muitos domínios para os mesmos poucos anfitriões de correio, e um domínio cujo servidor de correio é conhecido por servir domínios listados é assinalado com disposableSource: mx_host. Um fornecedor muito recente num novo servidor de correio pode ainda não ser assinalado.

Utilização e quota

Cada endereço verificado conta como um pedido no limite mensal partilhado do seu plano — uma verificação individual, cada endereço de um lote, cada endereço distinto de uma tarefa de lista — juntamente com o resto do seu tráfego e com o mesmo limite de taxa por minuto. Não existe um plano nem um preço de e-mail separado. O limite de taxa por minuto conta chamadas HTTP, não itens: um lote de até 100 IP ou endereços de e-mail conta como um único pedido, enquanto cada item continua a contar separadamente para o limite mensal de pedidos.

O que isto não verifica

Cada verificação é ao nível do domínio ou do endereço. A Watch-IP nunca contacta o servidor de correio do destinatário, pelo que um resultado não estabelece que a caixa de correio existe, que o correio lá chegará nem que pertence à pessoa que se regista. Um veredicto accept significa «nenhum problema encontrado», não um endereço com funcionamento confirmado — para isso, utilize um e-mail de confirmação.

Campos de resposta

syntaxValid: Se o endereço é sintaticamente válido.
isDisposable: Se o domínio corresponde a um fornecedor descartável/temporário conhecido, diretamente, através de um domínio pai ou através do seu servidor de correio. Sempre false quando syntaxValid é false.
disposableSource: list, parent_domain ou mx_host — porque é que isDisposable é true; caso contrário, null.
mx: O estado do servidor de correio do domínio (found, implicit, none, null_mx, no_domain ou unknown) e o seu anfitrião MX principal.
didYouMean: Uma correção provável de gralha, como gmial.com → gmail.com, ou null.
isRoleAccount / isFreeProvider: Indicadores de endereço funcional (admin@, info@, noreply@…) e de fornecedor de correio para consumidores. O de fornecedor gratuito é apenas informativo.
normalizedEmail / canonicalEmail: O endereço em minúsculas e o mesmo sem +tags (nem pontos do Gmail) para detetar contas duplicadas.
verdict / reasons: accept, review ou reject, mais todos os códigos de motivo verificados — consulte a referência para a lista completa.

Agir com base no veredicto

JavaScript do formulário de registo

async function checkEmail(email) {
  const response = await fetch('https://api.watch-ip.com/v1/email/validate', {
    method: 'POST',
    headers: { 'X-Api-Key': 'YOUR_PUBLISHABLE_KEY', 'Content-Type': 'application/json' },
    body: JSON.stringify({ email }),
  });
  if (!response.ok) return { state: 'unknown' }; // falhar em aberto — não bloqueie o registo por um erro de rede

  const result = await response.json();
  if (result.didYouMean) return { state: 'suggest', suggestion: result.didYouMean };
  if (result.verdict === 'reject') return { state: 'reject', reasons: result.reasons };
  return { state: 'ok' }; // accept ou review: deixe o registo prosseguir e assinale-o no seu back-end
}

Mostre uma mensagem distinta por motivo — invalid_syntax, disposable_domain e no_mail_server exigem ações corretivas diferentes por parte do visitante — e ofereça didYouMean como correção com um clique.

Perguntas frequentes

Verifica se a caixa de correio existe?

Não. Verifica a sintaxe, as listas e os registos DNS de servidor de correio do domínio, e a forma do endereço. Nunca contacta o servidor de correio nem confirma que a caixa de correio individual é real — um reject por no_mail_server diz respeito a todo o domínio.

Um accept prova que o e-mail funciona?

Não. accept significa que nenhuma das verificações encontrou um problema, não que o endereço vai garantidamente receber correio ou que pertence à pessoa que se regista. Utilize um e-mail de confirmação quando precisar disso.

Os utilizadores podem contornar a validação no navegador?

Sim. Qualquer verificação do lado do navegador, incluindo esta, pode ser contornada desativando o JavaScript ou chamando diretamente o seu endpoint de registo. Aplique no seu back-end qualquer decisão que importe — POST /v1/signup/check foi concebido para isso.

Posso limpar uma lista existente?

Sim. Carregue um CSV na página Email lists do painel, ou submeta até 100 000 endereços a POST /v1/email/jobs com a sua chave secreta e, em seguida, transfira um CSV de resultados com um veredicto e motivos por linha. Os duplicados são cobrados uma vez, e os carregamentos e resultados são eliminados ao fim de 7 dias.

Como são contados os pedidos?

Um pedido por endereço verificado, contabilizado no limite mensal partilhado do seu plano. Os duplicados numa tarefa de lista contam uma vez; uma verificação de registo conta como um pedido.