跳至主要內容

電子郵件範本

Logto 提供不同的範本來自訂電子郵件內容，這些範本根據其使用情境進行分類。

強烈建議在不同情境中使用不同的範本。否則，使用者可能會收到與當前操作不匹配的電子郵件內容，造成混淆。如果有未配置的範本缺失，可能會導致依賴該範本的流程錯誤，影響業務的正常發展。

電子郵件範本類型​

usageType情境變數
SignIn使用者使用其電子郵件登入並透過輸入驗證碼而非密碼進行驗證。code: string
application: ApplicationInfo
organization?: OrganizationInfo
Register使用者使用其電子郵件創建帳戶，並透過輸入 Logto 發送到其電子郵件的驗證碼進行驗證。code: string
application: ApplicationInfo
organization?: OrganizationInfo
ForgotPassword如果使用者在登入時忘記密碼，他們可以選擇使用已經在 Logto 驗證過的電子郵件來驗證其身分。code: string
application: ApplicationInfo
organization?: OrganizationInfo
Generic此範本可作為各種情境的通用備用選項，包括測試連接器配置等。code: string
OrganizationInvitation使用此範本向使用者發送邀請連結以加入組織。link: string
organization: OrganizationInfo
inviter?: UserInfo
UserPermissionValidation在應用程式使用過程中，可能會有一些高風險操作或風險較高的操作需要額外的使用者驗證，例如銀行轉帳、刪除使用中的資源和取消會員資格。UserPermissionValidation 範本可用於定義使用者在這些情況下收到的電子郵件驗證碼的內容。code: string
user: UserInfo
application?: ApplicationInfo
BindNewIdentifier當使用者修改其個人資料時，他們可能會將電子郵件地址綁定到其當前帳戶。在這種情況下，可以使用 BindNewIdentifier 範本來自訂驗證電子郵件的內容。code: string
user: UserInfo
application?: ApplicationInfo

電子郵件範本變數​

Code​

使用者需要輸入的驗證碼以完成驗證過程。可用於 SignIn、Register、ForgotPassword、Generic、UserPermissionValidation 和 BindNewIdentifier 範本。

  • 驗證碼在 10 分鐘內過期。我們目前不支援自訂驗證碼的過期時間。
  • 範本中需要保留一個 {{code}} 佔位符。發送驗證碼時，會用隨機生成的驗證碼替換此佔位符，然後將電子郵件發送給使用者。

ApplicationInfo​

使用者正在互動的客戶端應用程式的公共資訊。可用於 SignIn、Register、ForgotPassword、UserPermissionValidation 和 BindNewIdentifier 範本。

type ApplicationInfo = {
  id: string;
  name: string;
  displayName?: string;
  branding?: {
    logoUrl?: string;
    darkLogoUrl?: string;
    favicon?: string;
    darkFavicon?: string;
  };
};
  • 所有嵌套的應用程式資訊欄位都可以透過點符號在範本中訪問。例如，{{application.name}} 將被替換為配置中的實際應用程式名稱。
  • 如果未提供根 application 變數，則 handlebars 佔位符將被忽略且不會被替換。
  • 如果提供的 application 物件不包含所需欄位或值為未定義，則 handlebars 佔位符將被替換為空字串。例如，{{application.foo.bar}} 將被替換為 ``。

OrganizationInfo​

使用者正在互動的組織的公共資訊。

type OrganizationInfo = {
  id: string;
  name: string;
  branding?: {
    logoUrl?: string;
    darkLogoUrl?: string;
    favicon?: string;
    darkFavicon?: string;
  };
};
  • 對於 SignIn、Register 和 ForgotPassword 範本，organization 變數是可選的。僅在授權請求中存在 organization_id 參數時可用。詳情請參閱 組織專屬品牌設定。
  • 對於 OrganizationInvitation 範本，organization 變數是必需的。

UserInfo​

發送電子郵件的使用者的公共資訊。可用於 UserPermissionValidation、BindNewIdentifier 和 OrganizationInvitation 範本。

type UserInfo = {
  id: string;
  name?: string;
  username?: string;
  primaryEmail?: string;
  primaryPhone?: string;
  avatar?: string;
  profile?: Profile;
};
  • 有關 Profile 類型的更多詳細資訊，請查看 profile。
  • UserPermissionValidation 和 BindNewIdentifier 範本的 user 變數是必需的。
  • OrganizationInvitation 範本的 inviter 變數是可選的。僅在組織邀請請求中提供 inviterId 時可用。

電子郵件範本範例​

你可以使用提供的電子郵件範本代碼範例作為自訂 UI 的起點。要創建類似於以下的使用者介面：

內建電子郵件範本範例

由於 Logto 在不同情境中使用的電子郵件範本非常相似，唯一的區別在於當前情境和操作的描述。

我們不在此詳細展示所有範本的 HTML 代碼，而是僅以 登入 情境為例。其他情境，如註冊和忘記密碼，與以下範例非常相似。

使用者可以參考此範本並根據實際情況進行調整。

<!doctype html>
<html lang="zh-TW">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>驗證你的電子郵件以登入</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>驗證你的電子郵件以登入</h1>
          <p>我們已收到一個登入嘗試，以下是驗證碼。請在你打開的頁面中輸入它以完成登入過程。</p>
          <div class="verification-code">000000</div>
          <p style="color: #747778;">
            如果你沒有嘗試登入但收到了此電子郵件，請忽略它。驗證碼將在 10 分鐘內保持有效。
          </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>：
        為開發者提供更好的身分基礎設施。
      </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;">
        有問題或需要幫助？
        <a href="{{mailToUrl}}" style="color: #A9ACAC; text-decoration: underline;">聯絡我們</a>
      </p>
    </div>
  </body>
</html>

然後你可以將上述 HTML 代碼轉義並將其添加到配置中的連接器 "Template" 欄位，如下所示（假設使用 SendGrid 連接器）：

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

電子郵件範本本地化​

不同語言的自訂電子郵件範本​

Logto 支援透過 Management API 為不同語言創建自訂電子郵件範本。你可以為不同語言和範本類型創建自訂電子郵件範本，以提供本地化的使用者體驗。

type EmailTemplate = {
  languageTag: string;
  templateType: TemplateType;
  details: {
    subject: string;
    content: string;
    contentType?: 'text/html' | 'text/plain';
    replyTo?: string;
    sendFrom?: string;
  };
};
欄位描述
subject電子郵件的主題範本。
content電子郵件的內容範本。
contentType一些電子郵件提供商可能會根據內容類型不同地渲染電子郵件範本。（例如 Sendgrid、Mailgun）。使用此欄位指定電子郵件範本的內容類型。
replyTo將接收電子郵件回覆的電子郵件地址。檢查你的電子郵件提供商以查看此欄位是否受支援。
sendFrom電子郵件發件人的名稱別名。檢查你的電子郵件提供商以查看此欄位是否受支援。

一旦創建了電子郵件範本，Logto 將根據使用者的語言偏好自動選擇適當的電子郵件範本，使用以下優先順序：

  1. 對於客戶端 使用體驗 API 和 使用者帳戶 API，語言偏好由請求中的 Accept-Language 標頭決定。對於 Management API（如 組織邀請），你可以在請求正文的 messagePayload 欄位中包含 locale 參數來指定語言偏好。
  2. 當檢測到語言偏好時，Logto 會使用 languageTag 和 templateType 欄位查找匹配的自訂電子郵件範本。如果指定語言和範本類型存在範本，Logto 將使用該範本來渲染電子郵件。
  3. 如果未檢測到語言偏好，或者檢測到的語言和範本類型沒有自訂範本，Logto 將使用在登入體驗中配置的租戶默認語言。查看 本地化語言 以獲取配置詳細資訊。
  4. 如果找不到匹配的範本，Logto 將使用連接器配置中定義的默認電子郵件範本。

支援的電子郵件連接器：

提供商端的電子郵件範本本地化​

對於使用由提供商管理電子郵件範本的電子郵件連接器的開發者：

使用者偏好的語言將透過範本負載中的 locale 參數傳遞給提供商。你可以在提供商的控制台中為不同語言創建多個範本，並使用 locale 參數指定語言偏好。

常見問題​

如果 Logto 中未配置範本，如何使用第三方電子郵件範本服務？​

你可以為自己的網路服務添加一個新端點來發送電子郵件，然後使用 Logto HTTP 電子郵件連接器 來調用你維護的端點。

這樣你就可以在自己的伺服器上處理電子郵件範本邏輯。

是否有辦法使用 Logto 電子郵件發送自訂的「歡迎電子郵件」給我們的使用者？​

我們提供 Webhook 功能。你可以實作自己的 API 端點來接收 Logto Webhook 發送的 User.Created 事件，並在 webhook 處理程序中添加邏輯以發送自訂的歡迎電子郵件。

Logto 電子郵件連接器僅提供與驗證流程相關的事件的電子郵件通知。歡迎電子郵件是一項業務需求，電子郵件連接器本身不支援，但可以透過 Webhook 實現此功能。

最大化驗證電子郵件的傳遞以保證使用者存取