Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Envoyer des emails avec NestJS (Nodemailer)

Cette leçon met en place l'envoi d'e-mails dans une API NestJS. Un MailService global encapsule Nodemailer, avec une configuration SMTP lue dans .env et une vérification au démarrage. Les essais utili...

0 chapitres 0 QCM Accès gratuit
Envoyer des emails avec NestJS (Nodemailer)

À propos de ce cours

Cette leçon met en place l'envoi d'e-mails dans une API NestJS. Un MailService global encapsule Nodemailer, avec une configuration SMTP lue dans .env et une vérification au démarrage. Les essais utilisent MailDev, un faux serveur SMTP qui capture les messages sans rien envoyer. L'exécution montre un e-mail HTML avec pièce jointe, l'échappement des données saisies par l'utilisateur, puis le comportement quand le serveur SMTP est arrêté : erreur 500 si l'on attend l'envoi, inscription réussie et erreur journalisée sinon. La configuration Gmail est expliquée. Activités corrigées.

Objectifs de la leçon

  • Configurer Nodemailer dans un service NestJS réutilisable.
  • Tester les e-mails sans rien envoyer, avec MailDev.
  • Construire un e-mail HTML sûr, avec pièce jointe.
  • Gérer une panne du serveur SMTP sans pénaliser l'utilisateur.
Le principe

Une API n'envoie pas elle-même les e-mails : elle les confie à un serveur SMTP (celui de Gmail, d'un hébergeur, ou d'un service spécialisé comme Brevo). La bibliothèque Nodemailer parle le protocole SMTP. Pendant le développement, on utilise un faux serveur SMTP qui garde les messages pour qu'on les consulte : aucun e-mail n'arrive par erreur chez un vrai stagiaire.

Envoyer un e-mail depuis NestJS

Le même code envoie vers MailDev en développement et vers un vrai serveur SMTP en production : seul le .env change.

npm install nodemailer
npm install -D @types/nodemailer

# Faux serveur SMTP pour le développement (dans un autre terminal)
npx maildev            # SMTP sur le port 1025, boîte de réception sur http://localhost:1080
Configuration et service

📄 .env

# Développement : MailDev (npx maildev) capture tous les e-mails, rien ne part vraiment
MAIL_HOTE=127.0.0.1
MAIL_PORT=1025
MAIL_SECURISE=false
MAIL_UTILISATEUR=
MAIL_MOT_DE_PASSE=
MAIL_EXPEDITEUR="Centre de formation <ne-pas-repondre@formation.tn>"

📄 src/mail/mail.service.ts

import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { createTransport, SendMailOptions, Transporter } from 'nodemailer';

export interface Message {
  a: string | string[];
  sujet: string;
  html: string;
  texte?: string;
  piecesJointes?: SendMailOptions['attachments'];
}

@Injectable()
export class MailService implements OnModuleInit {
  private readonly logger = new Logger(MailService.name);
  private readonly transporteur: Transporter;
  private readonly expediteur: string;

  constructor(config: ConfigService) {
    const utilisateur = config.get<string>('MAIL_UTILISATEUR');
    this.transporteur = createTransport({
      host: config.getOrThrow<string>('MAIL_HOTE'),
      port: Number(config.getOrThrow('MAIL_PORT')),
      secure: config.get('MAIL_SECURISE') === 'true',          // true pour le port 465 (SSL/TLS)
      auth: utilisateur ? { user: utilisateur, pass: config.get<string>('MAIL_MOT_DE_PASSE') } : undefined,
      connectionTimeout: 5000,
    });
    this.expediteur = config.getOrThrow<string>('MAIL_EXPEDITEUR');
  }

  // Au démarrage : on vérifie la connexion, sans empêcher l'application de démarrer
  async onModuleInit() {
    try {
      await this.transporteur.verify();
      console.log('[MailService] serveur SMTP joignable');
    } catch (e) {
      console.log('[MailService] serveur SMTP injoignable : ' + (e as Error).message);
    }
  }

  async envoyer(m: Message) {
    const info = await this.transporteur.sendMail({
      from: this.expediteur,
      to: m.a,
      subject: m.sujet,
      html: m.html,
      text: m.texte ?? m.html.replace(/<[^>]+>/g, ''),    // version texte pour les clients sans HTML
      attachments: m.piecesJointes,
    });
    return info.messageId as string;
  }
}

📄 src/mail/mail.module.ts

import { Global, Module } from '@nestjs/common';
import { MailService } from './mail.service';

@Global()                       // utilisable dans tous les modules sans réimporter MailModule
@Module({ providers: [MailService], exports: [MailService] })
export class MailModule {}
  • Le transporteur est créé une seule fois, dans le constructeur, à partir de la configuration (chapitre 10).
  • onModuleInit (leçon 7.5) vérifie la connexion au démarrage et l'affiche, sans empêcher l'application de démarrer si le serveur SMTP est indisponible.
  • @Global(): le service est disponible dans tous les modules dès que MailModule est importé une fois dans AppModule.
  • Une version texte est toujours fournie (text) : certains clients de messagerie et les filtres anti-spam en tiennent compte.
Un modèle d'e-mail sûr

📄 src/mail/modeles.ts

// Échapper toute donnée venant de l'utilisateur avant de l'insérer dans du HTML
export const echapper = (s: string) =>
  s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]!);

const gabarit = (titre: string, contenu: string) => `<!doctype html>
<html lang="fr"><body style="font-family:Arial,sans-serif;background:#f4f6f8;padding:24px">
  <div style="max-width:560px;margin:auto;background:#fff;border-radius:8px;padding:24px">
    <h2 style="color:#e0234e;margin-top:0">${titre}</h2>
    ${contenu}
    <p style="color:#888;font-size:12px">Centre de formation, message automatique, merci de ne pas répondre.</p>
  </div>
</body></html>`;

export function bienvenue(nom: string, formation: string) {
  return {
    sujet: `Bienvenue ${nom} !`,
    html: gabarit('Inscription confirmée', `<p>Bonjour <strong>${echapper(nom)}</strong>,</p>
    <p>Votre inscription à la formation <strong>${echapper(formation)}</strong> est confirmée.</p>
    <p>Vous trouverez votre attestation en pièce jointe.</p>`),
  };
}

Le nom et la formation viennent de l'utilisateur : on les échappe avant de les insérer dans le HTML, comme Angular le fait dans un template. Sans cela, un nom contenant du HTML s'afficherait comme du HTML dans l'e-mail (liens piégés, faux formulaires).

📄 src/inscriptions.controller.ts

import { Body, Controller, Logger, Post } from '@nestjs/common';
import { IsEmail, IsString, Length } from 'class-validator';
import { PDF } from './faux-fichiers';
import { MailService } from './mail/mail.service';
import { bienvenue } from './mail/modeles';

export class InscriptionDto {
  @IsString() @Length(2, 60) nom: string;
  @IsEmail() email: string;
  @IsString() formation: string;
}

@Controller('inscriptions')
export class InscriptionsController {
  private readonly logger = new Logger('Inscriptions');
  constructor(private readonly mail: MailService) {}

  // Version 1 : on attend l'envoi (la réponse dépend du serveur SMTP)
  @Post('attendre')
  async attendre(@Body() dto: InscriptionDto) {
    const { sujet, html } = bienvenue(dto.nom, dto.formation);
    const messageId = await this.mail.envoyer({
      a: dto.email, sujet, html,
      piecesJointes: [{ filename: 'attestation.pdf', content: PDF, contentType: 'application/pdf' }],
    });
    return { inscrit: dto.email, messageId };
  }

  // Version 2 : on n'attend pas ; un échec d'envoi est journalisé, l'inscription reste valide
  @Post()
  inscrire(@Body() dto: InscriptionDto) {
    const { sujet, html } = bienvenue(dto.nom, dto.formation);
    this.mail.envoyer({ a: dto.email, sujet, html })
      .catch((e: Error) => console.log(`[Inscriptions] e-mail non envoyé à ${dto.email} : ${e.message}`));
    return { inscrit: dto.email, email: 'en cours d\'envoi' };
  }
}

Résultat réellement obtenu :

[MailService] serveur SMTP joignable
POST /api/inscriptions/attendre → 201 {"inscrit":"sami@exemple.tn","messageId":"<6f43bde4-d7ad-3228-a671-f60786ae854d@formation.tn>"}
POST /api/inscriptions → 201 {"inscrit":"pirate@exemple.tn","email":"en cours d'envoi"}

— Boîte de réception de MailDev (GET http://127.0.0.1:1080/api/email)
De : Centre de formation <ne-pas-repondre@formation.tn> | À : sami@exemple.tn | Sujet : Bienvenue Sami Ben Ali !
   pièces jointes : attestation.pdf (application/pdf, 209 o)
   extrait HTML : <p>Bonjour <strong>Sami Ben Ali</strong>,</p> <p>Votre inscription à la formation <strong>Développement web</strong> est confirmée.</p>
De : Centre de formation <ne-pas-repondre@formation.tn> | À : pirate@exemple.tn | Sujet : Bienvenue <script>alert(1)</script> !
   pièces jointes : aucune
   extrait HTML : <p>Bonjour <strong>&lt;script&gt;alert(1)&lt;/script&gt;</strong>,</p> <p>Votre inscription à la formation <strong>Réseaux &lt;b&gt;</strong> est confirmée.</p>

L'e-mail reçu dans MailDev

L'e-mail capturé par MailDev (http://localhost:1080) : expéditeur, destinataire, pièce jointe et rendu HTML.

Lecture
  • Le premier e-mail est complet : expéditeur du .env, HTML, pièce jointe PDF.
  • Pour le second, le nom <script>alert(1)</script> est devenu du texte inoffensif (&lt;script&gt;) dans le HTML. Le sujet, lui, est du texte brut : il s'affiche tel quel, sans danger.
Et si le serveur SMTP est en panne ?

Même application, serveur SMTP arrêté (port 1026) :

$ serveur SMTP arrêté (port 1026)
[MailService] serveur SMTP injoignable : connect ECONNREFUSED 127.0.0.1:1026
POST /api/inscriptions/attendre → 500 {"statusCode":500,"message":"Internal server error"}  [durée: 57 ms]
POST /api/inscriptions → 201 {"inscrit":"ines@exemple.tn","email":"en cours d'envoi"}  [durée: 8 ms]
[Inscriptions] e-mail non envoyé à ines@exemple.tn : connect ECONNREFUSED 127.0.0.1:1026
  • Avec await, l'échec de l'e-mail fait échouer toute la requête (500) : l'utilisateur croit que son inscription a échoué, alors qu'elle est peut-être enregistrée.
  • Sans await, avec un .catch() qui journalise : l'inscription réussit (201, en 8 ms au lieu d'attendre le serveur SMTP) et l'erreur est notée pour l'administrateur.

Toujours un .catch() sur une promesse qu'on n'attend pas : une promesse rejetée sans catch peut arrêter le processus Node.js. Pour un envoi fiable (nouvelles tentatives, file d'attente qui survit à un redémarrage), on utilise une file de tâches comme BullMQ avec Redis. La leçon 15.6 montre une autre façon de découpler l'envoi : les événements.

En production
# Production avec Gmail : mot de passe d'application (compte Google avec validation en deux étapes)
MAIL_HOTE=smtp.gmail.com
MAIL_PORT=465
MAIL_SECURISE=true
MAIL_UTILISATEUR=centre.formation@gmail.com
MAIL_MOT_DE_PASSE=abcdefghijklmnop          # mot de passe d'application de 16 lettres, pas votre mot de passe Google
MAIL_EXPEDITEUR="Centre de formation <centre.formation@gmail.com>" 
  • Gmail exige un mot de passe d'application (Compte Google → Sécurité → Validation en deux étapes → Mots de passe des applications). Gmail limite aussi le nombre d'envois par jour : pour des envois en nombre, préférez un service transactionnel (Brevo, Mailjet, Amazon SES…).
  • Port 465 avec secure: true (TLS dès la connexion) ou port 587 avec secure: false (STARTTLS).
  • Pour de nombreux modèles, un moteur de templates (Handlebars, MJML) ou le paquet @nestjs-modules/mailer évite d'écrire le HTML à la main.
Activités

Activité 1 Réinitialisation du mot de passe

Dans le projet du TP 8, ajoutez POST /api/auth/mot-de-passe-oublie (e-mail) : générez un jeton aléatoire (randomBytes(32).toString('hex')), stockez son empreinte SHA-256 et une date d'expiration (30 minutes), et envoyez un lien …/reinitialiser?jeton=…. La réponse doit être identique que l'e-mail existe ou non. Pourquoi ?

Voir le corrigé

Une réponse identique (« Si un compte existe, un e-mail a été envoyé ») empêche de découvrir quels e-mails ont un compte (leçon 13.3). On stocke l'empreinte, pas le jeton, pour la même raison que les refresh tokens (leçon 13.8). La route POST /api/auth/reinitialiser vérifie l'empreinte et l'expiration, change le mot de passe, efface le jeton et ferme les sessions. Envoyez l'e-mail sans l'attendre, avec un .catch().

Activité 2 Configuration validée

Ajoutez les variables MAIL_* au schéma de validation de la configuration (chapitre 10) : hôte obligatoire, port numérique, MAIL_SECURISE booléen, expéditeur obligatoire.

Voir le corrigé
MAIL_HOTE: Joi.string().required(),
MAIL_PORT: Joi.number().port().default(587),
MAIL_SECURISE: Joi.boolean().default(false),
MAIL_UTILISATEUR: Joi.string().allow('').default(''),
MAIL_MOT_DE_PASSE: Joi.string().allow('').default(''),
MAIL_EXPEDITEUR: Joi.string().required(),

Avec Joi, MAIL_SECURISE devient un vrai booléen : dans MailService, utilisez alors config.get<boolean>('MAIL_SECURISE') au lieu de comparer à la chaîne 'true'.

Activité 3 Un e-mail de test

Ajoutez une route réservée à l'admin, POST /api/admin/email-test, qui envoie un e-mail à l'adresse de l'admin connecté et renvoie le messageId. Testez-la avec MailDev, puis avec le serveur SMTP arrêté. Quel statut renvoyer en cas d'échec ?

Voir le corrigé

Ici, l'envoi est le but de la requête : on l'attend, et en cas d'échec on renvoie une erreur explicite, par exemple 503 Service Unavailable avec « Serveur de messagerie indisponible » (ServiceUnavailableException), plutôt qu'une 500 générique.

Activité 4 Repérer les erreurs

Trouvez les trois problèmes de ce code.

@Post()
async inscrire(@Body() dto: InscriptionDto) {
  const transporteur = createTransport({ host: 'smtp.gmail.com', port: 465, secure: true,
    auth: { user: 'centre@gmail.com', pass: 'MonMotDePasse2026' } });
  await transporteur.sendMail({ to: dto.email, subject: 'Bienvenue', html: `<p>Bonjour ${dto.nom}</p>` });
  return this.service.inscrire(dto);
}
Voir le corrigé

(1) Identifiants écrits dans le code : ils finiront sur GitHub ; ils doivent venir du .env. (2) dto.nom inséré sans échappement dans le HTML. (3) L'e-mail est envoyé et attendu avant l'inscription : en cas de panne SMTP, pas d'inscription ; et si l'inscription échoue ensuite, un e-mail de bienvenue a été envoyé pour rien. On inscrit d'abord, puis on envoie sans bloquer. Enfin, créer un transporteur à chaque requête est inutilement coûteux : un service le crée une fois.

À retenir

  • Nodemailer + un MailService global ; configuration SMTP dans .env.
  • En développement, MailDev (npx maildev) capture les e-mails : rien ne part.
  • Échapper les données de l'utilisateur dans le HTML ; fournir aussi une version texte.
  • Ne pas faire dépendre la réponse de l'envoi : envoyer sans attendre, avec un .catch() qui journalise.
  • Gmail : mot de passe d'application, port 465 secure ou 587 ; pour les gros volumes, un service transactionnel.

Cet article vous a-t-il aidé ?