Cómo activar el modo debug de PHPMailer y diagnosticar errores SMTP

El modo debug de PHPMailer muestra la conversación SMTP entre la aplicación y el servidor de correo. Es la forma más directa de distinguir un fallo de conexión, TLS, autenticación o rechazo del mensaje.

Actívalo solo mientras reproduces el problema, con un destinatario y contenido de prueba. La transcripción puede incluir remitentes, destinatarios, cabeceras y el cuerpo del mensaje. Los niveles 0 a 3 ocultan el usuario y la contraseña SMTP, pero SMTP::DEBUG_LOWLEVEL puede mostrarlos. No publiques el resultado completo.

Activar el nivel de diagnóstico recomendado

En PHPMailer 6 y 7 importa las clases y utiliza la constante SMTP::DEBUG_SERVER, equivalente al nivel 2 de versiones antiguas:

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;

$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->SMTPDebug = SMTP::DEBUG_SERVER;

Integra estas opciones en la instancia de PHPMailer que ya envía tu aplicación, después de cargar sus clases y antes de llamar a send(). El fragmento no es un programa completo de envío: conserva tu configuración de servidor, autenticación y destinatarios de prueba.

Este nivel registra tanto los comandos enviados por el cliente como las respuestas del servidor. El nivel 3 añade información sobre la conexión inicial y puede ayudar cuando hay un timeout. El nivel 4 muestra tráfico de bajo nivel, puede revelar las credenciales SMTP y no debe utilizarse salvo para analizar un problema de protocolo en un entorno controlado.

Si no quieres mostrar la transcripción en la respuesta HTML y el error_log de PHP ya apunta a un registro privado fuera de public_html, puedes enviarla allí:

$mail->Debugoutput = 'error_log';

No uses esta salida sin comprobar antes dónde escribe PHP: podría terminar en un registro compartido o descargable desde la web.

Cuando termines, desactiva el diagnóstico y elimina el registro cuando ya no sea necesario:

$mail->SMTPDebug = SMTP::DEBUG_OFF;

Cómo leer el resultado

Busca la última respuesta del servidor antes del fallo:

• No aparece una respuesta 220: revisa el nombre del servidor, DNS, puerto y posibles bloqueos de red.
• Falla STARTTLS o la validación del certificado: comprueba que TLS y puerto coinciden, que la extensión OpenSSL está activa y que el sistema tiene certificados CA actualizados. No desactives la verificación TLS para ocultar el error.
• Respuesta 535 o similar: el servidor rechazó la autenticación. Verifica usuario completo, contraseña y método admitido por el proveedor.
• Respuesta 550 o 5.7.x: el servidor recibió la petición pero rechazó el remitente, el destinatario o el mensaje. Conserva el texto completo porque suele indicar la política aplicada.
• Respuesta 250 al finalizar DATA: el servidor aceptó el mensaje para procesarlo. Un 250 anterior, por ejemplo tras EHLO o MAIL FROM, no confirma el envío completo. La aceptación tampoco garantiza entrega en la bandeja de entrada. Si luego aparece en spam, continúa con la guía de entregabilidad.

La guía oficial de resolución de problemas de PHPMailer recomienda usar ejemplos actuales, leer la transcripción SMTP completa y comprobar la red antes de atribuir el problema a la librería.

Datos útiles para reproducir el fallo

Guarda la versión de PHPMailer, la versión de PHP, el host y puerto SMTP, el tipo de cifrado y el mensaje de error completo. Sustituye antes cualquier dirección privada, token o credencial. Una captura que solo muestre SMTP connect() failed oculta normalmente la respuesta que permite encontrar la causa.