¿Cuánto cuesta cada lead perdido por un formulario que no envía? Problemas con formularios (CF7, Gravity) que se quedan cargando o no envían frenan conversiones y dañan la reputación; responsables web y técnicos necesitan una reparación prioritaria, segura y reproducible. Actúe ahora: siga una checklist ordenada con tiempos estimados, comandos y snippets listos para restaurar envíos y recuperar leads sin arriesgar otras funciones.
Si los formularios CF7 o Gravity no envían o se quedan cargando, lo primero es comprobar SMTP/wp_mail, errores PHP y la consola JS (nonces/AJAX). Conviene desactivar plugins y cambiar a un tema por defecto; probar un envío SMTP externo. Seguir la checklist paso a paso con snippets, logs y tiempos estimados permite diagnosticar y reparar sin riesgos.
Resumen del proceso
Este resumen permite identificar la causa raíz y probar una solución segura en menos de una hora. Cada paso tiene comandos, tiempo estimado y resultado esperado.
Checklist rápido
- Reproducir el fallo en modo incógnito y tomar captura (3 min).
- Abrir consola DevTools y filtrar XHR por "wp-json" o "admin-ajax.php" (5 min).
- Desactivar caché y modo de desarrollo en Cloudflare/hosting (5 min).
- Revisar logs mail/PHP con tail/grep (10 min).
- Probar SMTP con swaks/curl (10 min). O, si el hosting bloquea SMTP, usar la API HTTP del proveedor con curl. Ejemplos: swaks --to [email protected] --server smtp.sendgrid.net:587 --auth LOGIN --auth-user apikey --auth-password 'APIKEY' || curl -s -X POST https://api.sendgrid.com/v3/mail/send -H 'Authorization: Bearer APIKEY' -H 'Content-Type: application/json' -d '{"personalizations":[{"to":[{"email":"[email protected]"}]}],"from":{"email":"[email protected]"},"content":[{"type":"text/html","value":"Prueba"}] }'.
- Desactivar plugins por pares y probar (15 min).
- Aplicar fix temporal y monitorizar logs (10 min).
Resultado esperado
Tras seguir la checklist, el equipo identifica la causa primaria y aplica un parche temporal seguro. En la mayoría de sitios se obtiene una prueba de envío exitosa y registros claros en /var/log en menos de 60 minutos.
Comprobar logs y servidor
Revisar /var/log/mail.log y el log PHP suele mostrar códigos SMTP, errores fatales o timeouts que la interfaz de WordPress no muestra. Usar los comandos que siguen revela rechazo por SPF/DKIM, errores 500 de PHP o bloqueos de conexión.
Comandos y rutas
- tail -n 200 /var/log/mail.log
- tail -n 200 /var/log/php_errors.log || tail -n 200 /var/log/php7.4-fpm.log || tail -n 200 /var/log/apache2/error.log || journalctl -u php7.4-fpm -n 200. Utilice la variante que aplique a su stack y, si no existe, consulte journalctl o la configuración de error_log en php.ini para localizar el archivo correcto.
- journalctl -u postfix -n 200
- grep -i "contact-form-7|gravity" /var/log/apache2/error.log
Cada comando tarda entre 30 s y 2 min según tamaño del log.
Entradas ejemplo e interpretación
- Entrada SMTP: status=bounced (host mx.example.com[1.2.3.4] said: 550 5.7.1 ... SPF) significa rechazo por SPF; revisar DNS y remitente.
- Entrada PHP: PHP Fatal error: Uncaught Error: Call to undefined function indica conflicto de plugin/tema.
- Timeout: Connection timed out suele indicar bloqueo de puerto 25/587 o reglas WAF.
Cuando Contact Form 7 muestra un spinner eterno, la causa es casi siempre un error en JavaScript, un nonce inválido o una petición XHR que devuelve 404/500. Reproducir el envío en DevTools identifica la respuesta exacta del endpoint REST/AJAX.
Reproducir y aislar error JS
Abrir la página en modo incógnito, F12 → pestaña Console y Network. Filtrar por XHR y buscar rutas como /wp-json/contact-form-7/v1/contact-forms/{id}/feedback.
Errores frecuentes: 404 en endpoint REST, 403 por nonce, Uncaught ReferenceError por scripts dependientes que faltan.
Fixes y snippets seguros
- Forzar encolado: añadir en el child theme un enqueued script si el tema impide cargar wpcf7-scripts.
Ejemplo seguro (añadir en plugin propio o mu-plugin):
php
add_action('wp_enqueue_scripts','cf7_force_enqueue', 5);
function cf7_force_enqueue(){
if(function_exists('wpcf7_enqueue_scripts')){
wpcf7_enqueue_scripts();
wpcf7_enqueue_styles();
}
}
Comprobar sintaxis antes con php -l functions.php; realizar copia functions.php.bak.
Lo que omiten la mayoría de guías es documentar la petición XHR completa: cabeceras, cuerpo y respuesta. Esa información suele mostrar si falta una cabecera CSRF o si una regla WAF devuelve HTML en lugar de JSON.
Cuando el spinner de Contact Form 7 no desaparece, conviene una secuencia de depuración centrada en cliente:
- En Network, filtrar la petición a /wp-json/contact-form-7/ y comprobar Content-Type; si llega HTML en vez de JSON investigar reglas WAF/Cloudflare que inyectan HTML
- En Console buscar Uncaught ReferenceError y errores de carga por scripts con defer/async que cambian el orden de ejecución
- Revisar nonces y reCAPTCHA porque nonces inválidos devuelven 403. Como comprobación práctica, añadir temporalmente un listener que detecte respuestas no-JSON y haga log completo ayuda a identificar la fuente: jQuery(document).ajaxComplete(function(e,xhr,settings){ if(settings.url.indexOf('/wp-json/contact-form-7')!==-1){ if((xhr.getResponseHeader('Content-Type')||'').indexOf('application/json')===-1){ console.error('CF7 respuesta inesperada:', xhr.responseText); } } }); También conviene probar a remover defer/async en los scripts de formulario y re-encolar wpcf7-scripts mediante wp_enqueue para restaurar el orden correcto; si reCAPTCHA interviene, probar con la clave de test del proveedor para aislar el fallo
En Gravity Forms, fallos de envío suelen originarse en filtros o hooks (gform_pre_submission, gform_after_submission) que alteran datos o en integraciones externas que devuelven timeouts. Revisar los hooks y el registro de System Logs permite encontrar el 85% de los problemas.
Comprobar hooks e integraciones
Buscar funciones que enganchan a estos hooks y desactivarlas temporalmente con remove_filter para aislar el fallo. Revisar entradas en la tabla wp_rg_lead y en System Logs de Gravity Forms.
Hooks clave: gform_pre_validation, gform_pre_submission_filter, gform_after_submission.
Correcciones prácticas y snippets
- Si hay subida de archivos, aumentar upload_max_filesize y post_max_size en php.ini y reiniciar PHP-FPM.
- Para desactivar un hook problemático: remove_filter('gform_pre_submission', 'mi_funcion', 10);
- Si un webhook externo falla, probar con curl al endpoint y medir latencia; usar timeout corto (5 s) como configuración temporal.
Un caso habitual: un formulario que envía a una API externa y devuelve 500 → Gravity marca el envío como fallido aunque la entrada quede en la base de datos.
Configurar SMTP y DNS: gmail, SendGrid y mailgun
Configurar un SMTP autenticado y validar SPF/DKIM reduce reintentos y rechazos; Gmail sirve para volúmenes bajos, SendGrid y Mailgun son recomendables en producción. Probar con swaks y revisar Authentication-Results permite confirmar que SPF/DKIM pasan.
Ajustes y ejemplos por proveedor
- Gmail (volúmenes bajos): servidor smtp.gmail.com puerto 587 TLS; usar OAuth2 o contraseña de aplicación.
- SendGrid: servidor smtp.sendgrid.net puerto 587, usuario = apikey, password = "TU_APIKEY"; DNS: añadir include:sendgrid.net en SPF.
- Mailgun: smtp.mailgun.org puerto 587; añadir TXT SPF "v=spf1 include:mailgun.org ~all" y DKIM TXT que proporciona Mailgun.
Referencias: documentación oficial del plugin Contact Form 7 en WordPress.org y guías de Mailgun para DKIM.
Comandos de prueba
- swaks --to [email protected] --server smtp.sendgrid.net:587 --auth LOGIN --auth-user apikey --auth-password 'TU_APIKEY'
- curl test CF7 endpoint:
bash
curl -i -X POST https://tu-dominio.com/wp-json/contact-form-7/v1/contact-forms/123/feedback /
-H "Content-Type: application/x-www-form-urlencoded" /
--data "your-name=Test&[email protected]&your-message=Prueba"
Comprobar headers Received y Authentication-Results para SPF/DKIM/DMARC.
Esta guía tiene una recomendación directa: usar SendGrid o Mailgun en producción excepto cuando la política del hosting impide añadir registros DNS o abrir puertos SMTP; en esos casos recurrir a APIs HTTP del proveedor.
1
Reproducir: captura y consola (3 min)
2
Logs: mail.log y PHP error_log (10 min)
3
Probar SMTP: swaks / curl (10 min)
4
Aislar: desactivar plugins pares (15 min)
5
Aplicar fix: snippet seguro y monitor (10 min)
Para evitar ambigüedades al configurar el envío en producción, incluya ejemplos claros de archivos y registros. Por ejemplo, un extracto mínimo de main.cf para Postfix en un servidor que usa autenticación con relay: myhostname = mail.tu-dominio.com; relayhost = [smtp.sendgrid.net]:587; smtp_sasl_auth_enable = yes; smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd; smtp_tls_security_level = may; smtp_tls_CAfile = /etc/ssl/certs/ca-bundle.crt. En DNS añada un TXT SPF como "v=spf1 include:sendgrid.net include:mailgun.org -all" y pegue el registro DKIM que provea el proveedor, por defecto: default._domainkey.tu-dominio.com TXT "v=DKIM1; k=rsa; p=MIIBIjANB...".
Para WordPress, muestre la configuración exacta de un plugin SMTP (host, puerto, cifrado, usuario) y un ejemplo de php.ini ajustado: upload_max_filesize=32M, post_max_size=32M; la combinación de estos ejemplos facilita reproducir la configuración en SSH y validar con swaks o con la API HTTP del proveedor.
Snippets seguros, checklist reproducible y compatibilidades
Proporcionar snippets probados y una checklist reproducible evita errores comunes como editar functions.php sin backup. Aplicar cambios en un mu-plugin o plugin propio reduce riesgo.
Snippets wp_mail y cabeceras
Copiar y pegar solo en un plugin propio o mu-plugin. Comprobar sintaxis con php -l antes de activar.
forzar remitente y HTML
php
add_filter('wp_mail_from', function($from){return '[email protected]';});
add_filter('wp_mail_content_type', function($type){return 'text/html';});
Probar envío y revisar /var/log/mail.log. Si aparece un error 500 en el panel, revertir inmediatamente.
Checklist reproducible con tiempos y comandos
- ssh user@server "tail -n 200 /var/log/mail.log /var/log/php_errors.log" (10 min)
- curl al endpoint CF7 o pruebe swaks (5–10 min)
- desactivar cache/Cloudflare dev-mode (5 min)
- desactivar plugins por pares con WP-CLI: wp plugin deactivate plugin-slug (15 min)
- rollback: cp -r wp-content/themes/tu-tema wp-content/themes/tu-tema.bak
Tabla de compatibilidades
| Plugin |
Autor |
Error típico |
Impacto |
Acción recomendada |
| Contact Form 7 |
Takayuki Miyoshi / WordPress.org |
AJAX spinner por 404 REST o scripts faltantes |
Alto (envíos fallidos) |
Comprobar XHR, encolar scripts, configurar SMTP |
| Gravity Forms |
Rocketgenius |
Hooks que alteran payload o webhooks externos que timeout |
Alto (entradas incompletas) |
Desactivar filters, revisar System Logs, ajustar timeouts |
| WP Mail SMTP |
WPForms |
Credenciales incorrectas o falta DKIM |
Medio (pérdida de entregabilidad) |
Probar con swaks, verificar DNS y registros DKIM |
A fin de aplicar cambios sin riesgo, aporte snippets listos para copiar como mu-plugins y comandos automatizados.
- Ejemplo de mu-plugin mínimo (guardar en wp-content/mu-plugins/01-smtp-override.php): . Para pruebas automatizadas use scripts bash con swaks y curl
- swaks --to [email protected] --server smtp.sendgrid.net:587 --auth LOGIN --auth-user apikey --auth-password 'APIKEY' && curl -s -o /dev/null -w "%{http_code}" https://tu-dominio.com/wp-json/contact-form-7/v1/contact-forms/123/feedback --data "your-name=Auto&[email protected]&your-message=Prueba"
Para aislar plugins automáticamente utilice WP-CLI: wp plugin deactivate --all --path=/var/www/html && wp plugin activate contact-form-7 wp-mail-smtp --path=/var/www/html. Estos snippets permiten reproducir pruebas, registrar salidas y automatizar rollback si algo falla.
Preguntas frecuentes
Comprobar la consola JS y Network; muchas veces el spinner aparece por una respuesta HTML en lugar de JSON. Si el endpoint devuelve HTML, revisar reglas WAF o plugins que inyectan contenido.
¿Cómo pruebo SMTP sin enviar correos reales?
Usar swaks para simular envío y ver diálogo SMTP. Swaks muestra AUTH, MAIL FROM, RCPT TO y la respuesta del servidor.
¿Puedo usar Gmail en producción para enviar correos?
Sí para volúmenes bajos y pruebas; para volúmenes sostenidos elegir SendGrid o Mailgun. Gmail limita envíos y puede aplicar restricciones repentinamente.
¿Cómo detecto si Cloudflare bloquea las peticiones?
Activar "Development Mode" en Cloudflare y probar el envío; si funciona en dev-mode, Cloudflare WAF o reglas bloquean la petición.
Revisar System Logs y wp_rg_lead para confirmar la entrada; luego probar SMTP y mail.log para ver si el servidor entregó el correo o fue rechazado por destino.
¿Cómo validar SPF/DKIM rápidamente?
Usar dig: dig TXT tu-dominio.com +short y revisar registros; comprobar cabeceras Authentication-Results en correos recibidos.
Errores que arruinan el resultado y cuándo
Editar sin backup, no documentar pruebas y aplicar snippets en el tema padre son los errores que más complican la recuperación. Peor aún, confiar solo en la interfaz del plugin sin revisar logs del servidor suele ocultar la verdadera causa.
Lo que omiten muchos equipos es medir tiempos y documentar cambios: sin esa trazabilidad no se puede revertir de forma segura. Si el proveedor de hosting impone restricciones permanentes de correo (puertos cerrados, bloqueo de envíos), este método no resolverá la entregabilidad; contactar al hosting.
⚠️ No aplicar los cambios descritos si no se tiene acceso a logs del servidor o a la gestión DNS; en ese caso abrir un ticket con el proveedor y adjuntar las capturas y comandos ejecutados.
