Como ativar o modo debug do PHPMailer e diagnosticar erros SMTP

O modo debug do PHPMailer mostra a conversa SMTP entre a aplicação e o servidor de email. É a forma mais direta de distinguir uma falha de ligação, de TLS, de autenticação ou uma rejeição da mensagem.

Ative-o apenas enquanto reproduz o problema, com um destinatário e um conteúdo de teste. A transcrição pode incluir remetentes, destinatários, cabeçalhos e o corpo da mensagem. Os níveis 0 a 3 ocultam o utilizador e a palavra-passe SMTP, mas SMTP::DEBUG_LOWLEVEL pode mostrá-los. Não publique o resultado completo.

Ativar o nível de diagnóstico recomendado

No PHPMailer 6 e 7, importe as classes e utilize a constante SMTP::DEBUG_SERVER, equivalente ao nível 2 das versões antigas:

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

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

Integre estas opções na instância do PHPMailer que a sua aplicação já usa para enviar, depois de carregar as suas classes e antes de chamar send(). O fragmento não é um programa completo de envio: mantenha a sua configuração de servidor, autenticação e destinatários de teste.

Este nível regista tanto os comandos enviados pelo cliente como as respostas do servidor. O nível 3 acrescenta informação sobre a ligação inicial e pode ajudar quando há um timeout. O nível 4 mostra tráfego de baixo nível, pode revelar as credenciais SMTP e não deve ser utilizado exceto para analisar um problema de protocolo num ambiente controlado.

Se não quiser mostrar a transcrição na resposta HTML e o error_log do PHP já apontar para um registo privado fora de public_html, pode enviá-la para lá:

$mail->Debugoutput = 'error_log';

Não use esta saída sem verificar antes onde o PHP escreve: poderia acabar num registo partilhado ou descarregável a partir da web.

Quando terminar, desative o diagnóstico e elimine o registo quando já não for necessário:

$mail->SMTPDebug = SMTP::DEBUG_OFF;

Como ler o resultado

Procure a última resposta do servidor antes da falha:

• Não aparece uma resposta 220: reveja o nome do servidor, o DNS, a porta e possíveis bloqueios de rede.
• Falha o STARTTLS ou a validação do certificado: verifique se o TLS e a porta coincidem, se a extensão OpenSSL está ativa e se o sistema tem certificados CA atualizados. Não desative a verificação TLS para ocultar o erro.
• Resposta 535 ou semelhante: o servidor rejeitou a autenticação. Verifique o utilizador completo, a palavra-passe e o método admitido pelo fornecedor.
• Resposta 550 ou 5.7.x: o servidor recebeu o pedido, mas rejeitou o remetente, o destinatário ou a mensagem. Guarde o texto completo porque costuma indicar a política aplicada.
• Resposta 250 ao terminar DATA: o servidor aceitou a mensagem para processamento. Um 250 anterior, por exemplo depois de EHLO ou MAIL FROM, não confirma o envio completo. A aceitação também não garante a entrega na caixa de entrada. Se depois aparecer no spam, continue com o guia de entregabilidade.

O guia oficial de resolução de problemas do PHPMailer recomenda usar exemplos atuais, ler a transcrição SMTP completa e verificar a rede antes de atribuir o problema à biblioteca.

Dados úteis para reproduzir a falha

Guarde a versão do PHPMailer, a versão do PHP, o host e a porta SMTP, o tipo de cifragem e a mensagem de erro completa. Substitua antes qualquer endereço privado, token ou credencial. Uma captura de ecrã que só mostre SMTP connect() failed oculta normalmente a resposta que permite encontrar a causa.