邮件模板

Logto 提供了不同的模板用于自定义邮件内容，这些模板根据其使用场景进行分类。

强烈建议在不同场景中使用不同的模板。否则，用户可能会收到与当前操作不匹配的邮件内容，导致混淆。如果缺少未配置的模板，可能会导致依赖该模板的流程错误，影响业务的正常发展。

邮件模板自定义选项

Logto 提供了三种不同的方法来管理邮件模板：

在 Logto 中自定义模板
- 连接器：
- 功能：
  - ✅ 灵活地将各种变量插入模板
  - ✅ 通过 Management API 创建自定义多语言模板
  - ✅ 在 Logto 内完全编辑模板
在提供商平台中自定义模板
- 连接器：
  - Postmark
  - HTTP Email
- 功能：
  - ✅ 将变量传递给提供商平台
  - ✅ 将 locale 参数传递给提供商平台以实现本地化
  - ✅ 在提供商的仪表板中完全编辑模板（使用 Logto Management API）
预构建模板（不可自定义）
- 连接器：
  - Logto 内置邮件服务
- 功能：
  - ✅ 原生变量支持
  - ❌ 多语言模板 (即将推出)
  - ❌ 禁用模板/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`

邮件模板变量

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 类型的更多详细信息，请查看个人资料。
对于 UserPermissionValidation 和 BindNewIdentifier 模板，user 变量是必需的。
对于 OrganizationInvitation 模板，inviter 变量是可选的。仅在组织邀请请求中提供 inviterId 时可用。

邮件模板示例

你可以使用提供的邮件模板代码示例作为自定义 UI 的起点，以创建类似于以下的用户界面：

由于 Logto 在不同场景中使用的邮件模板非常相似，唯一的区别在于当前场景和操作的描述。

我们在此不详细展示所有模板的 HTML 代码，而是仅以登录场景为例。其他场景，如注册和忘记密码，与以下示例非常相似。

用户可以参考此模板并根据实际情况进行调整。

<!doctype html>
<html lang="zh-CN">
  <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 将根据用户的语言偏好自动选择合适的邮件模板，使用以下优先顺序：

对于客户端 Experience API 和 User Account API，语言偏好由请求中的 Accept-Language 头确定。对于 Management API（如 Organization Invitation），你可以通过在请求体的 messagePayload 字段中包含 locale 参数来指定语言偏好。
当检测到语言偏好时，Logto 会使用 languageTag 和 templateType 字段查找匹配的自定义邮件模板。如果指定语言和模板类型存在模板，Logto 将使用该模板渲染邮件。
如果未检测到语言偏好，或者检测到的语言和模板类型没有自定义模板，Logto 将使用登录体验中配置的租户默认语言。有关配置详细信息，请查看本地化语言。
如果未找到匹配的模板，Logto 将使用连接器配置中定义的默认邮件模板。

支持的邮件连接器：

提供商端邮件模板本地化

对于使用由提供商管理邮件模板的邮件连接器的开发者：

用户的首选语言将通过模板负载中的 locale 参数传递给提供商。你可以在提供商的控制台中为不同语言创建多个模板，并使用 locale 参数指定语言偏好。

常见问题解答

如果模板未在 Logto 中配置，如何使用第三方邮件模板服务？

你可以为自己的 Web 服务添加一个新端点以发送邮件，然后使用 Logto HTTP 邮件连接器调用你维护的端点。

这允许你在自己的服务器上处理邮件模板逻辑。

是否可以使用 Logto 邮件向我们的用户发送自定义的“欢迎邮件”？

我们提供 Webhook 功能。你可以实现自己的 API 端点以接收 Logto Webhook 发送的 User.Created 事件，并在 webhook 处理程序中添加逻辑以发送自定义的欢迎邮件。

Logto 邮件连接器仅提供与认证 (Authentication) 流程相关事件的邮件通知。欢迎邮件是一个业务需求，邮件连接器本身不支持，但可以通过 Webhook 实现此功能。

最大化验证邮件的发送以确保用户访问

邮件模板自定义选项​

邮件模板类型​

邮件模板变量​

Code​

ApplicationInfo​

OrganizationInfo​

UserInfo​

邮件模板示例​

邮件模板本地化​

不同语言的自定义邮件模板​

提供商端邮件模板本地化​

常见问题解答​

如果模板未在 Logto 中配置，如何使用第三方邮件模板服务？​

是否可以使用 Logto 邮件向我们的用户发送自定义的“欢迎邮件”？​

相关资源​