diff --git a/docs/connectors/email-connectors/email-templates.mdx b/docs/connectors/email-connectors/email-templates.mdx index 84feb41da1d..2d8bfec5655 100644 --- a/docs/connectors/email-connectors/email-templates.mdx +++ b/docs/connectors/email-connectors/email-templates.mdx @@ -13,20 +13,86 @@ It is strongly recommended that you use different templates in different scenari ## Email template types \{#email-template-types} -| usageType | Scenario | -| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| SignIn | Users sign in using their email and verify by entering verification code instead of entering a password. | -| Register | Users create an account using their email and verify it by entering a verification code sent by Logto to their email. | -| ForgotPassword | If users forget their password during login, they can choose to verify their identity using the email they've already verified with Logto. | -| Generic | This template can be used as a general backup option for various scenarios, including testing connector configurations and so on. | -| OrganizationInvitation | Use this template to send users an invitation link to join the organization. | -| UserPermissionValidation | During app usage, there may be some high-risk operations or operations with a relatively high risk level that require additional user verification, such as bank transfers, deleting resources in use, and canceling memberships. The `UserPermissionValidation` template can be used to define the content of the email verification code users receive in these situations. | -| BindNewIdentifier | When a user modifies their profile, they may bind an email address to their current account. In this case, the `BindNewIdentifier` template can be used to customize the content of the verification email. | +| usageType | Scenario | Variables | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | +| SignIn | Users sign in using their email and verify by entering verification code instead of entering a password. | code: string
application: `ApplicationInfo`
organization?: `OrganizationInfo` | +| Register | Users create an account using their email and verify it by entering a verification code sent by Logto to their email. | code: string
application: `ApplicationInfo`
organization?: `OrganizationInfo` | +| ForgotPassword | If users forget their password during login, they can choose to verify their identity using the email they've already verified with Logto. | code: string
application: `ApplicationInfo`
organization?: `OrganizationInfo` | +| Generic | This template can be used as a general backup option for various scenarios, including testing connector configurations and so on. | code: string | +| OrganizationInvitation | Use this template to send users an invitation link to join the organization. | link: string
organization: `OrganizationInfo`
inviter?: `UserInfo` | +| UserPermissionValidation | During app usage, there may be some high-risk operations or operations with a relatively high risk level that require additional user verification, such as bank transfers, deleting resources in use, and canceling memberships. The `UserPermissionValidation` template can be used to define the content of the email verification code users receive in these situations. | code: string
user: `UserInfo`
application?: `ApplicationInfo` | +| BindNewIdentifier | When a user modifies their profile, they may bind an email address to their current account. In this case, the `BindNewIdentifier` template can be used to customize the content of the verification email. | code: string
user: `UserInfo`
application?: `ApplicationInfo` | It's important to understand these parameters: -- Verification codes expire in 10 minutes. We currently do not support the customization of verification code expiry time. -- A `{{code}}` placeholder needs to be reserved in the template. When sending a verification code, a randomly generated code will replace this placeholder before we send email to users. +### Code + +The verification code that users need to enter to complete the verification process. Available in `SignIn`, `Register`, `ForgotPassword`, `Generic`, `UserPermissionValidation`, and `BindNewIdentifier` templates. + + - Verification codes expire in 10 minutes. We currently do not support the customization of verification code expiry time. + - A `{{code}}` placeholder needs to be reserved in the template. When sending a verification code, a randomly generated code will replace this placeholder before we send email to users. + +### ApplicationInfo + +The public information of the client application that users are interacting with. Available in `SignIn`, `Register`, `ForgotPassword`, `UserPermissionValidation`, and `BindNewIdentifier` templates. + +```ts +type ApplicationInfo = { + id: string; + name: string; + displayName?: string; + branding?: { + logoUrl?: string; + darkLogoUrl?: string; + favicon?: string; + darkFavicon?: string; + }; +}; +``` + +- All nested application info fields can be accessed in templates through dot notation. For example, `{{application.name}}` will be replaced with the actual application name from your configuration. +- If the root `application` variable is not provided, the handlebars placeholder will be ignored and not replaced. +- If the provided `application` object does not contain the required fields or the value is undefined, the handlebars placeholder will be replaced with an empty string. E.g. `{{application.foo.bar}}` will be replaced with ``. + +### OrganizationInfo + +The public information of the organization that users are interacting with. + +```ts +type OrganizationInfo = { + id: string; + name: string; + branding?: { + logoUrl?: string; + darkLogoUrl?: string; + favicon?: string; + darkFavicon?: string; + }; +}; +``` + +- For the `SignIn`, `Register`, and `ForgotPassword` templates, the `organization` variable is optional. Only available when the `organization_id` parameter is present in the authorization request. See [Organization-specific branding](/customization/match-your-brand#organization-specific-branding) for more details. +- For the `OrganizationInvitation` template, the `organization` variable is mandatory. + +### UserInfo + +The public information of the user that the email is sent to. Available in `UserPermissionValidation`, `BindNewIdentifier` and `OrganizationInvitation` templates. + +```ts +type UserInfo = { + id: string; + name?: string; + username?: string; + primaryEmail?: string; + primaryPhone?: string; + avatar?: string; + profile?: Profile; +}; +``` + +- Check [profile](/user-management/user-data#profile) for more details about the `Profile` type. +- The `user` variable is mandatory for the `UserPermissionValidation` and `BindNewIdentifier` templates. +- The `inviter` variable is optional for the `OrganizationInvitation` template. Only available when the `inviterId` is provided in the organization invitation request. ## Email template examples \{#email-template-examples} @@ -172,6 +238,41 @@ You can then escape the HTML code above and add it to the connector "Template" f } ``` +## Custom i18n email templates + +Logto supports customizing email templates in multiple languages. You may create multiple email templates in different languages for different types of emails. + +```ts +type EmailTemplate = { + languageTag: string; + templateType: TemplateType; + details: { + subject: string; + content: string; + contentType?: 'text/html' | 'text/plain'; + replyTo?: string; + sendFrom?: string; + }; +}; +``` + +| Field | Description | +| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| subject | The subject template of the email. | +| content | The content template of the email. | +| contentType | Some email providers may render email templates differently based on the content type. (e.g. Sendgrid, Mailgun). Use this field to specify the content type of the email template. | +| replyTo | The email address that will receive replies to the email. Check with your email provider to see if this field is supported. | +| sendFrom | The name alias of the email sender. Check with your email provider to see if this field is supported. | + +Once the email templates are created, Logto will automatically select the appropriate email template based on the user's language preference using the following priority order: + +1. For client-side experiences and user account APIs, language preference is determined by the `Accept-Language` header in the request. For admin APIs (such as Organization Invitation), you can specify the language preference by including a `locale` parameter in the `messagePayload` field of the request body. +2. When a language preference is detected, Logto looks for a matching custom email template using the `languageTag` and `templateType` fields. If a template exists for the specified language and template type, Logto will use that template. +3. If no language preference is detected, or if no custom template exists for the detected language and template type, Logto will use the tenant's default language configured in the Sign-in Experience. Check [Localized languages](/customization/localized-languages#customization-steps-in-logto-console) for configuration details. +4. If no matching template is found, Logto will use the default email template defined in the connector configuration. + +Check (TODO: management API) for more details on how to create and manage custom email templates. + ## FAQs \{#faqs}
@@ -205,3 +306,4 @@ The Logto email connector only provides email notifications for events related t Maximize verification email delivery to guarantee user access +```