Você decidiu adicionar verificação de e-mail à sua aplicação. Boa escolha — é a mudança de maior impacto que você pode fazer para melhorar a qualidade dos cadastros, reduzir devoluções e prevenir fraudes.
Este guia oferece código pronto para produção para integrar a verificação de e-mail em qualquer stack. Python, JavaScript, PHP, cURL — escolha sua linguagem e copie o código.
Por que a verificação no servidor é importante
Antes de escrevermos qualquer código, vamos deixar uma coisa clara: a validação de e-mail no lado do cliente não é suficiente.
// Isto NÃO é verificação — é apenas uma checagem de sintaxe
const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
// "thisdoesnotexist8472@gmail.com" → true (a sintaxe está correta, mas a caixa de e-mail não existe)
A expressão regular do lado do cliente detecta erros de formatação. Ela não informa se a caixa de e-mail realmente existe. Para isso, você precisa de verificação em nível SMTP — e isso exige uma chamada de API no servidor.
Obtendo sua chave de API
Primeiro, cadastre-se em email-validaton.com e copie sua chave de API no painel. Contas gratuitas recebem 100 verificações por mês.
Mantenha sua chave de API em sigilo — ela nunca deve aparecer em JavaScript do lado do cliente. Sempre chame a API de verificação a partir do seu backend.
Verificação de e-mail individual
Python
import requests
from typing import Optional
def verify_email(email: str, api_key: str) -> dict:
"""Verifica um único endereço de e-mail."""
resp = requests.get(
"https://email-validaton.com/api/v1/verify",
params={"email": email},
headers={"Authorization": f"Bearer {api_key}"},
timeout=15,
)
resp.raise_for_status()
return resp.json()
# Uso
result = verify_email("user@example.com", "YOUR_API_KEY")
print(f"Estado: {result['status']}")
print(f"Pontuação: {result['score']}/10")
print(f"Confiança: {result.get('confidence', 'N/A')}")
if result["status"] == "valid":
# Prosseguir com a criação da conta
create_user(email)
elif result["status"] in ("invalid", "disposable"):
# Rejeitar ou sinalizar
raise ValueError(f"Email inválido: {result['reason']}")
JavaScript (Node.js)
async function verifyEmail(email, apiKey) {
const url = new URL("https://email-validaton.com/api/v1/verify");
url.searchParams.set("email", email);
const resp = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
if (!resp.ok) throw new Error(`Erro de API: ${resp.status}`);
return resp.json();
}
// Utilização
const result = await verifyEmail("user@example.com", process.env.EV_API_KEY);
console.log(`Estado: ${result.status}, Pontuação: ${result.score}/10`);
if (result.status === "valid") {
await db.users.insert({ email, verified: true });
} else {
throw new Error(result.reason || "Falha na verificação do e-mail");
}
PHP
function verify_email(string $email, string $api_key): array {
$url = "https://email-validaton.com/api/v1/verify?email=" . urlencode($email);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer $api_key"],
CURLOPT_TIMEOUT => 15,
]);
$body = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($http_code !== 200) {
throw new RuntimeException("API retornou $http_code");
}
return json_decode($body, true);
}
// Utilização
$result = verify_email("user@example.com", getenv("EV_API_KEY"));
echo "Estado: {$result['status']}, Pontuação: {$result['score']}/10\n";
cURL (CLI / Scripts de Shell)
#!/bin/bash
API_KEY="your_api_key"
EMAIL="user@example.com"
curl -s -H "Authorization: Bearer $API_KEY" \
"https://email-validaton.com/api/v1/verify?email=$EMAIL" | python3 -m json.tool
Compreendendo a Resposta
Cada verificação retorna uma estrutura JSON consistente:
{
"email": "user@gmail.com",
"status": "valid",
"score": 9,
"confidence": "high",
"reason": "Caixa de correio existe e aceita e-mails",
"mx_server": "gmail-smtp-in.l.google.com",
"duration_ms": 287,
"disposable": false,
"role_account": false,
"free_provider": true
}
Principais Campos Explicados
| Campo | Valores | Significado |
|---|---|---|
status |
valid, invalid, catch_all, unknown, risky, disposable, over_quota, error |
O resultado da verificação |
score |
0–10 | Pontuação composta de qualidade. 8+ = excelente, 5-7 = moderada, <5 = arriscada |
confidence |
high, medium, low |
Quão confiável é o resultado |
reason |
String legível por humanos | Por que o status foi atribuído |
disposable |
booleano | Endereço de e-mail temporário |
role_account |
booleano | info@, support@, admin@, etc. |
free_provider |
booleano | Gmail, Yahoo, Outlook, etc. |
Padrões de Integração
Padrão 1: Validação de Formulário de Registo (o mais comum)
@app.route("/register", methods=["POST"])
def register():
email = request.form["email"]
password = request.form["password"]
# 1. Verificação de sintaxe (rápida, local)
if "@" not in email ou "." not in email.split("@")[-1]:
return jsonify({"error": "Formato de e-mail inválido"}), 400
# 2. Verificação SMTP (chamada à API)
try:
result = verify_email(email, current_app.config["EV_API_KEY"])
except requests.RequestException:
# A API está indisponível — não bloquear as inscrições, apenas marcar para revisão
create_user(email, password, flags=["unverified"])
return redirect(url_for("dashboard"))
# 3. Lógica de negócio com base no resultado
if result["status"] == "valid":
create_user(email, password, verified=True)
return redirect(url_for("bem-vindo"))
if result["status"] == "disposable":
return jsonify({
"error": "Por favor, use um endereço de e-mail permanente"
}), 400
if result["status"] == "invalid":
return jsonify({
"error": "Este endereço de e-mail não parece existir"
}), 400
# Catch-all, desconhecido, arriscado — permitir, mas sinalizar
create_user(email, password, flags=[result["status"]])
return redirect(url_for("bem-vindo"))
Padrão 2: Verificação Assíncrona (Não Bloqueante)
Em produção em escala, você não quer que os usuários esperem pela chamada da API:
import threading
def verify_async(email: str, api_key: str, user_id: int):
"""Verifica o e-mail em segundo plano e atualiza o registro do usuário."""
try:
result = verify_email(email, api_key)
db.users.update(user_id, {
"email_status": result["status"],
"email_score": result["score"],
"verified_at": datetime.utcnow(),
})
except Exceção as e:
logger.error(f"Falha na verificação em segundo plano para {user_id}: {e}")
# No seu handler de registro:
user = create_user(email, password)
threading.Thread(
alvo=verify_async,
args=(email, api_key, user.id),
daemon=True,
).start()
Padrão 3: Processamento de Listas em Massa
Para limpar listas grandes através do endpoint de upload em massa:
import requests
import time
def bulk_verify(file_path: str, api_key: str) -> str:
"""Envia um arquivo para verificação em massa. Retorna o ID da tarefa."""
with open(file_path, "rb") as f:
resp = requests.post(
"https://email-validaton.com/api/v1/bulk",
files={"file": f},
headers={"Authorization": f"Bearer {api_key}"},
)
return resp.json()["job_id"]
def wait_for_results(job_id: str, api_key: str, poll_sec: int = 5):
"""Consulta até a tarefa em massa ser concluída e, em seguida, baixa os resultados."""
while True:
resp = requests.get(
f"https://email-validaton.com/api/v1/bulk/status/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
)
data = resp.json()
if data["status"] in ("completed", "failed", "cancelled"):
return data
time.sleep(poll_sec)
# Uso
job_id = bulk_verify("my_list.csv", API_KEY)
result = wait_for_results(job_id, API_KEY)
# Descarregar o ficheiro de resultados
download = requests.get(result["result_url"])
Tratamento de Erros e Boas Práticas
Tratamento de Timeouts
A API de verificação normalmente responde em 200-800 ms. Defina um timeout de 10-15 segundos para lidar com problemas de rede de forma adequada.
Limite de Requisições
As contas gratuitas estão limitadas a 100/dia. Os planos pagos variam entre 5.000 e 500.000/mês. A API devolve 429 Too Many Requests when you exceed your limit.
Lógica de Repetição
Para falhas transitórias (erros de rede, 503), repita até 3 vezes com backoff exponencial:
import time
from requests.exceptions import RequestException
def verify_with_retry(email, api_key, max_retries=3):
for attempt in range(max_retries):
try:
return verify_email(email, api_key)
except RequestException:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt)
Não Bloquear Registos em Caso de Falha da API
Se a API de verificação estiver temporariamente indisponível, não bloqueie o registo do utilizador.Em vez disso:
1. Permita o registo e marque a conta como "pendente de verificação"
2. Execute a verificação de forma assíncrona quando a API voltar a funcionar
3. Notifique o utilizador se o seu e-mail for inválido posteriormente
Bloquear os registos durante uma falha da API faz perder utilizadores reais.
Conclusão
A verificação de e-mail não é opcional para aplicações em produção. Os e-mails inválidos causam devoluções, os e-mails descartáveis permitem abusos e as listas não verificadas prejudicam a sua reputação de remetente.
Os padrões de integração neste guia cobrem os casos de utilização mais comuns. Copie o código, adapte-o à sua stack e comece a verificar todos os e-mails que entram no seu sistema.
Pronto para integrar? Obtenha a sua chave de API gratuita — 100 verificações incluídas.
