Verificar correos de Gravity Forms

Gravity Forms es el caballo de batalla de los sitios WordPress serios: aplicaciones de varias páginas, flujos de registro, solicitudes de presupuesto, y cada uno de ellos tiene un campo de correo que comprueba el formato y nada más. Para verificar correos de Gravity Forms no instalas un plugin de marca; te enganchas al envío, llamas a una API de verificación y, o bien rechazas una dirección incorrecta en línea, o la etiquetas a posteriori. Esta guía cubre las tres vías compatibles: un filtro de validación PHP que bloquea las direcciones no entregables y desechables antes de que se guarde la entrada, el complemento Webhooks para el etiquetado y supresión asíncronos, y una exportación a CSV para limpiar tu tabla de entradas en masa.

La respuesta breve#

Gravity Forms te ofrece dos puntos de integración, y cuál elijas depende de si quieres detener una dirección incorrecta o simplemente reaccionar a ella:

1. En tiempo real, en línea: un pequeño fragmento de PHP en el filtro gform_field_validation llama a la API de Qualisend mientras el formulario se valida y devuelve un error de campo que el visitante ve. Este es el único lugar donde puedes rechazar una dirección antes de que se convierta en una entrada.
2. En tiempo real, asíncrono: el complemento Webhooks envía por POST cada entrada a una URL que tú controlas después de guardarse. No puede mostrar un error en línea, pero es perfecto para etiquetar, enrutar o suprimir direcciones no entregables antes de que lleguen a tu herramienta de correo.
3. Masivo: exporta las entradas almacenadas a CSV y pásalas por el verificador masivo de Qualisend de forma periódica. Sin código, funciona con cualquier licencia que almacene entradas.

Este artículo es el complemento específico de Gravity Forms de la guía más amplia verificar correos en formularios de WordPress, que cubre Contact Form 7 y WPForms con los mismos patrones. Si usas más de un plugin de formularios, empieza por ahí; si vas todo con Gravity Forms, todo lo que necesitas está más abajo.

Por qué el campo de correo de Gravity Forms no basta#

El tipo de campo email valida que lo que alguien escribió parezca una dirección: una @, un dominio, sin espacios sueltos. Eso es una comprobación de formato, y el formato no es entregabilidad. jane@gmial.com la supera. También lo hace throwaway@mailinator.com, y también un buzón de aspecto real en un dominio que caducó hace seis meses. Ninguno de esos se detecta hasta que envías, y para entonces una dirección muerta es un rebote duro que erosiona tu tasa de rebote y la reputación de remitente.

La verificación real añade las capas que Gravity Forms no puede: una consulta DNS/MX, un sondeo SMTP del buzón y marcas para direcciones desechables, de rol, gratuitas y catch-all. Si el proceso es nuevo para ti, cómo funciona la verificación de correo desglosa cada comprobación y por qué importa.

Verificar correos de Gravity Forms en el envío#

Gravity Forms expone un filtro de validación a nivel de campo que se activa durante la validación, antes de que se guarde la entrada, lo que significa que puedes invalidar el campo de correo y entregar al visitante un mensaje de error para que lo corrija. Ese es el filtro gform_field_validation, y es el hook adecuado cuando quieres una barrera en línea en lugar de una limpieza a posteriori.

El callback recibe el $result actual del campo (con una marca is_valid y un message), el $value enviado, el $form y el $field. Llamas a la API y, si el veredicto es malo, cambias is_valid a false y estableces el mensaje. Mantén la clave de API en una constante de wp-config.php, nunca en un ajuste del formulario, un archivo del tema ni ningún JavaScript del 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://api.qualisend.com/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;
}

Tres cosas sostienen este fragmento, y son las mismas tres en cualquier lenguaje: mantén la clave en el servidor, limita la petición con un tiempo de espera corto y falla en abierto: si la llamada da error, expira o devuelve un código distinto de 200, deja pasar el envío. Una API de verificación es un filtro de calidad, no una barrera de autenticación, y perder un lead real por una caída momentánea es el peor desenlace. Para la mecánica de la propia petición (cabeceras, gestión de errores, la forma de la respuesta result), la guía de validación de correo en PHP recorre la misma llamada de principio a fin.

Una nota sobre el alcance: dejar el filtro global (como arriba) verifica el campo de correo en todos los formularios. Para apuntar a un solo formulario, engancha en su lugar la variante específica de formulario y campo gform_field_validation_{form_id}_{field_id}, o añade una guarda temprana if ( $form['id'] !== 5 ) return $result;. Y si necesitas validar en varios campos a la vez —por ejemplo, verificar solo cuando otro campo está establecido— el filtro a nivel de formulario gform_validation te da todo el $form y te permite marcar campos individuales como fallidos; el filtro de campo de arriba es más sencillo y suficiente para una única barrera de correo.

Actuar sobre el veredicto#

La API devuelve un objeto result con un status de deliverable, risky, undeliverable o unknown, además de un score de 0 a 100, un código reason y sub-marcas para disposable, role, free y catch_all: el mismo $verdict que lee el fragmento. Asigna cada uno a una acción del formulario:

En un formulario en vivo, apóyate en las comprobaciones locales rápidas —sintaxis, dominio, desechable, rol— porque responden enseguida y atrapan el grueso de la basura sin hacer esperar al visitante. El sondeo SMTP del buzón, más pesado, encaja mejor en la vía masiva de abajo, donde un par de segundos de latencia no le importan a nadie.

La vía del complemento Webhooks#

Si el PHP a medida no es una opción —o solo necesitas mantener las direcciones muertas fuera de tu herramienta posterior, no bloquear el formulario— el complemento Webhooks de Gravity Forms lo hace sin código. Es un complemento con licencia (incluido con las licencias de Gravity Forms de nivel superior, así que comprueba tu plan) y dispara una petición HTTP configurable como un feed después de cada envío.

En los Ajustes → Webhooks del formulario, añade un feed: establece el tipo de petición en POST, el formato en JSON, apunta la URL a un endpoint que controles y asigna el campo de correo al cuerpo de la petición. Como no puedes poner de forma segura una clave de API en las cabeceras del propio webhook y luego llamar a Qualisend desde un tercero, el patrón limpio es apuntar el webhook a una pequeña función serverless tuya: la configuración exacta de la guía serverless de verificación en el registro. Esa función guarda la clave, recibe la carga de Gravity Forms, extrae el correo, llama a la API y actúa sobre el veredicto.

El truco está en el momento. El complemento Webhooks se activa después de que la entrada ya se ha guardado, así que se ejecuta de forma asíncrona y no puede mostrar al visitante un error de validación: en esta vía no hay rechazo en línea. Lo que sí puede hacer es verificar en segundos y enrutar según el resultado: añadir una etiqueta en tu CRM, saltarse el autoresponder para una dirección no entregable, o suprimirla antes de que llegue a tu plataforma de correo. Si necesitas que el visitante vea y corrija una dirección incorrecta, usa el filtro de validación de arriba; si lo único que buscas es higiene posterior, el webhook basta.

Verificar en masa una exportación CSV de Gravity Forms#

No todos los formularios necesitan una barrera en tiempo real, y además tendrás un catálogo pasado de entradas recogidas antes de añadir una. Para ambos casos, la vía sin código es limpiar por lotes:

1. Exporta las entradas a CSV. En la administración de Gravity Forms, abre Forms → Import/Export → Export Entries, elige el formulario, incluye la columna del correo y descarga el archivo. Obtienes una fila por entrada con la dirección en su propia columna.
2. Verifica el CSV en masa. Súbelo al verificador masivo de Qualisend, que ejecuta el proceso completo —MX, el sondeo SMTP y las marcas de desechable/rol/catch-all— en cada fila y te devuelve un archivo puntuado con un status y un reason por dirección.
3. Filtra y sincroniza. Conserva las deliverable, revisa las risky y descarta las undeliverable antes de importar las supervivientes a tu plataforma de correo.

Es el mismo bucle de exportar-verificar-reimportar que cualquier limpieza de lista, solo que con origen en tu tabla de entradas de Gravity Forms: la guía para limpiar una lista de correo lo cubre por completo. Pasa el catálogo pasado una vez y luego deja que un hook en el envío mantenga la lista limpia de ahí en adelante.

Tiempo real, masivo o ambos#

Resuelven problemas distintos, así que la mayoría de sitios acaban queriendo ambos:

• El tiempo real es prevención. Una errata atrapada en el envío es un lead salvado con una corrección de una línea; un dominio muerto rechazado ahí nunca se convierte en un rebote duro.
• El masivo es limpieza. Las direcciones se degradan —la gente cambia de trabajo, los dominios caducan—, así que incluso una lista perfectamente filtrada necesita reverificación periódica.

Qué vía en tiempo real puedes usar depende de tu licencia y de tu comodidad con el código: el filtro de validación necesita un fragmento de PHP pero te da un bloqueo en línea, mientras que el complemento Webhooks necesita un nivel de pago pero ningún código y gestiona el etiquetado asíncrono. Emparejar la que elijas con un pase masivo ocasional es toda la estrategia.

Preguntas frecuentes#

¿Puede Gravity Forms verificar direcciones de correo por sí solo?#

Solo el formato. El tipo de campo email confirma que una dirección está bien formada —tiene una @ y un dominio— pero no resuelve registros MX ni sondea el buzón, así que una dirección con una errata, desechable o inactiva desde hace tiempo que parece válida sigue pasando. La verificación real necesita las capas de DNS y SMTP que un servicio como Qualisend añade por encima, invocadas desde un filtro de validación, un webhook o un trabajo masivo con CSV.

¿Puede un webhook de Gravity Forms rechazar una dirección incorrecta en línea?#

No. El complemento Webhooks se activa después de guardar la entrada, así que se ejecuta de forma asíncrona y no puede mostrar al visitante un error de validación. Es ideal para etiquetar, enrutar o suprimir direcciones no entregables antes de que lleguen a tu herramienta de correo. Para un rechazo en línea que el visitante vea y pueda corregir, usa en su lugar el filtro gform_field_validation con el fragmento de PHP de esta guía.

¿Qué hook de Gravity Forms debería usar para verificar en el envío?#

Usa gform_field_validation para un único campo de correo: se activa durante la validación, recibe el valor del campo y te permite devolver un error en línea. Si necesitas validar en varios campos o ejecutar la comprobación condicionalmente en todo el formulario, usa el filtro a nivel de formulario gform_validation y marca los campos individuales como fallidos. Ambos se ejecutan en el servidor antes de que se guarde la entrada, así que ambos pueden bloquear.

¿Existe un complemento nativo de Qualisend para Gravity Forms?#

Ahora mismo no: nuestras integraciones nativas de la plataforma se están reconstruyendo y un conector para Gravity Forms está en la hoja de ruta. Hasta que salga, los enfoques compatibles son los tres de esta guía: llamar a la API REST desde el filtro de validación, desde una función serverless detrás del complemento Webhooks, o exportar las entradas a CSV y verificarlas en masa. Todos usan la API documentada directamente.

¿Listo para montarlo? El plan gratuito incluye créditos para probar cada vía, la referencia de la API tiene la petición /verify exacta para tu filtro de validación o función serverless, y el verificador de correo gratuito te permite probar una sola dirección antes de escribir una línea de PHP.