電子郵件範本 (Email templates)

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

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

電子郵件範本自訂選項

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

在 Logto 內自訂範本
- 連接器 (Connectors)：
- 功能 (Capabilities)：
  - ✅ 靈活插入多樣變數至範本
  - ✅ 透過 Management API 建立自訂多語言範本
  - ✅ 在 Logto 內完整編輯範本
在供應商平台自訂範本
- 連接器 (Connectors)：
  - Postmark
  - HTTP Email
- 功能 (Capabilities)：
  - ✅ 將變數傳遞至供應商平台
  - ✅ 將 locale 參數傳遞至供應商平台以支援在地化
  - ✅ 於供應商後台完整編輯範本（使用 Logto Management API）
預設範本（不可自訂）
- 連接器 (Connector)：
  - Logto 內建郵件服務 (Built-in Email Service)
- 功能 (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。
user 變數為 UserPermissionValidation 與 BindNewIdentifier 範本必填。
inviter 變數為 OrganizationInvitation 範本選填。僅當組織邀請請求帶有 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 (Experience APIs) 與使用者帳號 API (User Account APIs)，Logto 會使用 Accept-Language 標頭。對於 Management API（如組織邀請），可於 messagePayload 的 locale 欄位指定語言。
若皆未提供，Logto 會回退至租戶於「登入與帳號 > 內容」設定的預設語言。詳見在地化語言設定。

範本選擇：

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

支援的電子郵件連接器：

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

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

系統會將使用者偏好語言以 locale 參數傳遞給供應商。你可於供應商後台為不同語言建立多個範本，並透過 locale 參數指定語言偏好。

備註:

當驗證請求帶有 ui_locales 時，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 郵件發送自訂「歡迎郵件」給使用者嗎？​

相關資源​