電子郵件範本 (Email templates)

Logto 提供多種可自訂的電子郵件內容範本，並依照不同使用情境分類。

強烈建議你在不同情境下使用不同的範本。否則，使用者可能會收到與當前操作不符的電子郵件內容，造成混淆。如果有缺少且未設定的範本，可能會導致依賴該範本的流程出錯，影響業務正常運作。

電子郵件範本自訂選項

Logto 提供三種不同的電子郵件範本管理方式：

在 Logto 內自訂範本
- 連接器 (Connectors)：
- 功能 (Capabilities)：
  - ✅ 靈活插入多樣變數至範本
  - ✅ 透過 Management API 建立自訂多語言範本
  - ✅ 在 Logto 內完整編輯範本
在供應商平台自訂範本
- 連接器 (Connectors)：
  - Postmark
  - HTTP Email
- 功能 (Capabilities)：
  - ✅ 將變數傳遞至供應商平台
  - ✅ 傳遞 locale 參數至供應商平台以進行在地化
  - ✅ 於供應商後台完整編輯範本（使用 Logto Management API）
預設內建範本（不可自訂）
- 連接器 (Connector)：
  - Logto 內建電子郵件服務
- 功能 (Capabilities)：
  - ✅ 原生變數支援
  - ❌ 多語言範本 (即將推出)
  - ❌ 禁止範本 / UI 修改

電子郵件範本類型

usageType	情境說明	變數 (Variables)
SignIn	使用者以電子郵件登入，並以驗證碼驗證身分，而非輸入密碼。	code: string application: `ApplicationInfo` organization?: `OrganizationInfo`
Register	使用者以電子郵件註冊帳號，並輸入 Logto 寄送的驗證碼完成驗證。	code: string application: `ApplicationInfo` organization?: `OrganizationInfo`
ForgotPassword	使用者登入時忘記密碼，可選擇先以電子郵件驗證身分以重設密碼。	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`
MfaVerification	啟用電子郵件 MFA 時，此範本用於多重要素驗證 (MFA) 流程中寄送驗證碼給使用者。	code: string application: `ApplicationInfo` organization?: `OrganizationInfo`
BindMfa	啟用電子郵件 MFA 時，此範本用於設定 MFA 驗證碼。使用者將在綁定或設定電子郵件為 MFA 因子時收到此驗證碼。	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 物件未包含所需欄位或值為 undefined，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 Locales

啟動當前互動的 OIDC 驗證請求中提供的原始 ui_locales 值。

型別：string（以空格分隔的 BCP 47 語言標籤，依 OIDC 規範），例如："fr-CA fr en"。
可用性：當當前登入互動以 ui_locales 啟動時存在。若未提供，則省略此變數。
典型用途：可於郵件內容或主旨中記錄使用者要求的 UI 語言，方便 i18n 支援或稽核，例如 Requested languages: {{uiLocales}}。

電子郵件範本範例

你可以參考下方提供的電子郵件範本程式碼，作為自訂 UI 的起點。若要建立如下圖的使用者介面：

由於 Logto 不同情境下的電子郵件範本內容極為相似，僅差在當前情境與操作說明。

此處不詳列所有範本的 HTML 程式碼，僅以登入情境為例。其他如註冊、忘記密碼等情境範本與下例大同小異。

你可依實際需求參考並調整此範本。

<!doctype html>
<html lang="en">
  <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;
  };
};

欄位 (Field)	說明 (Description)
subject	郵件主旨範本。
content	郵件內容範本。
contentType	部分郵件供應商會依內容型態渲染郵件範本（如 Sendgrid、Mailgun）。可用此欄位指定郵件範本內容型態。
replyTo	收件人回覆郵件的信箱。請確認你的郵件供應商是否支援此欄位。
sendFrom	寄件者名稱別名。請確認你的郵件供應商是否支援此欄位。

建立範本後，Logto 會自動依下列順序解析使用者語言偏好，並選擇最合適的範本：

語言偏好解析順序如下：

若 OIDC 驗證請求包含 ui_locales，Logto 會選擇 ui_locales 中第一個被租戶語言庫支援的標籤。詳見 ui_locales。
否則，對於用戶端使用體驗 API 與使用者帳號 API，Logto 會使用 Accept-Language 標頭。對於 Management API（如組織邀請），可於 messagePayload 的 locale 欄位指定語言。
若皆未提供，Logto 會退回至登入體驗中設定的租戶預設語言。詳見在地化語言設定。

範本選擇：

解析語言後，Logto 會以 languageTag 與 templateType 尋找符合的自訂電子郵件範本，若有則使用該範本。
若無符合的自訂範本，則使用連接器設定中的預設電子郵件範本。

支援的電子郵件連接器：

供應商端電子郵件範本在地化

若你使用由供應商管理電子郵件範本的連接器：

使用者偏好語言會以 locale 參數傳遞至供應商範本 payload。你可於供應商後台建立多語言範本，並以 locale 參數指定語言偏好。

備註:

當驗證請求中有 ui_locales 時，範本 context 會同時提供 locale 與 uiLocales 變數。 uiLocales 變數包含驗證請求中的原始 ui_locales 值，而 locale 變數則根據 ui_locales 解析出的第一個支援標籤決定。若未提供 ui_locales，locale 則依標準解析規則（如 Accept-Language，再退回預設語言）。

常見問題

若未在 Logto 設定範本，如何使用第三方電子郵件範本服務？

你可以在自己的 Web 服務新增一個端點來發送郵件，然後使用 Logto HTTP 電子郵件連接器呼叫你維護的端點。

如此即可於自有伺服器處理電子郵件範本邏輯。

有辦法用 Logto 電子郵件發送自訂「歡迎郵件」給使用者嗎？

我們提供 Webhook 功能。你可以實作自己的 API 端點，接收 Logto Webhook 發送的 User.Created 事件，並於 webhook handler 內加入發送自訂歡迎郵件的邏輯。

Logto 電子郵件連接器僅針對驗證流程相關事件提供郵件通知。歡迎郵件屬於業務需求，電子郵件連接器並未原生支援，但可透過 Webhook 實現此功能。

提高驗證郵件送達率，確保使用者順利存取

電子郵件範本自訂選項​

電子郵件範本類型​

電子郵件範本變數​

Code​

ApplicationInfo​

OrganizationInfo​

UserInfo​

UI Locales​

電子郵件範本範例​

電子郵件範本在地化​

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

供應商端電子郵件範本在地化​

常見問題​

若未在 Logto 設定範本，如何使用第三方電子郵件範本服務？​

有辦法用 Logto 電子郵件發送自訂「歡迎郵件」給使用者嗎？​

相關資源​