Configurer le fournisseur d’email Strapi 5 et les notifications de workflow

Strapi 5 intègre un plugin Email capable d’envoyer des messages transactionnels via SMTP ou des services tiers populaires. En configurant le fournisseur une seule fois et en ajoutant un petit middleware Document Service, vous pouvez notifier automatiquement les auteurs, les réviseurs ou des parties externes à chaque fois qu’une entrée passe à une étape du workflow ou est enfin publiée.

1. Pourquoi configurer l’email pour les notifications de workflow ?

L’approbation de contenu dans Strapi Enterprise repose sur les flux de révision. Les équipes ont souvent besoin d’un signal clair — généralement un email — lorsqu’un élément atteint une étape requise (par ex. Prêt à réviser) ou lorsqu’il passe en ligne. Sans automatisation, les éditeurs doivent alerter manuellement leurs collègues, ce qui annule l’intérêt d’un workflow structuré.

2. Installer le plugin Email (intégré)

Le plugin Email fait partie du cœur de Strapi 5 ; aucun package npm supplémentaire n’est nécessaire. Après avoir créé un projet Strapi (npx create-strapi-app my‑project@5.x), le plugin est déjà enregistré. Vérifiez qu’il est activé dans config/plugins.ts :

module.exports = ({ env }) => ({
  // other plugins …
  email: {
    // configuration will be added here
  },
});

Si la clé email est absente, ajoutez‑la comme indiqué ci‑dessus.

3. Choisir et configurer un fournisseur

Strapi prend en charge plusieurs fournisseurs en natif. Les deux plus courants sont SendGrid (API) et Nodemailer (SMTP). Choisissez celui qui correspond à votre infrastructure.

3.1 Configuration SendGrid

// config/plugins.ts
module.exports = ({ env }) => ({
  email: {
    config: {
      provider: 'sendgrid',
      providerOptions: {
        apiKey: env('SENDGRID_API_KEY'),
      },
      settings: {
        defaultFrom: 'no-reply@example.com',
        defaultReplyTo: 'support@example.com',
        testAddress: 'test@example.com',
      },
    },
  },
});

Définissez la variable d’environnement SENDGRID_API_KEY dans votre fichier .env.

3.2 Configuration Nodemailer (SMTP)

// config/plugins.ts
module.exports = ({ env }) => ({
  email: {
    config: {
      provider: 'nodemailer',
      providerOptions: {
        host: env('SMTP_HOST'),
        port: env.int('SMTP_PORT', 587),
        secure: false, // true for 465
        auth: {
          user: env('SMTP_USERNAME'),
          pass: env('SMTP_PASSWORD'),
        },
      },
      settings: {
        defaultFrom: 'no-reply@example.com',
        defaultReplyTo: 'support@example.com',
      },
    },
  },
});

Alimentez SMTP_HOST, SMTP_USERNAME et SMTP_PASSWORD dans le fichier .env.

3.3 Limitation de débit (optionnel)

Si vous prévoyez des pics de trafic, activez la limitation de débit intégrée :

email: {
  config: {
    // provider config …
    ratelimit: {
      enabled: true,
      interval: 5,
      max: 5,
      delayAfter: 1,
      timeWait: 1,
      prefixKey: '${userEmail}',
      whitelist: [],
    },
  },
},

Cela évite l’envoi accidentel de spams à la même adresse.

4. Tester la configuration

Un contrôle rapide peut être lancé depuis un contrôleur Strapi, une route personnalisée ou le REPL :

await strapi.plugins['email'].services.email.send({
  to: 'dev@example.com',
  subject: 'Strapi email test',
  text: 'The email plugin is working.',
  html: '<p>The email plugin is working.</p>',
});

Si le message arrive, le fournisseur est correctement configuré.

5. Flux de révision – le point de déclenchement

Strapi Enterprise vous permet de définir un pipeline d’étapes (par ex. À faire → Prêt à réviser → Approuvé → Publié). Un type de contenu peut être lié à un workflow spécifique via l’interface d’administration (Settings → Review Workflows). Le paramètre clé pour les notifications est l’étape requise pour la publication, que vous pouvez définir sur « Approved ».

6. Accrocher l’action de publication avec le middleware Document Service

Le Document Service remplace les anciens hooks de cycle de vie. Le middleware reçoit un objet context qui indique le type de contenu (uid) et l’action (action) en cours.

6.1 Créer le fichier middleware

Créez src/middlewares/publish-notifications.js :

module.exports = {
  // Appelé une fois au démarrage du serveur
  register({ strapi }) {
    strapi.documents.use(async (context, next) => {
      // Exécute d’abord l’action principale (create, update, publish, …)
      const result = await next();

      // Post‑traitement – n’agir que sur les événements de publication pour le type de contenu choisi
      if (
        context.uid === 'api::article.article' &&
        context.action === 'publish'
      ) {
        // Charge l’entrée complète, y compris l’auteur (createdBy) et les éventuels réviseurs
        const entry = await strapi
          .documents('api::article.article')
          .findOne({
            documentId: context.params.documentId,
            populate: {
              createdBy: { fields: ['email', 'firstname', 'lastname'] },
              // En supposant qu’une relation « reviewer » existe sur le modèle
              reviewer: { fields: ['email', 'firstname'] },
            },
          });

        if (entry) {
          const { createdBy, reviewer, title } = entry;
          const recipients = [];
          if (createdBy?.email) recipients.push(createdBy.email);
          if (reviewer?.email) recipients.push(reviewer.email);

          // Envoie une notification à chaque partie prenante
          await Promise.all(
            recipients.map((email) =>
              strapi.plugins['email'].services.email.send({
                to: email,
                subject: `Article published: ${title}`,
                text: `Hi,\n\nThe article “${title}” has just been published.`,
                html: `<p>Hi,</p><p>The article <strong>${title}</strong> has just been published.</p>`,
              })
            )
          );
        }
      }

      return result;
    });
  },
};

6.2 Enregistrer le middleware

Ajoutez le chemin du fichier dans config/middlewares.js (ou config/middlewares.ts si vous utilisez TypeScript) :

module.exports = [
  // …other middlewares
  { name: 'global::publish-notifications', config: {} },
];

Strapi exécutera désormais le code après chaque publication réussie d’une entrée article.

7. Envoyer des emails templatisés (polish optionnel)

Si vous préférez un contenu plus riche, utilisez sendTemplatedEmail. Placez un fichier de template Lodash sous src/email-templates/article-published.js :

module.exports = {
  subject: 'New article published: <%= entry.title %>',
  html: `<h1><%= entry.title %></h1><p>Author: <%= author.firstname %> <%= author.lastname %></p>`,
  text: 'A new article has been published: <%= entry.title %>',
};

Puis appelez‑le depuis le middleware :

const template = require('../email-templates/article-published');
await strapi.plugins['email'].services.email.sendTemplatedEmail(
  { to: email },
  template,
  { entry, author: createdBy }
);

Cela sépare la logique de mise en forme du code métier.

8. Utiliser le plugin Notifier pour des alertes dans l’admin (optionnel)

Si vous souhaitez une bannière UI en plus de l’email, installez le plugin communautaire strapi-plugin-notifier (téléchargé sous forme de zip, pas via npm). Après l’installation, configurez‑le dans config/plugins.ts :

module.exports = ({ env }) => ({
  notifier: {
    config: {
      enabled: true,
      // You can restrict broadcasting to specific roles
    },
  },
});

Depuis le middleware, vous pouvez alors diffuser un message :

await strapi
  .plugin('notifier')
  .service('notifier')
  .broadcast({
    title: 'Article Published',
    message: `The article “${title}” is now live.`,
    type: 'info',
  });

Les administrateurs verront la notification toast en haut‑à‑droite de l’interface.

9. Surcharges spécifiques à l’environnement

En développement vous pouvez utiliser un serveur SMTP local (p. ex. Mailhog) et en production un vrai fournisseur. Créez config/env/development/plugins.ts et config/env/production/plugins.ts avec le bloc email correspondant. Strapi fusionne automatiquement le fichier d’environnement avec la configuration de base.

10. Vérifier l’ensemble du flux

1. Créer un nouvel article dans l’admin UI – il démarre en état Draft.
2. Déplacer l’entrée vers Ready to review – aucun email n’est envoyé car le middleware n’écoute que publish.
3. Faire avancer le workflow jusqu’à l’étape requise (par ex. Approved).
4. Appuyer sur Publish. Le middleware s’exécute, récupère l’entrée et envoie un email à l’auteur et au réviseur. Si le plugin Notifier est installé, un toast apparaît également.
5. Consultez le Audit log (/docs/reference/audit-log) pour voir l’événement entry.publish enregistré.

11. Problèmes fréquents & dépannage

12. Prochaines étapes

• Ajouter des notifications plus granulaires (par ex. sur changement d’étape) en écoutant les événements entry.update et en vérifiant le champ workflowStage.
• Intégrer des systèmes de ticket externes via les webhooks (Admin → Settings → Webhooks) si vous avez besoin d’alertes Slack ou Jira.
• Sécuriser le service email en limitant les clés API au strict nécessaire et en les faisant pivoter régulièrement.

En configurant le plugin Email intégré et en ajoutant quelques lignes de middleware Document Service, vous transformez les flux de révision de Strapi 5 en un pipeline d’approbation entièrement automatisé. Les éditeurs obtiennent un retour immédiat, les parties prenantes restent informées, et votre processus de publication devient à la fois plus rapide et auditable.

Pour une personnalisation approfondie, consultez la documentation officielle du plugin Email et le guide des flux de révision.