Verifique e-mails no cadastro com uma função serverless

O bounce mais barato é aquele que nunca entra na sua lista. Verificar um endereço no momento em que a pessoa o digita — em uma função serverless por trás do seu formulário de cadastro — barra erros de digitação, domínios inexistentes e endereços descartáveis já na porta de entrada, em vez de você pagar para limpá-los depois e levar o prejuízo de entregabilidade nesse meio-tempo. Este guia mostra o padrão com um route serverless funcional.

A resposta curta#

Coloque a verificação em uma função no servidor que seu formulário de cadastro chame: ela guarda sua chave de API, chama POST /verify e age com base no veredito local imediato — rejeite undeliverable, ofereça a correção did_you_mean, marque disposable e deixe todo o resto passar. Duas regras fazem toda a diferença: nunca chame a API pelo navegador (a chave precisa ficar no servidor) e nunca bloqueie um cadastro quando a API estiver lenta ou fora do ar (fail open).

Por que no cadastro, e não depois#

Verificar na captura é prevenção; limpar uma lista é remediação, e a prevenção vence em todos os aspectos. Um erro de digitação pego ainda no teclado é um assinante salvo com uma correção de uma linha. Um domínio inexistente rejeitado no cadastro nunca vira um hard bounce que abala sua taxa de bounce. Um endereço descartável barrado na porta nunca dilui suas métricas nem sua fatura. O mesmo endereço encontrado numa limpeza de lista três meses depois já custou a você um envio, um bounce e um pedacinho da reputação de remetente.

O padrão#

Três peças em movimento:

1. O formulário envia o endereço para o seu próprio endpoint — nunca direto para a API de verificação, porque isso exporia sua chave.
2. Uma função serverless guarda a chave em uma variável de ambiente, chama POST /verify e transforma o resultado em uma decisão.
3. Sua lógica de cadastro age com base na decisão: rejeitar, sugerir uma correção ou aceitar.

Um route serverless#

Aqui está ele como um Route Handler do App Router do Next.js, que faz deploy como uma função serverless na Vercel. A chave fica em QUALISEND_API_KEY; o cliente nunca a vê:

// app/api/validate-email/route.ts
import { NextResponse } from "next/server";

const BASE = "https://app.qualisend.com/api/v1";

export async function POST(req: Request) {
  const { email } = await req.json();

  try {
    const res = await fetch(`${BASE}/verify`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.QUALISEND_API_KEY!}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email }),
      signal: AbortSignal.timeout(4000), // don't let a slow probe stall signup
    });

    // On any API error, fail open — a real user must not be blocked by our outage.
    if (!res.ok) return NextResponse.json({ ok: true, degraded: true });

    const { result } = await res.json();

    if (result.status === "undeliverable") {
      return NextResponse.json({
        ok: false,
        reason: result.reason,          // invalid_email | invalid_domain | rejected_email
        suggestion: result.did_you_mean, // e.g. "jane@gmail.com"
      });
    }
    if (result.sub_flags?.disposable) {
      return NextResponse.json({ ok: false, reason: "disposable" });
    }

    // deliverable, risky, or unknown — accept, but pass along a typo suggestion if any
    return NextResponse.json({ ok: true, status: result.status, suggestion: result.did_you_mean });
  } catch {
    return NextResponse.json({ ok: true, degraded: true }); // timeout or network error → fail open
  }
}

Guarde a chave com as ferramentas de variáveis de ambiente da sua plataforma (vercel env add QUALISEND_API_KEY) e ela é injetada em tempo de execução — nunca empacotada no cliente.

Agindo com base no veredito#

O result imediato é o veredito local (sintaxe, DNS, descartável, role, erro de digitação), que é exatamente o que você quer no cadastro — rápido e suficiente para decidir:

Fail open, sempre#

O ponto inegociável: se a chamada de verificação der erro, estourar o timeout ou retornar algo diferente de 2xx, deixe o cadastro passar. Uma API de verificação é um filtro de qualidade, não uma barreira de autenticação, e bloquear um cliente pagante por causa de uma indisponibilidade passageira é um desfecho muito pior do que deixar entrar um endereço questionável. Tanto o branch !res.ok quanto o catch acima retornam ok: true exatamente por esse motivo. Em vez disso, registre os cadastros degradados e pegue-os na sua próxima limpeza de lista.

Perguntas frequentes#

Verificar no cadastro deixa o formulário mais lento?#

Quase nada, se você fizer do jeito certo. O veredito local retorna rápido, e o timeout de 4 segundos acima limita o pior caso — passado esse ponto, você adota o fail open e aceita o cadastro mesmo assim. Os usuários recebem correções do tipo "você quis dizer" quase instantâneas; eles nunca ficam esperando um servidor de e-mail lento, porque você está agindo com base no resultado local imediato, e não fazendo polling da sondagem SMTP.

Devo bloquear endereços de e-mail descartáveis no cadastro?#

Depende do seu produto. Para um serviço pago ou sensível à reputação, bloquear os descartáveis logo na porta vale a pena — quem os usa nunca teve intenção de ouvir você de novo. Para um cadastro de consumidor com pouca fricção, marcá-los para revisão posterior pode ser melhor do que adicionar fricção. O route acima os rejeita; afrouxe para apenas uma marcação se isso encaixar no seu funil.

Preciso do resultado completo confirmado por SMTP no cadastro?#

Geralmente não. O veredito local imediato pega a maior parte dos cadastros ruins — erros de digitação, domínios inexistentes, descartáveis — sem nenhuma espera. Reserve o resultado completo confirmado por SMTP (via GET /jobs ou um job em lote) para a limpeza de listas, onde a latência não importa e pegar cada caixa de correio inativa importa.

Como mantenho minha chave de API em segredo?#

Chame a API de verificação apenas a partir de código no servidor — uma função serverless, um route handler ou o backend — e guarde a chave em uma variável de ambiente, nunca no JavaScript do lado do cliente. Se a chave for parar no bundle do navegador, ela está no lugar errado.

Pronto para colocar em prática? O plano gratuito inclui 100 créditos para testar o fluxo, e a referência da API traz o endpoint /verify com exemplos prontos para copiar e colar em sete linguagens.