Verificare le email dai moduli HubSpot in tempo reale

Un modulo HubSpot è una macchina per acquisire contatti: ogni invio crea o aggiorna un record di contatto, imposta le proprietà e può iscrivere quel contatto a un workflow. Quello che non fa è dirti se l'indirizzo digitato è davvero reale. Il campo email di HubSpot esegue un controllo del formato (conferma che ci siano una @ e un dominio), ma non può vedere che la casella è morta, usa e getta o un errore di battitura di gmail.com. Questa guida mostra due modi pratici per verificare le email dai moduli HubSpot con Qualisend: in tempo reale, con un workflow di Operations Hub che invia via POST ogni nuovo indirizzo all'API di Qualisend, e in blocco, esportando i contatti in un CSV. Nessuno dei due richiede un connettore nativo (per ora non esiste): bastano le azioni di workflow integrate di HubSpot o il suo pulsante di esportazione.

In breve#

Scegli il percorso in base a quando ti serve la risposta:

• In tempo reale: iscrivi a un workflow le nuove persone che compilano il modulo. Un'azione custom-code o webhook chiama l'API di Qualisend con l'email, e una diramazione scrive l'esito in una proprietà del contatto, poi instrada o sopprime il record in base allo status restituito.
• In blocco: esporta i contatti in CSV, passali alla verifica in blocco di Qualisend e sopprimi gli indirizzi non recapitabili prima del prossimo invio.

Perché il campo del modulo HubSpot non può confermare una casella#

Il campo email di HubSpot valida il formato: controlla che la stringa sembri un indirizzo prima di lasciar inviare il modulo. È lo stesso tipo di controllo di una regex, e fallisce per gli stessi motivi: il formato non è deliverability. jane@gmial.com supera il controllo del formato. Lo stesso vale per throwaway@mailinator.com e per un indirizzo dall'aspetto reale su un dominio che ha chiuso l'anno scorso.

Nessuno di questi viene intercettato finché non invii, e a quel punto un indirizzo morto è un hard bounce che intacca il tuo tasso di bounce e la reputazione del mittente. La vera verifica aggiunge i livelli che HubSpot non può offrire: una ricerca DNS/MX e un test SMTP della casella, più indicatori per gli indirizzi usa e getta, generici e catch-all. Se questa pipeline è nuova per te, cosa controlla davvero la verifica email è il punto di partenza.

Due modi per verificare le email dai moduli HubSpot#

Prima il vincolo importante: un modulo HubSpot standard non può bloccare un'email errata durante l'invio. Non esiste un modo supportato per chiamare un'API esterna tra il clic su "Submit" e la creazione del record, quindi la verifica in tempo reale avviene subito dopo l'invio, dentro un workflow, e non come filtro in linea. Questo condiziona entrambi i percorsi qui sotto.

Percorso 1: in tempo reale con un workflow di Operations Hub#

Crea un workflow basato sui contatti e imposta il trigger di iscrizione su "Form submission", limitato al modulo che ti interessa. Ora ogni nuova persona che compila il modulo entra nel workflow, dove effettui la chiamata di verifica e agisci sul risultato.

Ci sono due modi per effettuare quella chiamata: scegli quello adatto al tuo portale e al tuo stack.

Opzione A: un'azione custom-code (autonoma). Se sei su Operations Hub Professional o Enterprise, un'azione custom-code esegue Node.js (o Python) direttamente nel workflow. Aggiungi l'email del contatto iscritto come proprietà di input, salva la tua chiave come secret con il nome QUALISEND_API_KEY e chiama Qualisend dall'azione:

// HubSpot custom-code action (Node.js) — input property: email, secret: QUALISEND_API_KEY
const QUALISEND_ENDPOINT = "https://app.qualisend.com/api/v1/verify"; // confirm the path in /developers

exports.main = async (event, callback) => {
  const email = event.inputFields.email;

  // Fail open — never block a real lead on a transient API error.
  const failOpen = () => callback({ outputFields: { email_status: "unknown" } });

  let res;
  try {
    res = await fetch(QUALISEND_ENDPOINT, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.QUALISEND_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email }),
      signal: AbortSignal.timeout(10000),
    });
  } catch {
    return failOpen(); // timeout or network error
  }
  if (!res.ok) return failOpen(); // 402 out of credits, 429 rate limited, 5xx

  const { job_id, result } = await res.json();
  callback({
    outputFields: {
      email_status: result.status, // deliverable / risky / undeliverable / unknown
      email_score: result.score,
      email_smtp: result.smtp, // pending / cached / skipped
      qualisend_job_id: job_id,
    },
  });
};

L'azione espone come output email_status, email_score, email_smtp e qualisend_job_id. Quando email_smtp è cached o skipped, l'esito è già definitivo. Quando è pending, il test della casella è ancora in corso e email_status è solo l'esito locale istantaneo (di solito unknown), quindi non basare ancora l'instradamento su quel valore: crea una diramazione su email_smtp, aggiungi un breve Delay e poi una seconda azione custom-code che legge il job completato, con qualisend_job_id come input:

// Second custom-code action, after the Delay: input qualisend_job_id, secret: QUALISEND_API_KEY
exports.main = async (event, callback) => {
  const jobId = event.inputFields.qualisend_job_id;

  try {
    const res = await fetch(`https://app.qualisend.com/api/v1/jobs/${jobId}?include=results`, {
      headers: { Authorization: `Bearer ${process.env.QUALISEND_API_KEY}` },
      signal: AbortSignal.timeout(10000),
    });
    const job = res.ok ? await res.json() : null;
    const row = job?.status === "completed" ? job.results?.[0] : null;
    if (row) {
      return callback({ outputFields: { email_status: row.status, email_score: row.score } });
    }
  } catch {
    // timeout or network error: fall through and fail open
  }

  // Still running, or the API didn't answer: keep it unknown and re-check later.
  callback({ outputFields: { email_status: "unknown" } });
};

Su entrambe le diramazioni, fai seguire all'ultima azione un passaggio Copy property value che scrive email_status in una proprietà personalizzata del contatto, poi usa una if/then branch per instradare in base a quella: è l'unico motivo per cui hai eseguito il controllo.

Opzione B: un'azione webhook verso una tua funzione. Preferisci tenere la logica nel tuo codice, o non hai un piano con il custom-code? Aggiungi un'azione webhook che invia via POST a una piccola funzione serverless che controlli tu. La funzione estrae l'email, chiama Qualisend e scrive l'esito finale nel contatto in HubSpot con la sua API CRM (quando smtp risulta pending, legge quell'esito da GET /jobs/{job_id} una volta terminato il job). È la stessa struttura lato server dello schema di verifica all'iscrizione: la chiave API non lascia mai il server e tu agisci sul risultato. Il codice dell'endpoint nella guida per Node.js o nella guida per Python si inserisce quasi senza modifiche: solo l'analisi del payload è specifica di HubSpot.

In ogni caso la richiesta sottostante è la stessa, e i segnaposto li compili tu partendo dalla documentazione per sviluppatori:

POST https://app.qualisend.com/api/v1/verify
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{ "email": "jane@example.com" }

Per un indirizzo recapitabile la risposta è questa: uno status, uno score da 0 a 100, un reason e un insieme di sub_flags:

{
  "job_id": "6f1d2c3e-8a4b-4c5d-9e6f-7a8b9c0d1e2f",
  "result": {
    "status": "deliverable",
    "score": 95,
    "smtp": "cached",
    "reason": "accepted_email",
    "sub_flags": { "disposable": false, "role": false, "free_mail": false, "catch_all": false }
  }
}

Qui smtp è cached, quindi l'esito è già definitivo. Quando invece è pending, reason è ancora null e i valori finali di status, score e reason arrivano dalla lettura del job.

Due regole rendono tutto questo robusto. Usa una chiave dedicata creata solo per questo workflow (lo scope predefinito verify copre sia il controllo sia la lettura del job), così, se dovesse mai trapelare da un log, potrai revocarla senza compromettere nient'altro. E lascia passare in caso di errore (fail open): se Qualisend va in timeout o viene raggiunto il limite del piano, tratta l'indirizzo come unknown e tieni il contatto, invece di scartare un lead reale per un problema passeggero: è esattamente ciò che fanno i rami catch e !res.ok qui sopra.

A valle, l'esito è solo una diramazione. Imposta dall'output una proprietà personalizzata "Email status", poi lascia decidere al workflow: un contatto deliverable prosegue nella sequenza di nurturing; un undeliverable o disposable vede sospeso il follow-up, viene segnalato per la revisione oppure impostato come non-marketing, così da restare escluso dalle liste attive e dagli invii. Il workflow è l'infrastruttura; l'instradamento lo decidi tu.

Percorso 2: verificare in blocco un'esportazione CSV#

Se hai già migliaia di contatti, o preferisci pulire a intervalli regolari anziché eseguire controlli a ogni invio del modulo, procedi a lotti: questo percorso non richiede alcun workflow, quindi funziona anche sotto i piani di Operations Hub. In HubSpot apri Contacts, scegli una lista o un filtro e fai Export in CSV. Otterrai una riga per ogni contatto, con l'email in una colonna a sé.

Poi:

1. Carica il CSV nella verifica in blocco di Qualisend e lascia che esegua l'intero processo (MX, SMTP e gli indicatori usa e getta, generico e catch-all) su ogni riga.
2. Scarica il file annotato. Ogni indirizzo torna con uno status, un reason e uno score da 0 a 100.
3. Sopprimi gli indirizzi non recapitabili in HubSpot: importa i risultati per impostare la tua proprietà "Email status", poi escludi tutto ciò che non è recapitabile dalle liste attive e dagli invii di marketing.

La verifica in blocco è lo strumento giusto per i contatti già accumulati, ma è pulizia, non prevenzione: un indirizzo che intercetti qui di solito era già nel tuo database da tempo. Abbina un passaggio periodico in blocco al workflow in tempo reale, così i nuovi indirizzi errati vengono segnalati nel momento in cui arrivano.

Agire in base all'esito#

Qualunque sia il percorso che restituisce il risultato, la forma è la stessa: uno status, un reason, uno score e gli indicatori aggiuntivi. Associa ciascuno a un'azione:

Se stai valutando l'approccio con i workflow di HubSpot rispetto alla chiamata diretta all'API dal tuo backend, vale lo stesso compromesso di qualsiasi strato di collegamento: i workflow vincono per velocità di configurazione, un'integrazione diretta vince per costi e controllo su larga scala. Lo stesso schema con webhook è alla base anche delle guide analoghe per Zapier e Typeform, se una parte della tua acquisizione avviene fuori da HubSpot.

Pronto a collegare tutto? Prendi una chiave con gli scope giusti e il formato esatto della richiesta nella documentazione per sviluppatori, fai un controllo rapido su un singolo indirizzo con la verifica email gratuita oppure parti dai 100 crediti gratuiti disponibili su ogni piano per testare il workflow dall'inizio alla fine prima di attivarlo.