API de validação de e-mail no cadastro: exemplos em Python, PHP e JavaScript

Uma expressão regular aceita ana.souza@gmial.com sem reclamar. O seu banco de dados também, o CRM também, e a sequência de boas-vindas também, até o primeiro bounce. Uma API de validação de e-mail pega esse endereço enquanto a pessoa ainda está na tela de cadastro, que é o único momento em que dá para pedir que ela corrija.

Este post mostra como chamar a API da Easy Email Verification a partir do código de cadastro em Python, PHP e JavaScript, com resultados de um teste real. A maior parte trata do que os tutoriais pulam: o que o seu código deve fazer com cada resposta, e o que fazer quando a API não responde.

O que a API de validação de e-mail confere e a regex não

Checar o formato só diz que o endereço tem cara de endereço. A API da Easy Email Verification vai além: confere se o domínio existe e tem servidor de e-mail, conversa com esse servidor para saber se a caixa existe e sinaliza endereços de provedores descartáveis, endereços genéricos como contato@ e domínios que aceitam tudo (catch-all).

Dá para testar agora, sem conta, com a chave pública de sandbox:

curl --get "https://api.easyemailverification.com/v1/verify" \
  --data-urlencode "email=valid@sandbox.easyemailverification.com" \
  -H "X-API-Key: eev_sandbox_key"

Com a sua chave, a requisição é a mesma. Mande a chave no cabeçalho X-API-Key, e não na URL: URLs acabam em logs de servidor, proxies e ferramentas de monitoramento de erros; cabeçalhos, em geral, não.

Teste real: quatro cadastros, quatro respostas diferentes

Em 20 de novembro passamos cinco endereços pela API, o tipo de mistura que qualquer formulário de cadastro recebe numa semana. Quatro estão abaixo. O quinto é de uma empresa real, então ficou de fora. As respostas JSON completas ficam guardadas junto com este post.

EndereçoresultreasonSinaisdid_you_mean
support@easyemailverification.comvalidaccepted_emailrolenenhum
x9k.eev.nobody.2026@gmail.cominvalidrejected_emailfreenenhum
ana.souza.eev2026@gmial.cominvalidinvalid_mx_recorddisposableana.souza.eev2026@gmail.com
eev.signup.test2026@mailinator.comunknownaccept_alldisposable, freenenhum
Teste da API de validação de e-mail: respostas JSON para quatro endereços de cadastro

Dois desses merecem atenção.

O erro de digitação no Gmail volta como invalid, com o endereço corrigido no did_you_mean. Rejeitar de cara seria perder uma pessoa real que errou uma letra. Perguntar “Você quis dizer gmail.com?” mantém essa pessoa. Mas a sugestão é uma pergunta, não uma aprovação: se a pessoa aceita, o endereço corrigido passa pela API de novo; se ela insiste em gmial.com, ele continua inválido.

O endereço do Mailinator é a armadilha. O Mailinator aceita mensagem para qualquer caixa, então o resultado é unknown com reason accept_all, e não invalid. Se o seu código lê só o result, uma caixa descartável entra direto na sua base. Quem pega é o sinal disposable.

Validar não é confirmar

Uma API de validação de e-mail diz se é provável que a caixa exista. Ela não tem como dizer que a pessoa preenchendo o formulário é dona dessa caixa. Só um link de confirmação faz isso.

Por isso, trate as duas coisas como etapas separadas. A validação decide se o cadastro segue. A confirmação decide se o endereço é confiável: até o link ser clicado, a conta existe, mas o e-mail fica como não confirmado e ainda não deve entrar nas suas campanhas.

O que fazer com cada resultado no cadastro

Esta é a regra que usamos e recomendamos para um formulário de cadastro comum. Ajuste ao seu risco, mas decida de propósito; não deixe que a regra seja o que a primeira versão do código fez por acaso.

Resposta da APIAçãoO que o usuário vê
did_you_mean preenchidoPerguntar antes“Você quis dizer ana.souza@gmail.com?” O endereço escolhido é verificado de novo
disposable verdadeiroRejeitar“Use um e-mail permanente”
invalidRejeitar“Este endereço parece não existir. Confira, por favor”
validAceitar, não confirmadoO cadastro segue; o link de confirmação é enviado
unknownAceitar, não confirmadoO cadastro segue; o link de confirmação é enviado
API lenta, fora do ar ou sem créditosAceitar, não confirmado, verificar depoisNada de diferente

Nossa opinião sobre o unknown: não bloqueie no cadastro. Domínios corporativos catch-all, servidores que demoram a responder e provedores que recusam a verificação temporariamente caem ali, e muitos desses são clientes de verdade. Mas aceitar o cadastro não é o mesmo que confiar no endereço. Para unknown, a API devolve safe_to_send: false porque não conseguiu confirmar que a caixa existe, e permitir o cadastro não muda esse resultado. Mantenha o endereço fora das campanhas até a pessoa confirmar o e-mail e a sua própria política de envio permitir.

Ou seja, são duas regras, não uma. A regra de cadastro (a tabela acima) decide quem ganha conta. A regra de envio decide quem recebe as suas campanhas, e é nela que o safe_to_send entra.

Endereços genéricos (contato@, vendas@) são um sinal, não um veredito. Numa newsletter para consumidor final dá para recusar; numa ferramenta B2B, o contato@ muitas vezes é o único e-mail que uma pequena empresa tem.

O caminho curto: bibliotecas oficiais

Se você prefere não escrever a chamada HTTP, existem bibliotecas oficiais para Node.js, Python e PHP (npm install easyemailverification, pip install easyemailverification, composer require easyemailverification/php-sdk). Todas leem a chave de EEV_API_KEY e têm uma função decide() que transforma o resultado em accept, reject, suggest ou review. Os detalhes estão na página de bibliotecas.

Os exemplos abaixo usam HTTP puro, para você ver cada decisão e adaptar. Eles devolvem a ação e a sugestão, quando houver. Timeout, erro de rede, código de erro HTTP e resposta que não seja o JSON esperado viram pending, em vez de exceção.

API de validação de e-mail em Python

Usa a biblioteca requests e o módulo logging, que já vem com o Python.

import logging
import os

import requests

API_URL = "https://api.easyemailverification.com/v1/verify"
API_KEY = os.environ["EEV_API_KEY"]  # nunca escreva a chave no código
log = logging.getLogger("signup")


def check_signup_email(email):
    """Devolve {"action": "accept" | "reject" | "pending", "suggestion": str | None}."""
    domain = email.rpartition("@")[2]  # registre o domínio, nunca o endereço completo
    try:
        resp = requests.get(
            API_URL,
            params={"email": email},
            headers={"X-API-Key": API_KEY},
            timeout=10,
        )
    except requests.RequestException as exc:
        log.warning("EEV fora do ar (%s), domain=%s", type(exc).__name__, domain)
        return {"action": "pending", "suggestion": None}

    if resp.status_code != 200:
        level = logging.ERROR if resp.status_code in (400, 401, 402) else logging.WARNING
        log.log(level, "EEV HTTP %s, domain=%s", resp.status_code, domain)
        return {"action": "pending", "suggestion": None}

    try:
        r = resp.json()
        result = r["result"]
    except (ValueError, KeyError, TypeError):
        log.error("EEV resposta inesperada, domain=%s", domain)
        return {"action": "pending", "suggestion": None}

    suggestion = r.get("did_you_mean") or None
    if r.get("disposable") or result == "invalid":
        action = "reject"
    elif result in ("valid", "unknown"):
        action = "accept"  # o endereço ainda não foi confirmado
    else:
        log.error("EEV result inesperado %r, domain=%s", result, domain)
        action = "pending"
    return {"action": action, "suggestion": suggestion}

Com os quatro endereços do teste, ela devolve accept, reject, reject com a sugestão gmail.com, e reject.

Exemplo em PHP com cURL

Não precisa de biblioteca, só da extensão cURL, que vem em quase toda instalação de PHP.

<?php
const API_URL = 'https://api.easyemailverification.com/v1/verify';

/** Devolve ['action' => 'accept'|'reject'|'pending', 'suggestion' => ?string] */
function check_signup_email(string $email): array
{
    $domain = substr(strrchr($email, '@') ?: '', 1); // registre o domínio, nunca o endereço completo
    $ch = curl_init(API_URL . '?' . http_build_query(['email' => $email]));
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ['X-API-Key: ' . getenv('EEV_API_KEY')],
        CURLOPT_TIMEOUT        => 10,
    ]);
    $body   = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($body === false || $status !== 200) {
        // 0 = timeout ou erro de rede; 400, 401 e 402 precisam de alguém para agir
        error_log("EEV HTTP $status, domain=$domain");
        return ['action' => 'pending', 'suggestion' => null];
    }

    $r = json_decode($body, true);
    if (!is_array($r) || !isset($r['result'])) {
        error_log("EEV resposta inesperada, domain=$domain");
        return ['action' => 'pending', 'suggestion' => null];
    }

    $suggestion = $r['did_you_mean'] ?? '' ?: null;
    if (!empty($r['disposable']) || $r['result'] === 'invalid') {
        return ['action' => 'reject', 'suggestion' => $suggestion];
    }
    if (in_array($r['result'], ['valid', 'unknown'], true)) {
        return ['action' => 'accept', 'suggestion' => $suggestion]; // ainda não confirmado
    }
    error_log("EEV result inesperado, domain=$domain");
    return ['action' => 'pending', 'suggestion' => null];
}

Exemplo em JavaScript (Node.js)

A partir do Node 18 o fetch já vem embutido. Este código roda no seu servidor, nunca na página.

const API_URL = "https://api.easyemailverification.com/v1/verify";
const API_KEY = process.env.EEV_API_KEY; // só no servidor, nunca no navegador

// Devolve { action: "accept" | "reject" | "pending", suggestion: string | null }
export async function checkSignupEmail(email) {
  const domain = email.split("@").pop(); // registre o domínio, nunca o endereço completo
  const url = new URL(API_URL);
  url.searchParams.set("email", email);

  let r;
  try {
    const resp = await fetch(url, {
      headers: { "X-API-Key": API_KEY },
      signal: AbortSignal.timeout(10000),
    });
    if (!resp.ok) {
      const log = [400, 401, 402].includes(resp.status) ? console.error : console.warn;
      log(`EEV HTTP ${resp.status}, domain=${domain}`);
      return { action: "pending", suggestion: null };
    }
    r = await resp.json();
  } catch (err) {
    // timeout, erro de rede ou corpo que não é JSON
    console.warn(`EEV falhou (${err.name}), domain=${domain}`);
    return { action: "pending", suggestion: null };
  }

  const suggestion = r?.did_you_mean || null;
  if (r?.disposable || r?.result === "invalid") return { action: "reject", suggestion };
  if (r?.result === "valid" || r?.result === "unknown") {
    return { action: "accept", suggestion }; // o endereço ainda não foi confirmado
  }
  console.error(`EEV resposta inesperada, domain=${domain}`);
  return { action: "pending", suggestion: null };
}

Ligando tudo na rota de cadastro

A função só decide. É na rota de cadastro que o usuário vê o resultado. Abaixo, uma rota mínima em Express que usa a função de Node.js acima; a mesma ordem funciona em Flask, Laravel ou qualquer outro framework.

A rota mostra o fluxo de decisão, não um cadastro completo. As funções createUser() e sendConfirmationLink() no fim são simulações: nada é gravado e nenhum e-mail é enviado. Troque as duas pelo seu banco de dados e pelo seu envio de e-mail antes de usar em produção.

import express from "express";
import { checkSignupEmail } from "./signup_check.mjs";

const app = express();
app.use(express.json());

app.post("/signup", async (req, res) => {
  const email = String(req.body.email ?? "").trim();

  // 0. Checagem local barata: não gaste crédito com campo vazio ou quebrado.
  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) || email.length > 254) {
    return res.status(422).json({ error: "Digite um e-mail válido." });
  }

  const { action, suggestion } = await checkSignupEmail(email);

  // 1. Provável erro de digitação: pergunte antes. Se o usuário aceitar,
  //    o formulário envia o endereço corrigido e ele é verificado de novo.
  if (suggestion && !req.body.keepTypedEmail) {
    return res.status(409).json({ suggestion });
  }
  // 2. Inválido ou descartável, mesmo que o usuário insista no que digitou.
  if (action === "reject") {
    return res.status(422).json({ error: "Use um e-mail válido e permanente." });
  }
  // 3. accept ou pending: cria a conta com o e-mail ainda não confirmado.
  try {
    const user = await createUser(email, { emailConfirmed: false, recheck: action === "pending" });
    await sendConfirmationLink(user);
    res.status(201).json({ id: user.id });
  } catch (err) {
    console.error(`cadastro falhou depois da verificação: ${err.name}`);
    res.status(500).json({ error: "Não foi possível criar a conta. Tente de novo." });
  }
});

// SIMULAÇÃO: nada é gravado e nenhum e-mail é enviado.
// Troque estas duas funções pelo seu banco de dados e pelo seu envio de e-mail antes de usar em produção.
async function createUser(email, flags) { return { id: Date.now(), email, ...flags }; }
async function sendConfirmationLink(user) {}

app.listen(3000);

A ordem importa. Primeiro vem uma checagem local de formato, para que um campo vazio ou quebrado não gaste crédito. Depois a sugestão, para que um erro de digitação receba uma pergunta gentil em vez de uma mensagem de erro, e só então a rejeição, para que insistir em gmial.com não coloque o endereço para dentro. Se gravar a conta falhar depois de uma verificação bem-sucedida, o usuário recebe um erro simples e pode tentar de novo.

Nunca chame a API pelo navegador

Dá vontade de verificar no momento em que a pessoa sai do campo de e-mail, direto da página. Não faça isso com a sua chave de API: qualquer um abre as ferramentas de desenvolvedor do navegador, copia a chave e gasta os seus créditos. Chame o seu próprio backend, e deixe o backend chamar a API.

Se você quer mesmo a verificação dentro do formulário sem escrever código de servidor, use o widget de formulário. Ele tem uma chave própria, que só funciona no domínio autorizado e tem limite por visitante.

Quando a API não responde

A verificação conversa com o servidor de e-mail de outra empresa, então pode levar alguns segundos, e de vez em quando esse servidor não responde. A documentação da API recomenda um timeout de cerca de 30 segundos. Num formulário de cadastro usamos 10: ninguém espera 30 segundos num botão “Criar conta”.

Quando a chamada falha, os exemplos devolvem pending e deixam a pessoa entrar com o e-mail não confirmado. Um cadastro perdido custa mais que um endereço ruim de vez em quando, e os pendentes podem ser verificados depois numa rotina diária de verificação de e-mail em massa. Mas nem toda falha é igual:

O que aconteceuO que significaO que fazer
Timeout, erro de rede, 5xxTemporárioVerificar depois, com intervalo crescente, poucas vezes
429Requisições demaisDiminuir o ritmo; verificar depois
400 ou 401Requisição ou chave erradaCorrigir a configuração; nada está sendo verificado
402Sem créditosAvisar quem paga a conta; não repetir
200 com corpo ilegívelInesperadoRegistrar no log e tratar como pending

Por isso os exemplos registram 400, 401 e 402 como erro: se uma chave for revogada, todo cadastro vira pending sem barulho, e só o log vai mostrar. Registre o domínio, não o endereço completo, e nunca a chave.

Mais um detalhe sobre repetir a chamada: uma requisição que estourou o tempo pode já ter consumido crédito. Não repita em loop.

Teste sem gastar créditos

A chave de sandbox eev_sandbox_key funciona sem conta. Endereços em sandbox.easyemailverification.com devolvem respostas fixas: valid@, invalid@, unknown@, disposable@, catchall@ e role@ cobrem cada caso, typo@gmial.com devolve uma sugestão em did_you_mean, e quota@ e ratelimit@ devolvem os erros 402 e 429 para você testar também o caminho de falha. Rodamos os três exemplos acima com os nove: as mesmas respostas em Python, PHP e Node.js, com catchall@ e unknown@ aceitos como não confirmados, disposable@ recusado e os erros 402 e 429 registrados como pending. A lista completa de campos e erros está na documentação da API.

Perguntas frequentes

Quanto custa cada verificação?

Um crédito por endereço, e toda conta nova começa com 200 créditos grátis. Respostas unknown por timeout, erro ou bloqueio não são cobradas; as de catch-all são. Os preços estão na página da API.

Dá para validar vários endereços numa requisição?

Sim. Um POST no mesmo endpoint /v1/verify aceita até 50 endereços. Para listas de milhares, use o envio de arquivo em massa.

Devo validar a cada tecla digitada?

Não. Valide uma vez, quando o formulário for enviado, no seu servidor. Cada chamada consome um crédito e conversa com um servidor de e-mail; validar endereços pela metade desperdiça os dois.

Próximo passo

Rode o comando curl acima com a chave de sandbox e depois encaixe um dos exemplos na sua rota de cadastro. Quando quiser testar endereços reais, crie uma conta grátis e gere uma chave em Configurações da API. Para ver a resposta completa de um endereço antes de escrever qualquer código, use o verificador de e-mail grátis.

Criar conta grátis

Posts relacionados

Ver todos os posts do blog da Easy Email Verification

Ilustração de Storyset

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *

Rolar para cima