Migrer son SMTP de Gmail vers un hébergeur pro : les pièges à éviter

Utiliser Gmail comme serveur SMTP pour l'envoi d'emails transactionnels est une solution courante en développement, notamment avec NextAuth et son provider Email. Mais dès qu'un projet passe en production avec un nom de domaine personnalisé, la migration vers un hébergeur mail dédié (OVH, Infomaniak, SendGrid...) devient nécessaire. Voici les erreurs classiques rencontrées lors de cette transition, et comment les éviter.

Le piège des configurations dupliquées

Le problème le plus fréquent n'est pas la nouvelle configuration elle-même, mais les anciennes qui traînent. Un projet grandit souvent avec plusieurs fichiers qui définissent chacun leur propre client SMTP : une route API, un fichier de librairie, parfois un script de test oublié. Résultat : on modifie le fichier .env, on redémarre le serveur, et l'erreur persiste — parce qu'un autre fichier, quelque part, a le nom de l'ancien serveur codé en dur.

La solution est simple mais demande de la discipline : centraliser toute la configuration d'authentification dans un seul fichier, importé partout où c'est nécessaire. Une seule source de vérité évite les divergences silencieuses.

Port et sécurité : 465 n'est pas 587

Les hébergeurs SMTP n'utilisent pas tous les mêmes conventions. Le port 587 fonctionne généralement avec le protocole STARTTLS, où la connexion démarre en clair puis bascule vers une connexion chiffrée. Le port 465, en revanche, attend une connexion chiffrée dès le départ (SSL/TLS implicite).

Dans la configuration Nodemailer, cela se traduit par un paramètre simple mais facile à oublier :

Avec le port 465, l'option secure doit être activée. Avec le port 587, elle doit rester désactivée. Une mauvaise combinaison entraîne des erreurs de connexion difficiles à diagnostiquer, car le message d'erreur ne pointe pas toujours clairement vers cette cause.

Identifiants : bien distinguer authentification et expéditeur

Une confusion fréquente consiste à mélanger l'adresse d'expédition affichée dans l'email (from) avec l'identifiant utilisé pour l'authentification SMTP (auth.user). Ces deux valeurs sont souvent identiques, mais ce n'est pas systématique selon les hébergeurs, et les nommer différemment dans le code évite bien des erreurs de débogage.

Toujours vérifier le cache de build

Un dernier piège, spécifique aux frameworks modernes comme Next.js : après une modification du fichier d'environnement ou du code d'authentification, le cache de build peut conserver d'anciennes versions compilées. Un simple redémarrage du serveur de développement ne suffit pas toujours ; il faut parfois supprimer le dossier de build généré pour forcer une reconstruction complète.

En résumé

Une migration SMTP réussie repose sur trois vérifications systématiques : une seule configuration centralisée, la bonne combinaison port/sécurité pour l'hébergeur choisi, et un cache de build proprement nettoyé après chaque changement. Trois minutes de vérification qui évitent des heures de débogage.