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 Benutzer E-Mail-Inhalte erhalten, die nicht zur aktuellen Aktion passen, was zu Verwirrung führt. Falls erforderliche Vorlagen fehlen und nicht konfiguriert sind, 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 der Logto Management APIs)

  3. Vorgefertigte Vorlagen (nicht anpassbar)

    • Connector:
    • Funktionen:
      • ✅ Native Variablenunterstützung
      • ✅ Mehrsprachige Vorlagen
      • ❌ Änderungen an Vorlage / UI deaktiviert

Typen von E-Mail-Vorlagen​

usageTypeSzenarioVariablen
SignInBenutzer melden sich mit ihrer E-Mail an und verifizieren sich durch Eingabe eines Verifizierungscodes anstelle eines Passworts.code: string
application: ApplicationInfo
organization?: OrganizationInfo
RegisterBenutzer erstellen ein Konto mit ihrer E-Mail und verifizieren dieses durch Eingabe eines von Logto an ihre E-Mail gesendeten Verifizierungscodes.code: string
application: ApplicationInfo
organization?: OrganizationInfo
ForgotPasswordWenn Benutzer 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, Verifizieren oder Verknüpfen der E-Mail nach der Anmeldung usw.code: string
OrganizationInvitationVerwende diese Vorlage, um Benutzern 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 Benutzerverifizierung 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-Verifizierungscodes für diese Situationen zu definieren.code: string
user: UserInfo
application?: ApplicationInfo
BindNewIdentifierWenn ein Benutzer sein Profil ändert, kann er eine E-Mail-Adresse an sein aktuelles Konto binden. In diesem Fall kann die BindNewIdentifier-Vorlage verwendet werden, um den Inhalt der Verifizierungs-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 Verifizierungscodes an Benutzer zu senden.code: string
application: ApplicationInfo
organization?: OrganizationInfo
BindMfaWenn E-Mail MFA aktiviert ist, wird diese Vorlage verwendet, um den E-Mail-Verifizierungscode für MFA einzurichten. Benutzer erhalten diesen Verifizierungscode, wenn sie ihre E-Mail-Adresse als MFA-Faktor für ihr Konto binden oder konfigurieren.code: string
user: UserInfo
application?: ApplicationInfo

Variablen für E-Mail-Vorlagen​

Code​

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

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

ApplicationInfo​

Die öffentlichen Informationen der Client-Anwendung, mit der die Benutzer 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;
  };
};
  • Auf alle verschachtelten Felder der Anwendung kann in Vorlagen per Punktnotation zugegriffen 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 Benutzer 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 Benutzers, 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 ist.

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-Sprachtags, gemäß OIDC-Spezifikation), z. B.: "fr-CA fr en".
  • Verfügbarkeit: Vorhanden, wenn die aktuelle Anmeldeinteraktion mit ui_locales initiiert wurde. Wenn nicht bereitgestellt, wird diese Variable weggelassen.
  • Typische Verwendung: In E-Mail-Inhalt oder Betreff aufnehmen, um die vom Benutzer 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 Codebeispiele für E-Mail-Vorlagen 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.

Benutzer 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;">
            Falls du dich nicht anmelden wolltest, ignoriere diese E-Mail 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 ihn 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 Benutzern 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 angeben.
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 Anzeigename des E-Mail-Absenders. 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 Benutzers 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 Benutzers wird mit dem Parameter locale im Template-Payload an den Anbieter übergeben. Du kannst im Dashboard des Anbieters mehrere Vorlagen für verschiedene Sprachen erstellen und den Parameter locale 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-Dienste 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 Benutzern eine angepasste "Willkommens-E-Mail" zu senden?​

Wir bieten Webhook-Funktionalität. Du kannst deinen eigenen API-Endpunkt implementieren, um das von Logto Webhook gesendete User.Created-Ereignis 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 Verifizierungs-E-Mails, um den Benutzerzugang zu gewährleisten