電子郵件範本 (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)時，於多重要素驗證流程中發送驗證碼給使用者。	code: string application: `ApplicationInfo` organization?: `OrganizationInfo`
BindMfa	啟用電子郵件多重要素驗證 (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 的起點。若要建立如下圖的使用者介面：

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 會依據使用者語言偏好自動選擇對應範本，優先順序如下：

對於前端使用體驗 API (Experience API) 與使用者帳號 API (Account API)，語言偏好由請求的 Accept-Language 標頭決定。對於 Management API（如組織邀請），可於請求內容的 messagePayload 欄位指定 locale 參數。
偵測到語言偏好時，Logto 會依 languageTag 與 templateType 尋找對應自訂範本。若存在，將以該範本渲染郵件。
若未偵測到語言偏好，或無對應自訂範本，則使用登入體驗中設定的租戶預設語言。詳見多語言設定。
若仍無對應範本，則使用連接器設定中的預設郵件範本。

支援的郵件連接器：

郵件服務平台端的範本在地化

若你使用由郵件服務平台管理範本的連接器：

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

常見問題

若未在 Logto 配置範本，如何使用第三方郵件範本服務？

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

如此即可在自己的伺服器上處理郵件範本邏輯。

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

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

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

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

電子郵件範本自訂選項​

電子郵件範本類型​

電子郵件範本變數​

Code​

ApplicationInfo​

OrganizationInfo​

UserInfo​

電子郵件範本範例​

電子郵件範本在地化​

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

郵件服務平台端的範本在地化​

常見問題​

若未在 Logto 配置範本，如何使用第三方郵件範本服務？​

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

相關資源​