Zum Hauptinhalt springen

E-Mail-Vorlagen

Logto stellt verschiedene Vorlagen zur Anpassung von E-Mail-Inhalten bereit, die nach ihren Anwendungsfällen kategorisiert sind.

Es wird dringend empfohlen, in unterschiedlichen Szenarien verschiedene Vorlagen zu verwenden. Andernfalls könnten Nutzer E-Mail-Inhalte erhalten, die nicht zur aktuellen Aktion passen, was zu Verwirrung führen kann. Wenn Vorlagen fehlen, die nicht konfiguriert wurden, kann dies zu Fehlern in Abläufen führen, die auf diese Vorlage angewiesen sind, und die normale Geschäftsentwicklung beeinträchtigen.

Optionen zur Anpassung von E-Mail-Vorlagen​

Logto bietet drei verschiedene Ansätze für das Management von E-Mail-Vorlagen:

  1. Vorlagen in Logto anpassen

    • Connectors:
    • Funktionen:
      • ✅ Flexible Einbindung verschiedener Variablen in Vorlagen
      • ✅ Erstellung benutzerdefinierter mehrsprachiger Vorlagen über Management APIs
      • ✅ Vollständige Bearbeitung der Vorlagen innerhalb von Logto

  2. Vorlagen auf der Plattform des Anbieters anpassen

    • Connectors:
    • Funktionen:
      • ✅ Variablen an die Plattform des Anbieters übergeben
      • ✅ locale-Parameter zur Lokalisierung an die Plattform des Anbieters übergeben
      • ✅ Vollständige Bearbeitung der Vorlagen im Dashboard des Anbieters (Verwendung von Logto Management APIs)

  3. Vorgefertigte Vorlagen (nicht anpassbar)

    • Connector:
    • Funktionen:
      • ✅ Native Variablenunterstützung
      • ❌ Mehrsprachige Vorlagen (Demnächst verfügbar)
      • ❌ Anpassung der Vorlage / UI deaktiviert

Typen von E-Mail-Vorlagen​

usageTypeSzenarioVariablen
SignInNutzer melden sich mit ihrer E-Mail an und verifizieren sich, indem sie einen Bestätigungscode eingeben, anstatt ein Passwort einzugeben.code: string
application: ApplicationInfo
organization?: OrganizationInfo
RegisterNutzer erstellen ein Konto mit ihrer E-Mail und verifizieren dieses, indem sie einen von Logto an ihre E-Mail gesendeten Bestätigungscode eingeben.code: string
application: ApplicationInfo
organization?: OrganizationInfo
ForgotPasswordWenn Nutzer ihr Passwort beim Login vergessen, können sie zunächst ihre Identität per E-Mail verifizieren, um das Passwort zurückzusetzen.code: string
application: ApplicationInfo
organization?: OrganizationInfo
GenericDiese Vorlage kann als allgemeine Backup-Option für verschiedene Szenarien verwendet werden, einschließlich Testen von Connector-Konfigurationen, Verifizierung oder Verknüpfung der E-Mail nach der Anmeldung usw.code: string
OrganizationInvitationVerwende diese Vorlage, um Nutzern einen Einladungslink zu senden, damit sie der Organisation beitreten können.link: string
organization: OrganizationInfo
inviter?: UserInfo
UserPermissionValidationWährend der Nutzung der App kann es einige risikoreiche oder relativ risikoreiche Aktionen geben, die eine zusätzliche Nutzerverifizierung erfordern, wie z. B. Banküberweisungen, Löschen genutzter Ressourcen oder Kündigung von Mitgliedschaften. Die UserPermissionValidation-Vorlage kann verwendet werden, um den Inhalt der E-Mail mit dem Bestätigungscode für diese Situationen zu definieren.code: string
user: UserInfo
application?: ApplicationInfo
BindNewIdentifierWenn ein Nutzer sein Profil ändert, kann er eine E-Mail-Adresse mit seinem aktuellen Konto verknüpfen. In diesem Fall kann die BindNewIdentifier-Vorlage verwendet werden, um den Inhalt der Bestätigungs-E-Mail anzupassen.code: string
user: UserInfo
application?: ApplicationInfo
MfaVerificationWenn E-Mail MFA aktiviert ist, wird diese Vorlage verwendet, um während des Multi-Faktor-Authentifizierungsprozesses Bestätigungscodes an Nutzer zu senden.code: string
application: ApplicationInfo
organization?: OrganizationInfo
BindMfaWenn E-Mail MFA aktiviert ist, wird diese Vorlage verwendet, um den Bestätigungscode für MFA einzurichten. Nutzer erhalten diesen Code, wenn sie ihre E-Mail-Adresse als MFA-Faktor für ihr Konto binden oder konfigurieren.code: string
user: UserInfo
application?: ApplicationInfo

E-Mail-Vorlagen-Variablen​

Code​

Der Bestätigungscode, den Nutzer eingeben müssen, um den Verifizierungsprozess abzuschließen. Verfügbar in den Vorlagen SignIn, Register, ForgotPassword, Generic, UserPermissionValidation und BindNewIdentifier.

  • Bestätigungscodes verfallen nach 10 Minuten. Die Anpassung der Gültigkeitsdauer von Bestätigungscodes wird derzeit nicht unterstützt.
  • Im Template muss ein Platzhalter {{code}} reserviert werden. Beim Versand eines Bestätigungscodes wird dieser Platzhalter durch einen zufällig generierten Code ersetzt, bevor die E-Mail an die Nutzer gesendet wird.

ApplicationInfo​

Die öffentlichen Informationen der Client-Anwendung, mit der die Nutzer interagieren. Verfügbar in den Vorlagen SignIn, Register, ForgotPassword, UserPermissionValidation und BindNewIdentifier.

type ApplicationInfo = {
  id: string;
  name: string;
  displayName?: string;
  branding?: {
    logoUrl?: string;
    darkLogoUrl?: string;
    favicon?: string;
    darkFavicon?: string;
  };
};
  • Alle verschachtelten Felder der Anwendung können in Vorlagen per Punktnotation angesprochen werden. Zum Beispiel wird {{application.name}} durch den tatsächlichen Anwendungsnamen aus deiner Konfiguration ersetzt.
  • Wenn die Wurzelvariable application nicht bereitgestellt wird, wird der Handlebars-Platzhalter ignoriert und nicht ersetzt.
  • Wenn das bereitgestellte application-Objekt die erforderlichen Felder nicht enthält oder der Wert undefiniert ist, wird der Handlebars-Platzhalter durch einen leeren String ersetzt. Z. B. wird {{application.foo.bar}} durch `` ersetzt.

OrganizationInfo​

Die öffentlichen Informationen der Organisation, mit der die Nutzer interagieren.

type OrganizationInfo = {
  id: string;
  name: string;
  branding?: {
    logoUrl?: string;
    darkLogoUrl?: string;
    favicon?: string;
    darkFavicon?: string;
  };
};
  • Für die Vorlagen SignIn, Register und ForgotPassword ist die Variable organization optional. Sie ist nur verfügbar, wenn der Parameter organization_id in der Autorisierungsanfrage vorhanden ist. Siehe Organisationsspezifisches Branding für weitere Details.
  • Für die Vorlage OrganizationInvitation ist die Variable organization verpflichtend.

UserInfo​

Die öffentlichen Informationen des Nutzers, an den die E-Mail gesendet wird. Verfügbar in den Vorlagen UserPermissionValidation, BindNewIdentifier und OrganizationInvitation.

type UserInfo = {
  id: string;
  name?: string;
  username?: string;
  primaryEmail?: string;
  primaryPhone?: string;
  avatar?: string;
  profile?: Profile;
};
  • Siehe Profil für weitere Details zum Typ Profile.
  • Die Variable user ist für die Vorlagen UserPermissionValidation und BindNewIdentifier verpflichtend.
  • Die Variable inviter ist für die Vorlage OrganizationInvitation optional. Sie ist nur verfügbar, wenn inviterId in der Organisationseinladung angegeben wurde.

UI Locales​

Der ursprüngliche ui_locales-Wert, der in der OIDC-Authentifizierungsanfrage bereitgestellt wurde, die die aktuelle Interaktion ausgelöst hat.

  • Typ: string (durch Leerzeichen getrennte Liste von BCP 47 Sprach-Tags, gemäß OIDC-Spezifikation), zum Beispiel: "fr-CA fr en".
  • Verfügbarkeit: Vorhanden, wenn die aktuelle Anmeldeinteraktion mit ui_locales gestartet wurde. Wenn nicht angegeben, wird diese Variable weggelassen.
  • Typische Verwendung: In E-Mail-Inhalt oder Betreff aufnehmen, um die vom Nutzer angeforderten UI-Sprachen für i18n-Unterstützung oder Auditing zu protokollieren, z. B. Angeforderte Sprachen: {{uiLocales}}.

Beispiele für E-Mail-Vorlagen​

Du kannst die bereitgestellten E-Mail-Vorlagen-Beispiele als Ausgangspunkt für die Anpassung deiner UI verwenden. Um eine Benutzeroberfläche ähnlich der folgenden zu erstellen:

Beispiel für eine integrierte E-Mail-Vorlage

Da die E-Mail-Vorlagen, die in verschiedenen Szenarien von Logto verwendet werden, sehr ähnlich sind und sich nur in der Beschreibung des aktuellen Szenarios und der Aktion unterscheiden,

zeigen wir hier nicht den HTML-Code aller Vorlagen im Detail. Stattdessen nehmen wir nur das Anmelde-Szenario als Beispiel. Andere Szenarien wie Registrierung und Passwort vergessen sind diesem Beispiel sehr ähnlich.

Nutzer können sich an dieser Vorlage orientieren und sie an ihre tatsächliche Situation anpassen.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Bestätige deine E-Mail, um dich anzumelden</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>Bestätige deine E-Mail, um dich anzumelden</h1>
          <p>
            Wir haben einen Anmeldeversuch mit folgendem Code erhalten. Bitte gib ihn auf der Seite
            ein, die du geöffnet hast, um den Anmeldevorgang abzuschließen.
          </p>
          <div class="verification-code">000000</div>
          <p style="color: #747778;">
            Wenn du dich nicht anmelden wolltest, aber diese E-Mail erhalten hast, ignoriere sie
            bitte. Der Code bleibt 10 Minuten lang gültig.
          </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>:
        Die bessere Identity-Infrastruktur für Entwickler.
      </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;">
        Hast du Fragen oder benötigst Hilfe?
        <a href="{{mailToUrl}}" style="color: #A9ACAC; text-decoration: underline;"
          >Kontaktiere uns</a
        >
      </p>
    </div>
  </body>
</html>

Du kannst dann den obigen HTML-Code escapen und wie folgt in das Feld "Template" des Connectors in den Konfigurationen einfügen (angenommen, du verwendest den SendGrid-Connector):

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

Lokalisierung von E-Mail-Vorlagen​

Benutzerdefinierte E-Mail-Vorlagen für verschiedene Sprachen​

Logto unterstützt die Erstellung benutzerdefinierter E-Mail-Vorlagen für verschiedene Sprachen über die Management API. Du kannst für verschiedene Sprachen und Vorlagentypen eigene E-Mail-Vorlagen erstellen, um deinen Nutzern eine lokalisierte Erfahrung zu bieten.

type EmailTemplate = {
  languageTag: string;
  templateType: TemplateType;
  details: {
    subject: string;
    content: string;
    contentType?: 'text/html' | 'text/plain';
    replyTo?: string;
    sendFrom?: string;
  };
};
FeldBeschreibung
subjectDie Betreffvorlage der E-Mail.
contentDie Inhaltsvorlage der E-Mail.
contentTypeEinige E-Mail-Anbieter rendern E-Mail-Vorlagen je nach Inhaltstyp unterschiedlich (z. B. Sendgrid, Mailgun). Mit diesem Feld kannst du den Inhaltstyp der E-Mail-Vorlage festlegen.
replyToDie E-Mail-Adresse, an die Antworten auf die E-Mail gesendet werden. Prüfe bei deinem E-Mail-Anbieter, ob dieses Feld unterstützt wird.
sendFromDer Name des Absenders der E-Mail. Prüfe bei deinem E-Mail-Anbieter, ob dieses Feld unterstützt wird.

Sobald die E-Mail-Vorlagen erstellt wurden, wählt Logto automatisch die passende E-Mail-Vorlage aus, indem zuerst die Sprachpräferenz des Nutzers ermittelt und dann die am besten passende Vorlage ausgewählt wird.

Die Sprachpräferenz wird in folgender Reihenfolge ermittelt:

  1. Wenn die OIDC-Authentifizierungsanfrage ui_locales enthält, wählt Logto das erste Tag in ui_locales, das von der Sprachbibliothek deines Tenants unterstützt wird. Siehe ui_locales für Details.
  2. Andernfalls verwendet Logto für clientseitige Experience APIs und User Account APIs den Accept-Language-Header. Für Management APIs (wie z. B. Organisationseinladung) kannst du die Sprache über das Feld locale in messagePayload angeben.
  3. Wenn beides nicht angegeben ist, verwendet Logto die Standard-Sprache des Tenants, die in der Anmeldeerfahrung konfiguriert ist. Siehe Lokalisierte Sprachen für Konfigurationsdetails.

Vorlagenauswahl:

  1. Mit der ermittelten Sprache sucht Logto nach einer passenden benutzerdefinierten E-Mail-Vorlage anhand von languageTag und templateType. Wenn gefunden, wird diese Vorlage verwendet.
  2. Wenn keine passende benutzerdefinierte Vorlage existiert, verwendet Logto die Standard-E-Mail-Vorlage, die in der Connector-Konfiguration definiert ist.

Unterstützte E-Mail-Connectors:

Lokalisierung von E-Mail-Vorlagen auf Anbieterseite​

Für Entwickler, die E-Mail-Connectors verwenden, bei denen die E-Mail-Vorlage vom Anbieter verwaltet wird:

Die bevorzugte Sprache des Nutzers wird über den locale-Parameter im Template-Payload an den Anbieter übergeben. Du kannst im Dashboard des Anbieters mehrere Vorlagen für verschiedene Sprachen erstellen und den locale-Parameter verwenden, um die Sprachpräferenz anzugeben.

hinweis:

Wenn ui_locales in der Authentifizierungsanfrage vorhanden ist, stehen sowohl die Variablen locale als auch uiLocales im Template-Kontext zur Verfügung. Die Variable uiLocales enthält den ursprünglichen ui_locales-Wert aus der Authentifizierungsanfrage, während die Variable locale auf dem ersten unterstützten Tag basiert, der aus ui_locales ermittelt wurde. Wenn ui_locales nicht angegeben ist, folgt locale den Standardauflösungsregeln (z. B. Accept-Language, dann Standardsprache).

FAQs​

Wie kann ich Drittanbieter-E-Mail-Template-Services nutzen, wenn Vorlagen nicht in Logto konfiguriert sind?​

Du kannst einen neuen Endpunkt zu deinem eigenen Webservice hinzufügen, um E-Mails zu versenden, und dann den Logto HTTP E-Mail-Connector verwenden, um den von dir gepflegten Endpunkt aufzurufen.

So kannst du die Logik für E-Mail-Vorlagen auf deinem eigenen Server verwalten.

Gibt es eine Möglichkeit, Logto-E-Mail zu verwenden, um unseren Nutzern eine angepasste "Willkommens-E-Mail" zu senden?​

Wir bieten Webhook-Funktionalität an. Du kannst deinen eigenen API-Endpunkt implementieren, um das von Logto Webhook gesendete User.Created-Event zu empfangen, und Logik hinzufügen, um innerhalb des Webhook-Handlers eine angepasste Willkommens-E-Mail zu versenden.

Der Logto-E-Mail-Connector stellt nur E-Mail-Benachrichtigungen für Ereignisse im Zusammenhang mit dem Authentifizierungsablauf bereit. Willkommens-E-Mails sind eine geschäftliche Anforderung und werden vom E-Mail-Connector nicht nativ unterstützt, aber diese Funktionalität kann über Webhooks realisiert werden.

Maximale Zustellbarkeit von Bestätigungs-E-Mails, um den Nutzerzugang zu gewährleisten