Modèles d’e-mails

Logto propose différents modèles pour personnaliser le contenu des e-mails, qui sont classés en fonction de leurs cas d’utilisation.

Il est fortement recommandé d’utiliser des modèles différents selon les scénarios. Sinon, les utilisateurs pourraient recevoir un contenu d’e-mail qui ne correspond pas à l’opération en cours, ce qui pourrait prêter à confusion. Si certains modèles nécessaires ne sont pas configurés, cela peut entraîner des erreurs de flux qui dépendent de ce modèle et affecter le bon déroulement de l’activité.

Options de personnalisation des modèles d’e-mails

Logto propose trois approches distinctes pour la gestion des modèles d’e-mails :

1. Personnaliser les modèles dans Logto

   • Connecteurs :
     • SMTP
     • SendGrid
     • Mailgun
     • AWS Direct Mail
     • Aliyun Direct Mail
   • Fonctionnalités :
     • ✅ Insérer de manière flexible diverses variables dans les modèles
     • ✅ Créer des modèles personnalisés multilingues via les Management APIs
     • ✅ Édition complète des modèles dans Logto

2. Personnaliser les modèles sur la plateforme du fournisseur

   • Connecteurs :
     • Postmark
     • HTTP Email
   • Fonctionnalités :
     • ✅ Transmettre des variables à la plateforme du fournisseur
     • ✅ Transmettre le paramètre locale à la plateforme du fournisseur pour la localisation
     • ✅ Édition complète des modèles dans le tableau de bord du fournisseur (Utiliser les Management APIs de Logto)

3. Modèles prédéfinis (non personnalisables)

   • Connecteur :
     • Service d’e-mail intégré Logto
   • Fonctionnalités :
     • ✅ Prise en charge native des variables
     • ❌ Modèles multilingues (Bientôt disponible)
     • ❌ Modification du modèle / de l’interface désactivée

Types de modèles d’e-mails

usageType	Scénario	Variables
SignIn	Les utilisateurs se connectent en utilisant leur e-mail et vérifient en saisissant un code de vérification au lieu d’un mot de passe.	code: string application: ApplicationInfo organization?: OrganizationInfo
Register	Les utilisateurs créent un compte en utilisant leur e-mail et le vérifient en saisissant un code de vérification envoyé par Logto à leur adresse e-mail.	code: string application: ApplicationInfo organization?: OrganizationInfo
ForgotPassword	Si les utilisateurs oublient leur mot de passe lors de la connexion, ils peuvent choisir de vérifier leur identité via l’e-mail pour réinitialiser le mot de passe.	code: string application: ApplicationInfo organization?: OrganizationInfo
Generic	Ce modèle peut être utilisé comme option de secours générale pour divers scénarios, y compris le test de la configuration du connecteur, la vérification ou la liaison de l’e-mail après la connexion, etc.	code: string
OrganizationInvitation	Utilisez ce modèle pour envoyer aux utilisateurs un lien d’invitation afin de rejoindre l’organisation.	link: string organization: OrganizationInfo inviter?: UserInfo
UserPermissionValidation	Lors de l’utilisation de l’application, certaines opérations à risque élevé ou à niveau de risque relativement élevé peuvent nécessiter une vérification utilisateur supplémentaire, telles que les virements bancaires, la suppression de ressources en cours d’utilisation ou l’annulation d’abonnements. Le modèle UserPermissionValidation permet de définir le contenu de l’e-mail de vérification reçu par les utilisateurs dans ces situations.	code: string user: UserInfo application?: ApplicationInfo
BindNewIdentifier	Lorsqu’un utilisateur modifie son profil, il peut lier une adresse e-mail à son compte actuel. Dans ce cas, le modèle BindNewIdentifier permet de personnaliser le contenu de l’e-mail de vérification.	code: string user: UserInfo application?: ApplicationInfo
MfaVerification	Lorsque l’email MFA est activé, ce modèle est utilisé pour envoyer des codes de vérification aux utilisateurs lors du processus d’authentification multi-facteurs.	code: string application: ApplicationInfo organization?: OrganizationInfo
BindMfa	Lorsque l’email MFA est activé, ce modèle est utilisé pour configurer le code de vérification par e-mail pour la MFA. Les utilisateurs reçoivent ce code de vérification lorsqu’ils lient ou configurent leur adresse e-mail comme facteur MFA pour leur compte.	code: string user: UserInfo application?: ApplicationInfo

Variables des modèles d’e-mails

Code

Le code de vérification que les utilisateurs doivent saisir pour terminer le processus de vérification. Disponible dans les modèles SignIn, Register, ForgotPassword, Generic, UserPermissionValidation et BindNewIdentifier.

• Les codes de vérification expirent au bout de 10 minutes. Nous ne prenons actuellement pas en charge la personnalisation de la durée d’expiration du code de vérification.
• Un espace réservé {{code}} doit être prévu dans le modèle. Lors de l’envoi d’un code de vérification, un code généré aléatoirement remplacera cet espace réservé avant l’envoi de l’e-mail à l’utilisateur.

ApplicationInfo

Les informations publiques de l’application cliente avec laquelle l’utilisateur interagit. Disponible dans les modèles SignIn, Register, ForgotPassword, UserPermissionValidation et BindNewIdentifier.

type ApplicationInfo = {
  id: string;
  name: string;
  displayName?: string;
  branding?: {
    logoUrl?: string;
    darkLogoUrl?: string;
    favicon?: string;
    darkFavicon?: string;
  };
};

• Tous les champs imbriqués de l’application peuvent être utilisés dans les modèles via la notation par points. Par exemple, {{application.name}} sera remplacé par le nom réel de l’application issu de votre configuration.
• Si la variable racine application n’est pas fournie, l’espace réservé handlebars sera ignoré et non remplacé.
• Si l’objet application fourni ne contient pas les champs requis ou si la valeur est indéfinie, l’espace réservé handlebars sera remplacé par une chaîne vide. Par exemple, {{application.foo.bar}} sera remplacé par ``.

OrganizationInfo

Les informations publiques de l’organisation avec laquelle l’utilisateur interagit.

type OrganizationInfo = {
  id: string;
  name: string;
  branding?: {
    logoUrl?: string;
    darkLogoUrl?: string;
    favicon?: string;
    darkFavicon?: string;
  };
};

• Pour les modèles SignIn, Register et ForgotPassword, la variable organization est optionnelle. Disponible uniquement lorsque le paramètre organization_id est présent dans la requête d’autorisation. Voir Personnalisation spécifique à l’organisation pour plus de détails.
• Pour le modèle OrganizationInvitation, la variable organization est obligatoire.

UserInfo

Les informations publiques de l’utilisateur à qui l’e-mail est envoyé. Disponible dans les modèles UserPermissionValidation, BindNewIdentifier et OrganizationInvitation.

type UserInfo = {
  id: string;
  name?: string;
  username?: string;
  primaryEmail?: string;
  primaryPhone?: string;
  avatar?: string;
  profile?: Profile;
};

• Consultez profile pour plus de détails sur le type Profile.
• La variable user est obligatoire pour les modèles UserPermissionValidation et BindNewIdentifier.
• La variable inviter est optionnelle pour le modèle OrganizationInvitation. Disponible uniquement lorsque inviterId est fourni dans la requête d’invitation à l’organisation.

UI Locales

La valeur originale de ui_locales fournie dans la requête d’authentification OIDC qui a initié l’interaction en cours.

• Type : string (liste d’étiquettes de langue BCP 47 séparées par des espaces, selon la spécification OIDC), par exemple : "fr-CA fr en".
• Disponibilité : Présente lorsque l’interaction de connexion en cours a été initiée avec ui_locales. Si non fourni, cette variable est omise.
• Utilisation typique : À inclure dans le contenu ou l’objet de l’e-mail pour enregistrer les langues d’interface demandées par l’utilisateur à des fins de support i18n ou d’audit, par exemple Langues demandées : {{uiLocales}}.

Exemples de modèles d’e-mails

Vous pouvez utiliser les exemples de code de modèles d’e-mails fournis comme point de départ pour personnaliser votre interface utilisateur. Pour créer une interface utilisateur similaire à ce qui suit :

Les modèles d’e-mails utilisés dans les différents scénarios de Logto sont très similaires, la seule différence étant la description du scénario et de l’opération en cours.

Nous ne montrons pas ici le code HTML de tous les modèles en détail. Nous prenons uniquement le scénario de connexion comme exemple. Les autres scénarios, tels que l’inscription et la réinitialisation du mot de passe, sont très similaires à l’exemple ci-dessous.

Les utilisateurs peuvent se référer à ce modèle et l’ajuster selon leur situation réelle.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vérifiez votre e-mail pour vous connecter</title>
    <style>
      .auth-service-by:hover .mini-logo {
        display: none !important;
      }
      .auth-service-by:hover .mini-logo-color {
        display: block !important;
      }
      body {
        font-family:
          'SF Pro Text',
          -apple-system,
          system-ui,
          BlinkMacSystemFont,
          'Segoe UI',
          Roboto,
          Arial,
          sans-serif;
        -webkit-font-smoothing: antialiased;
        -moz-osx-font-smoothing: grayscale;
        font-smooth: always;
        background-color: #fff;
        color: #191c1d;
        max-width: 640px;
        padding: 32px 0;
        font-size: 14px;
        font-weight: 400;
        line-height: 20px;
      }
      h1 {
        font-size: 24px;
        font-weight: 700;
        line-height: 32px;
        margin-top: 32px;
      }
      .verification-code {
        margin: 20px 0;
        background: #eff1f1;
        border-radius: 12px;
        padding: 36px;
        font-size: 32px;
        font-weight: 600;
        line-height: 40px;
      }
      .footer {
        text-align: center;
        color: #a9acac;
        margin-top: 48px;
      }
    </style>
  </head>
  <body>
    <div style="max-width: 698px; border-radius: 16px; border: 1px solid #E0E3E3;">
      <div style="padding: 0 24px;">
        <center>
          <img src="{{logoUrl}}" alt="Logo" width="auto" height="40" />
          <h1>Vérifiez votre e-mail pour vous connecter</h1>
          <p>
            Nous avons reçu une tentative de connexion avec le code suivant. Veuillez le saisir sur
            la page que vous avez ouverte pour terminer le processus de connexion.
          </p>
          <div class="verification-code">000000</div>
          <p style="color: #747778;">
            Si vous n’avez pas tenté de vous connecter mais que vous avez reçu cet e-mail, veuillez
            l’ignorer. Le code restera actif pendant 10 minutes.
          </p>
          <hr style="margin: 64px 0 24px; max-width: 420px;" />
          <p style="color: #747778; margin: 16px 0 0;">{{companyInfo}}</p>
        </center>
      </div>
    </div>
    <div class="footer">
      <hr />
      <p style="font-size: 14px; line-height: 20px; margin: 20px 0;">
        <a href="https://logto.io" style="color: #A9ACAC; text-decoration: underline;">Logto</a> :
        La meilleure infrastructure d’identité pour les développeurs.
      </p>
      <table style="margin: 0 auto; width: auto; border-spacing: 0;">
        <tbody>
          <tr>
            <td style="vertical-align: middle;">
              <a href="{{discordServerUrl}}" style="display: block; margin: 0 12px;">
                <img src="{{discordLogoUrl}}" style="width: 20px;" />
              </a>
            </td>
            <td style="vertical-align: middle;">
              <a href="{{githubUrl}}" style="display: block; margin: 0 12px;">
                <img src="{{githubLogoUrl}}" style="width: 20px;" />
              </a>
            </td>
            <td style="vertical-align: middle;">
              <a href="{{twitterUrl}}" style="display: block; margin: 0 12px;">
                <img src="{{twitterLogoUrl}}" style="width: 20px;" />
              </a>
            </td>
            <td style="vertical-align: middle;">
              <a href="{{mailToUrl}}" style="display: block; margin: 0 12px;">
                <img src="{{emailIconUrl}}" style="width: 20px;" />
              </a>
            </td>
          </tr>
        </tbody>
      </table>
      <p style="font-size: 12px; line-height: 16px;">
        © Silverhand, Inc., 2810 North Church Street, Wilmington, DE 19802
      </p>
      <p style="color: #A9ACAC; font-size: 12px; line-height: 16px;">
        Des questions ou besoin d’aide ?
        <a href="{{mailToUrl}}" style="color: #A9ACAC; text-decoration: underline;"
          >Contactez-nous</a
        >
      </p>
    </div>
  </body>
</html>

Vous pouvez ensuite échapper le code HTML ci-dessus et l’ajouter au champ "Template" du connecteur dans la configuration comme suit (en supposant l’utilisation du connecteur SendGrid) :

{
  "subject": "<sign-in-template-subject>",
  "content": "<table cellpadding=\"0\" cellspacing=\"0\" ...",
  "usageType": "SignIn",
  "type": "text/html"
}

Localisation des modèles d’e-mails

Modèles d’e-mails personnalisés pour différentes langues

Logto prend en charge la création de modèles d’e-mails personnalisés pour différentes langues via les Management API. Vous pouvez créer des modèles d’e-mails personnalisés pour différentes langues et types de modèles afin d’offrir une expérience localisée à vos utilisateurs.

type EmailTemplate = {
  languageTag: string;
  templateType: TemplateType;
  details: {
    subject: string;
    content: string;
    contentType?: 'text/html' | 'text/plain';
    replyTo?: string;
    sendFrom?: string;
  };
};

Champ	Description
subject	Le modèle d’objet de l’e-mail.
content	Le modèle de contenu de l’e-mail.
contentType	Certains fournisseurs d’e-mails peuvent afficher les modèles différemment selon le type de contenu (par exemple, Sendgrid, Mailgun). Utilisez ce champ pour spécifier le type de contenu du modèle d’e-mail.
replyTo	L’adresse e-mail qui recevra les réponses à l’e-mail. Vérifiez auprès de votre fournisseur d’e-mails si ce champ est pris en charge.
sendFrom	Le nom d’expéditeur de l’e-mail. Vérifiez auprès de votre fournisseur d’e-mails si ce champ est pris en charge.

Une fois les modèles d’e-mails créés, Logto sélectionnera automatiquement le modèle d’e-mail approprié en résolvant d’abord la préférence de langue de l’utilisateur, puis en choisissant le modèle le plus adapté.

La préférence de langue est résolue dans l’ordre suivant :

1. Si la requête d’authentification OIDC inclut ui_locales, Logto sélectionne la première étiquette de ui_locales prise en charge par la bibliothèque de langues de votre tenant. Voir ui_locales pour plus de détails.
2. Sinon, pour les Experience APIs côté client et les User Account APIs, Logto utilise l’en-tête Accept-Language. Pour les Management APIs (comme Invitation à l’organisation), vous pouvez spécifier la langue via le champ locale dans messagePayload.
3. Si aucun n’est fourni, Logto utilise la langue par défaut du tenant configurée dans l’Expérience de connexion. Consultez Langues localisées pour les détails de configuration.

Sélection du modèle :

4. Avec la langue résolue, Logto recherche un modèle d’e-mail personnalisé correspondant via languageTag et templateType. Si trouvé, ce modèle est utilisé.
5. Si aucun modèle personnalisé correspondant n’existe, Logto utilise le modèle d’e-mail par défaut défini dans la configuration du connecteur.

Connecteurs d’e-mails pris en charge :

• Aliyun Direct Mail
• Amazon Direct Mail
• Mailgun
• SendGrid
• SMTP

Localisation des modèles d’e-mails côté fournisseur

Pour les développeurs qui utilisent des connecteurs d’e-mails dont les modèles sont gérés par le fournisseur :

• HTTP Email
• Postmark

La langue préférée de l’utilisateur sera transmise au fournisseur via le paramètre locale dans la charge utile du modèle. Vous pouvez créer plusieurs modèles pour différentes langues dans la console du fournisseur et utiliser le paramètre locale pour spécifier la préférence de langue.

remarque:

Lorsque ui_locales est présent dans la requête d’authentification, les variables locale et uiLocales seront toutes deux disponibles dans le contexte du modèle. La variable uiLocales contient la valeur originale de ui_locales de la requête d’authentification, tandis que la variable locale est déterminée en fonction de la première étiquette prise en charge résolue à partir de ui_locales. Si ui_locales n’est pas fourni, locale suit les règles de résolution standard (par exemple, Accept-Language, puis langue par défaut).

FAQ

Comment utiliser des services tiers de modèles d’e-mails si les modèles ne sont pas configurés dans Logto ?

Vous pouvez ajouter un nouvel endpoint à votre propre service web pour envoyer des e-mails, puis utiliser le connecteur HTTP email de Logto pour appeler l’endpoint que vous maintenez.

Cela vous permet de gérer la logique des modèles d’e-mails sur votre propre serveur.

Existe-t-il un moyen d’utiliser l’e-mail Logto pour envoyer à nos utilisateurs un "e-mail de bienvenue" personnalisé ?

Nous proposons la fonctionnalité Webhook. Vous pouvez implémenter votre propre endpoint API pour recevoir l’événement User.Created envoyé par le Webhook Logto, et ajouter la logique d’envoi d’un e-mail de bienvenue personnalisé dans le gestionnaire du webhook.

Le connecteur e-mail Logto ne fournit que des notifications e-mail pour les événements liés au flux d’authentification. Les e-mails de bienvenue sont un besoin métier et ne sont pas pris en charge nativement par le connecteur e-mail, mais cette fonctionnalité peut être obtenue via les Webhooks.

Ressources associées

Maximiser la délivrabilité des e-mails de vérification pour garantir l’accès utilisateur