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.
Table of Contents
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ço | result | reason | Sinais | did_you_mean |
|---|---|---|---|---|
| support@easyemailverification.com | valid | accepted_email | role | nenhum |
| x9k.eev.nobody.2026@gmail.com | invalid | rejected_email | free | nenhum |
| ana.souza.eev2026@gmial.com | invalid | invalid_mx_record | disposable | ana.souza.eev2026@gmail.com |
| eev.signup.test2026@mailinator.com | unknown | accept_all | disposable, free | nenhum |

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 API | Ação | O que o usuário vê |
|---|---|---|
| did_you_mean preenchido | Perguntar antes | “Você quis dizer ana.souza@gmail.com?” O endereço escolhido é verificado de novo |
| disposable verdadeiro | Rejeitar | “Use um e-mail permanente” |
| invalid | Rejeitar | “Este endereço parece não existir. Confira, por favor” |
| valid | Aceitar, não confirmado | O cadastro segue; o link de confirmação é enviado |
| unknown | Aceitar, não confirmado | O cadastro segue; o link de confirmação é enviado |
| API lenta, fora do ar ou sem créditos | Aceitar, não confirmado, verificar depois | Nada 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 aconteceu | O que significa | O que fazer |
|---|---|---|
| Timeout, erro de rede, 5xx | Temporário | Verificar depois, com intervalo crescente, poucas vezes |
| 429 | Requisições demais | Diminuir o ritmo; verificar depois |
| 400 ou 401 | Requisição ou chave errada | Corrigir a configuração; nada está sendo verificado |
| 402 | Sem créditos | Avisar quem paga a conta; não repetir |
| 200 com corpo ilegível | Inesperado | Registrar 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.
Posts relacionados
- Resultados da verificação de e-mail: o que significam valid, invalid, catch-all e unknown
- Como limpar uma lista de 50 mil contatos antes de uma campanha
- DMARC, DKIM e SPF: o que são e como configurar
Ver todos os posts do blog da Easy Email Verification
Ilustração de Storyset

