跳到主要内容

邮件模板

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

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

邮件模板类型​

usageType场景Variables
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="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;
  };
};
字段描述
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 中未配置模板，如何使用第三方邮件模板服务？​

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

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

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

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

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

最大化验证邮件的投递以保证用户访问