Verificare le email da Gravity Forms

Gravity Forms è il cavallo di battaglia dei siti WordPress più seri (candidature su più pagine, flussi di registrazione, richieste di preventivo) e ognuno di questi moduli ha un campo email che controlla il formato e nient'altro. Per verificare le email da Gravity Forms non installi un plugin dedicato: ti agganci all'invio, chiami un'API di verifica e rifiuti in linea un indirizzo errato oppure gli aggiungi un tag a posteriori. Questa guida copre i tre percorsi supportati: un filtro di validazione PHP che blocca gli indirizzi non recapitabili e usa e getta prima che la voce venga salvata, il Webhooks Add-On per aggiungere tag e sopprimere in modo asincrono e un'esportazione CSV per pulire in blocco la tabella delle voci.

In breve#

Gravity Forms ti offre due punti di integrazione, e quale usare dipende dal fatto che tu voglia fermare un indirizzo errato o solo reagire:

1. In tempo reale, in linea: un piccolo snippet PHP sul filtro gform_field_validation chiama l'API di Qualisend mentre il modulo viene validato e restituisce un errore di campo che il visitatore vede. È l'unico punto in cui puoi rifiutare un indirizzo prima che diventi una voce.
2. In tempo reale, asincrono: dopo il salvataggio, il Webhooks Add-On invia via POST ogni voce a un URL che controlli tu. Non può mostrare un errore in linea, ma è perfetto per aggiungere tag, instradare o sopprimere gli indirizzi non recapitabili prima che raggiungano il tuo strumento email.
3. In blocco: esporta le voci salvate in CSV e passale periodicamente alla verifica in blocco di Qualisend. Niente codice, e funziona con qualsiasi licenza che salvi le voci.

Questo articolo è il complemento specifico per Gravity Forms della guida più ampia verificare le email nei moduli WordPress, che copre Contact Form 7 e WPForms con gli stessi schemi. Se usi più di un plugin per moduli, parti da lì; se usi solo Gravity Forms, tutto ciò che ti serve è qui sotto.

Perché il campo email di Gravity Forms non basta#

Il tipo di campo email controlla che ciò che qualcuno ha digitato sembri un indirizzo: una @, un dominio, nessuno spazio di troppo. È un controllo del formato, e il formato non è deliverability. jane@gmial.com lo supera. Lo stesso vale per throwaway@mailinator.com e per una casella dall'aspetto reale su un dominio scaduto sei mesi fa. 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 Gravity Forms non può offrire: una ricerca DNS/MX, un test SMTP della casella e indicatori per gli indirizzi usa e getta, generici, gratuiti e catch-all. Se questo processo è nuovo per te, come funziona la verifica email spiega ogni controllo e perché è importante.

Verificare le email da Gravity Forms all'invio#

Gravity Forms espone un filtro di validazione a livello di campo che scatta durante la validazione, prima del salvataggio della voce: significa che puoi invalidare il campo email e dare al visitatore un messaggio di errore da correggere. È il filtro gform_field_validation, ed è l'hook giusto quando vuoi un blocco in linea anziché una pulizia a posteriori.

Il callback riceve il $result corrente del campo (con un flag is_valid e un message), il $value inviato, il $form e il $field. Chiami l'API e, se l'esito è negativo, imposti is_valid su false e definisci il messaggio. Tieni la chiave API in una costante di wp-config.php, mai in un'impostazione del modulo, in un file del tema o in JavaScript front-end:

// In a code-snippet plugin, or your theme's functions.php.
// In wp-config.php:  define( 'QUALISEND_API_KEY', 'YOUR_API_KEY' );

add_filter( 'gform_field_validation', 'qs_gf_verify_email', 10, 4 );

function qs_gf_verify_email( $result, $value, $form, $field ) {
    // Only run on email fields that already passed Gravity Forms' own checks.
    if ( $field->type !== 'email' || ! $result['is_valid'] ) {
        return $result;
    }

    // An email field with "confirm" enabled hands back an array.
    $email = is_array( $value ) ? rgar( $value, 0 ) : $value;
    $email = trim( (string) $email );
    if ( $email === '' ) {
        return $result; // let the field's own required-field check handle empties
    }

    // Confirm the exact endpoint and request body in /developers.
    $response = wp_remote_post( 'https://app.qualisend.com/api/v1/verify', array(
        'timeout' => 4, // cap it so a slow probe can't stall the form
        'headers' => array(
            'Authorization' => 'Bearer ' . QUALISEND_API_KEY,
            'Content-Type'  => 'application/json',
        ),
        'body' => wp_json_encode( array( 'email' => $email ) ),
    ) );

    // Fail open: a transient error must never block a real applicant.
    if ( is_wp_error( $response ) || wp_remote_retrieve_response_code( $response ) !== 200 ) {
        return $result;
    }

    $verdict = json_decode( wp_remote_retrieve_body( $response ), true )['result'] ?? array();

    if ( ( $verdict['status'] ?? '' ) === 'undeliverable' ) {
        $result['is_valid'] = false;
        $result['message']  = "That address doesn't look deliverable — please check it.";
    } elseif ( ! empty( $verdict['sub_flags']['disposable'] ) ) {
        $result['is_valid'] = false;
        $result['message']  = 'Please use a permanent email address.';
    }

    return $result;
}

Tre accorgimenti reggono questo snippet, e sono gli stessi in ogni linguaggio: tieni la chiave lato server, limita la richiesta con un timeout breve e lascia passare in caso di errore (fail open): se la chiamata dà errore, va in timeout o restituisce un codice diverso da 200, lascia passare l'invio. Un'API di verifica è un filtro di qualità, non un controllo di autenticazione, e perdere un lead reale per un'interruzione momentanea è il risultato peggiore. Per i dettagli della richiesta (intestazioni, gestione degli errori, struttura della risposta result), la guida alla validazione email in PHP illustra la stessa chiamata dall'inizio alla fine.

Una nota sull'ambito: lasciando il filtro globale (come sopra), verifichi il campo email di ogni modulo. Per limitarti a un solo modulo, aggancia invece la variante specifica per modulo e campo gform_field_validation_{form_id}_{field_id} oppure aggiungi all'inizio un controllo if ( $form['id'] !== 5 ) return $result;. E se devi validare più campi insieme, ad esempio verificare solo quando è impostato un altro campo, il filtro a livello di modulo gform_validation ti dà l'intero $form e ti consente di contrassegnare i singoli campi come non validi; il filtro di campo qui sopra è più semplice e basta per un singolo controllo sull'email.

Agire in base all'esito#

L'API restituisce un oggetto result con uno status che può essere deliverable, risky, undeliverable o unknown, più uno score da 0 a 100, un codice reason e indicatori aggiuntivi per disposable, role, free_mail e catch_all: è lo stesso $verdict che legge lo snippet. Associa a ciascuno un'azione nel modulo:

Su un modulo attivo, affidati ai controlli locali rapidi (sintassi, dominio, usa e getta, generico), perché rispondono in fretta e intercettano gran parte degli indirizzi spazzatura senza far aspettare il visitatore. Il più pesante test SMTP della casella si adatta meglio al percorso in blocco qui sotto, dove un paio di secondi di latenza non contano per nessuno.

Il percorso con il Webhooks Add-On#

Se il PHP personalizzato non è un'opzione, o devi solo tenere gli indirizzi morti fuori dal tuo strumento a valle senza bloccare il modulo, il Webhooks Add-On di Gravity Forms lo fa senza codice. È un add-on con licenza (incluso nelle licenze Gravity Forms di livello superiore, quindi controlla il tuo piano) e invia una richiesta HTTP configurabile come feed dopo ogni invio.

In Settings → Webhooks del modulo, aggiungi un feed: imposta il tipo di richiesta su POST e il formato su JSON, fai puntare l'URL a un endpoint che controlli tu e mappa il campo email nel corpo della richiesta. Dato che non puoi inserire in sicurezza una chiave API nelle intestazioni del webhook e poi chiamare Qualisend da una terza parte, lo schema pulito è far puntare il webhook a una piccola funzione serverless tua: è esattamente la configurazione della guida alla verifica all'iscrizione con serverless. Quella funzione custodisce la chiave, riceve il payload di Gravity Forms, estrae l'email, chiama l'API e agisce sull'esito.

Il limite sono i tempi. Il Webhooks Add-On scatta dopo che la voce è già stata salvata, quindi funziona in modo asincrono e non può mostrare al visitatore un errore di validazione: su questo percorso non c'è rifiuto in linea. Quello che può fare è verificare in pochi secondi e instradare in base al risultato: aggiungere un tag nel CRM, saltare l'autoresponder per un indirizzo non recapitabile o sopprimerlo prima ancora che raggiunga la tua piattaforma email. Se vuoi che il visitatore veda e corregga un indirizzo errato, usa il filtro di validazione qui sopra; se ti interessa solo l'igiene a valle, il webhook basta.

Verifica in blocco di un'esportazione CSV di Gravity Forms#

Non tutti i moduli hanno bisogno di un controllo in tempo reale, e avrai anche un archivio di voci raccolte prima di aggiungerne uno. In entrambi i casi, il percorso senza codice è pulire a lotti:

1. Esporta le voci in CSV. Nell'amministrazione di Gravity Forms apri Forms → Import/Export → Export Entries, scegli il modulo, includi la colonna email e scarica il file. Ottieni una riga per ogni voce, con l'indirizzo in una colonna a sé.
2. Verifica il CSV in blocco. Caricalo nella verifica in blocco di Qualisend, che esegue l'intero processo (MX, il test SMTP e gli indicatori usa e getta, generico e catch-all) su ogni riga e restituisce un file con i punteggi, più status e reason per ogni indirizzo.
3. Filtra e sincronizza. Tieni i deliverable, controlla i risky e scarta gli undeliverable prima di importare quelli rimasti nella tua piattaforma email.

È lo stesso ciclo di esportazione, verifica e reimportazione di qualsiasi pulizia della lista, solo con la tabella delle voci di Gravity Forms come fonte: la guida alla pulizia di una lista email lo tratta per intero. Verifica una volta l'archivio, poi lascia che un hook all'invio mantenga pulita la lista da lì in avanti.

In tempo reale, in blocco o entrambi#

Risolvono problemi diversi, quindi la maggior parte dei siti finisce per volerli entrambi:

• Il tempo reale è prevenzione. Un errore di battitura intercettato all'invio è un lead salvato con una correzione di una riga; un dominio morto rifiutato lì non diventa mai un hard bounce.
• La verifica in blocco è pulizia. Gli indirizzi si deteriorano (le persone cambiano lavoro, i domini scadono), quindi anche una lista protetta alla perfezione va riverificata periodicamente.

Quale percorso in tempo reale puoi usare dipende dalla tua licenza e da quanto ti senti a tuo agio con il codice: il filtro di validazione richiede uno snippet PHP ma ti dà un blocco in linea, mentre il Webhooks Add-On richiede un piano a pagamento ma nessun codice e gestisce i tag in modo asincrono. Abbinare quello che scegli a un passaggio occasionale in blocco è tutta la strategia.

Pronto a collegare tutto? Il piano Free include crediti per testare ogni percorso, il riferimento API ha la richiesta /verify esatta per il tuo filtro di validazione o la tua funzione serverless e la verifica email gratuita ti consente di provare un singolo indirizzo prima di scrivere una riga di PHP.