Verificare le email all'iscrizione con una funzione serverless

Il bounce più economico è quello che non entra mai nella tua lista. Verificare un indirizzo nel momento in cui viene digitato, con una funzione serverless dietro il modulo di iscrizione, ferma all'ingresso errori di battitura, domini morti e indirizzi usa e getta, invece di costringerti a pagare per eliminarli più tardi e a subire nel frattempo il danno alla deliverability. Questa guida mostra lo schema con una route serverless funzionante.

In breve#

Metti la verifica in una funzione lato server chiamata dal modulo di iscrizione: custodisce la tua chiave API, chiama POST /verify e agisce sull'esito locale immediato. Rifiuta undeliverable, proponi la correzione did_you_mean, segnala disposable e lascia passare tutto il resto. Tutto dipende da due regole: non chiamare mai l'API dal browser (la chiave deve restare sul server) e non bloccare mai un'iscrizione quando l'API è lenta o non disponibile (fail open).

Perché all'iscrizione e non dopo#

La verifica al punto di acquisizione è prevenzione; la pulizia di una lista è un rimedio, e la prevenzione vince su tutta la linea. Un errore di battitura intercettato mentre si digita è un iscritto salvato con una correzione di una riga. Un dominio morto rifiutato all'iscrizione non diventa mai un hard bounce che intacca il tuo tasso di bounce. Un indirizzo usa e getta bloccato all'ingresso non diluisce mai le tue metriche né gonfia la tua fattura. Lo stesso indirizzo trovato durante una pulizia della lista tre mesi dopo ti è già costato un invio, un bounce e un po' di reputazione del mittente.

Lo schema#

Tre componenti:

1. Il modulo invia l'indirizzo al tuo endpoint, mai direttamente all'API di verifica, perché esporrebbe la tua chiave.
2. Una funzione serverless custodisce la chiave in una variabile d'ambiente, chiama POST /verify e trasforma il risultato in una decisione.
3. La tua logica di iscrizione agisce sulla decisione: rifiuta, suggerisce una correzione o accetta.

Una route serverless#

Eccola come Route Handler del Next.js App Router, che su Vercel viene distribuito come funzione serverless. La chiave sta in QUALISEND_API_KEY e il client non la vede mai:

// 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
  }
}

Salva la chiave con gli strumenti per le variabili d'ambiente della tua piattaforma (vercel env add QUALISEND_API_KEY): viene iniettata in fase di esecuzione e non finisce mai nel bundle del client.

Agire in base all'esito#

Il result immediato è l'esito locale (sintassi, DNS, usa e getta, indirizzo generico, errore di battitura), ed è esattamente ciò che ti serve all'iscrizione, perché è veloce e basta per decidere:

Fail open, sempre#

L'unico punto non negoziabile: se la chiamata di verifica va in errore, va in timeout o restituisce una risposta diversa da 2xx, lascia passare l'iscrizione. Un'API di verifica è un filtro di qualità, non un controllo di autenticazione, e bloccare un cliente pagante per un'interruzione temporanea è molto peggio che lasciar entrare un indirizzo dubbio. Sia il ramo !res.ok sia il catch qui sopra restituiscono ok: true proprio per questo motivo. Registra le iscrizioni in modalità degradata e intercettale invece nella tua prossima pulizia della lista.

Pronto a collegare tutto? Il piano Free include 100 crediti per provare il flusso, e il riferimento API contiene l'endpoint /verify con esempi da copiare e incollare in sette linguaggi.