Recuperação de senha não chega? Causas e como resolver

O e-mail de recuperação de senha é o mais urgente que o seu sistema manda: a pessoa está na tela de login, esperando, sem conseguir entrar. Se ele não chega em poucos segundos, ela desiste, abre um chamado ou vai para o concorrente. E você quase nunca fica sabendo.

Onde o e-mail pode ter parado#

Siga o caminho da mensagem, do seu sistema até a caixa de entrada:

1. O sistema nem enviou. Erro engolido num try/catch, fila de jobs parada, usuário que não existe com aquele e-mail.
2. O serviço de envio recusou. Remetente fora de um domínio verificado, limite do dia, endereço na lista de supressão por uma devolução antiga.
3. O servidor de destino recusou ou adiou. Resposta 5xx (recusado) ou 4xx (tente depois).
4. Foi entregue, mas no spam ou numa aba que a pessoa não olha.
5. Chegou, mas o link não funciona: expirou, já foi usado (às vezes por um filtro que visitou antes) ou aponta para o domínio errado.

Passo a passo do diagnóstico#

1. Procure o pedido nos logs do seu app, pelo e-mail da pessoa e pelo horário. Se não há registro de envio, o problema está antes do e-mail.
2. Procure a mensagem no serviço de envio. Um bom serviço mostra a linha do tempo: aceito, enviado, entregue ou recusado, com a resposta do servidor de destino.
3. Leia o código de resposta. 550 5.1.1 é endereço que não existe; 550 5.7.26 ou 5.7.515 é falta de autenticação; 421 e 451 são adiamentos. A lista completa está em Códigos de devolução SMTP explicados.
4. Se foi entregue, peça à pessoa para procurar no spam e confira a autenticação abrindo uma cópia em Mostrar original no Gmail.

As causas mais comuns, uma a uma#

O erro de envio foi engolido#

Código assim é comum, e é a "falha silenciosa" que ninguém vê:

try {
  await enviarEmailDeSenha(usuario);
} catch {
  // nada aqui
}

Registre o erro com o código e o identificador do pedido, e alerte quando a taxa de falhas subir. Se o envio vai para uma fila, monitore jobs parados e com falha.

O remetente não está autenticado#

E-mail de senha saindo pela função mail() da hospedagem, por um SMTP qualquer ou com From num domínio sem SPF, DKIM e DMARC cai no spam ou é recusado, principalmente no Outlook e no Hotmail. Veja Como configurar SPF, DKIM e DMARC.

O endereço está suprimido#

Se um e-mail antigo para aquela pessoa voltou com "usuário não existe", o serviço de envio pode ter colocado o endereço na lista de supressão, para proteger a sua reputação. Se a pessoa corrigiu a caixa dela, tire o endereço da lista e envie de novo.

O provedor está adiando#

Domínio novo ou volume repentino faz o provedor pedir "tente mais tarde" (421, 451). O serviço tenta de novo sozinho, mas o e-mail chega com atraso, e para senha atraso é quase o mesmo que não chegar. Aqueça o domínio aos poucos e mantenha o transacional separado do marketing.

O link chega quebrado#

• Domínio errado: o link foi montado com o host da requisição interna ou com localhost. Use uma URL base configurada.
• Uso único gasto por um filtro: alguns filtros corporativos visitam o link antes da pessoa. Prefira um link que abre uma página com o botão "Criar nova senha", e só o envio do formulário consome o token.
• Validade curta demais: 30 a 60 minutos costuma ser um bom equilíbrio, com a opção de pedir outro na mesma tela.

Boas práticas para o e-mail de senha#

• Envie na hora, por um caminho só de transacional, nunca no meio de uma campanha.
• Assunto curto e claro: "Redefina a sua senha do Exemplo".
• Parte em texto e o link escrito por extenso além do botão.
• Diga a validade e o que fazer se não foi a pessoa que pediu.
• Nada de propaganda nesse e-mail.
• Mensagem genérica na tela ("se houver uma conta com esse e-mail, enviamos o link"), para não revelar quem tem conta.
• Chave de idempotência quando o sistema pode repetir o pedido, para a pessoa não receber três e-mails e usar o link errado.
• Limite por pessoa (por exemplo, um pedido por minuto) para evitar abuso.

Nos frameworks mais usados#

Onde o Couryo entra#

No Couryo, a API só responde sucesso quando o e-mail entrou na fila, e cada mensagem tem uma linha do tempo com a resposta original do servidor de destino e a explicação em português ("o Hotmail recusou porque o domínio não tem DMARC; corrija assim"). O transacional fica separado do marketing, e uma pausa por excesso de devoluções nunca derruba primeiro o e-mail de senha. Veja Enviar e-mail.

Perguntas frequentes#

Por que a recuperação de senha chega no Gmail e não no Hotmail?#

A Microsoft exige autenticação completa de quem envia em volume e é mais rígida com domínios sem DMARC. Confira o SPF, o DKIM e o DMARC do remetente e o código de resposta quando a mensagem volta.

O cliente diz que não recebeu, mas o sistema mostra "enviado". E agora?#

"Enviado" no seu sistema costuma querer dizer "entregue ao serviço de envio". Procure a mensagem no serviço e veja o que o servidor de destino respondeu. Se foi aceita (250), ela está no spam ou numa aba; se foi recusada, o código explica.

Posso reenviar automaticamente quando não chega?#

Pode reenviar quando houve erro temporário, e o bom serviço já faz isso sozinho. Para a pessoa, ofereça um botão "reenviar" com intervalo mínimo e use uma chave de idempotência por pedido, para não multiplicar e-mails.

Quanto tempo o e-mail de senha deveria levar?#

Segundos. Se leva minutos, há adiamento no provedor de destino ou fila parada no seu sistema; os dois aparecem na linha do tempo da mensagem.