Activer le mode debug de PHPMailer et diagnostiquer les erreurs SMTP

Le mode debug de PHPMailer affiche la conversation SMTP entre l'application et le serveur de messagerie. C'est le moyen le plus direct de distinguer un échec de connexion, de TLS, d'authentification ou un rejet du message.

Activez-le uniquement le temps de reproduire le problème, avec un destinataire et un contenu de test. La transcription peut contenir des expéditeurs, des destinataires, des en-têtes et le corps du message. Les niveaux 0 à 3 masquent l'utilisateur et le mot de passe SMTP, mais SMTP::DEBUG_LOWLEVEL peut les afficher. Ne publiez pas le résultat complet.

Activer le niveau de diagnostic recommandé

Dans PHPMailer 6 et 7, importez les classes et utilisez la constante SMTP::DEBUG_SERVER, équivalente au niveau 2 des anciennes versions :

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

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

Intégrez ces options dans l'instance de PHPMailer qu'utilise déjà votre application pour envoyer, après le chargement de ses classes et avant l'appel à send(). Cet extrait n'est pas un programme d'envoi complet : conservez votre configuration de serveur, d'authentification et vos destinataires de test.

Ce niveau enregistre à la fois les commandes envoyées par le client et les réponses du serveur. Le niveau 3 ajoute des informations sur la connexion initiale et peut aider en cas de timeout. Le niveau 4 affiche le trafic de bas niveau, peut révéler les identifiants SMTP et ne doit être utilisé que pour analyser un problème de protocole dans un environnement contrôlé.

Si vous ne voulez pas afficher la transcription dans la réponse HTML et que le error_log de PHP pointe déjà vers un journal privé situé hors de public_html, vous pouvez l'y envoyer :

$mail->Debugoutput = 'error_log';

N'utilisez pas cette sortie sans vérifier d'abord où PHP écrit : elle pourrait finir dans un journal partagé ou téléchargeable depuis le web.

Lorsque vous avez terminé, désactivez le diagnostic et supprimez le journal dès qu'il n'est plus nécessaire :

$mail->SMTPDebug = SMTP::DEBUG_OFF;

Lire le résultat

Cherchez la dernière réponse du serveur avant l'échec :

• Aucune réponse 220 n'apparaît : vérifiez le nom du serveur, le DNS, le port et d'éventuels blocages réseau.
• STARTTLS ou la validation du certificat échoue : vérifiez que le TLS et le port correspondent, que l'extension OpenSSL est active et que le système dispose de certificats CA à jour. Ne désactivez pas la vérification TLS pour masquer l'erreur.
• Réponse 535 ou similaire : le serveur a refusé l'authentification. Vérifiez l'utilisateur complet, le mot de passe et la méthode acceptée par le fournisseur.
• Réponse 550 ou 5.7.x : le serveur a reçu la demande mais a refusé l'expéditeur, le destinataire ou le message. Conservez le texte complet, car il indique généralement la politique appliquée.
• Réponse 250 à la fin de DATA : le serveur a accepté le message pour le traiter. Un 250 antérieur, par exemple après EHLO ou MAIL FROM, ne confirme pas l'envoi complet. L'acceptation ne garantit pas non plus la remise dans la boîte de réception. Si le message arrive ensuite dans les spams, poursuivez avec le guide de délivrabilité.

Le guide officiel de dépannage de PHPMailer recommande d'utiliser des exemples à jour, de lire la transcription SMTP complète et de vérifier le réseau avant d'attribuer le problème à la bibliothèque.

Informations utiles pour reproduire l'échec

Notez la version de PHPMailer, la version de PHP, l'hôte et le port SMTP, le type de chiffrement et le message d'erreur complet. Remplacez au préalable toute adresse privée, tout jeton ou identifiant. Une capture qui ne montre que SMTP connect() failed masque généralement la réponse qui permet de trouver la cause.