Skip to main content

Email templates

Ory Identities comes with built-in templates for all messages sent by the system. You can replace the default templates with custom ones that can carry your own branding, visual elements, and communication tone.

Built-in templates​

When you set the account recovery method to code, the system uses these templates:

  • recovery_code.valid: Sent if the user provided a recovery address that belongs to a registered account.
  • recovery_code.invalid: Sent if the user provided an address that doesn't belong to a known account.

When you set the account recovery method to link, the system uses these templates:

  • recovery.valid
  • recovery.invalid
info

To read more about the recovery flow, read Account recovery and password reset.

Using custom message templates​

You can use custom templates in place of built-in ones. If you don't specify a custom template, the system automatically uses the built-in one.

To use custom email templates, go to Customize → Email Configuration on the Ory Console and select the email template you want to customize from the Email Templates section at the bottom of the page.

Creating templates​

Templates use the Go template engine in the text/template package for rendering the email.subject.gotmpl and email.body.plaintext.gotmpl templates, and the html/template package for rendering the email.body.gotmpl template.

Learn more:

tip

Templates can use the Sprig library, which provides more than 100 commonly used template functions

danger

For security reasons, these Spring functions are disabled in the Ory Network:

  • Date functions: date,date_in_zone,date_modify, now, htmlDate, htmlDateInZone, dateInZone, dateModify
  • Strings: randAlphaNum, randAlpha, randAscii, randNumeric, uuidv4
  • OS: env, expandenv
  • Network: getHostByName

Available variables​

The variables available for use in email templates change depending on the flow and the selected method:

TemplateVariables
recovery_code.validTo the email address the email will be sent to
RecoveryCode the recovery code
Identity the identity to be recovered
recovery_code.invalidTo the email address the email will be sent to
recovery.validTo the email address the email will be sent to
RecoveryURL the recovery link
Identity the identity to be recovered
recovery.invalidTo the email address the email will be sent to

Mandatory template formats​

Each template must have two versions: html and plaintext.

  • html version uses the HTML syntax to achieve the desired look and functionality (such as clickable buttons) of the email message.
  • plaintext version can't contain any HTML. Must contain only plain text content and any necessary gotmpl logic. This version is used as a fallback when the html version cannot be delivered, for example when the user's mail server blocks HTML in all incoming messages.
courier/template/templates/verification/valid/email.body.gotmpl
Hi, please verify your account by clicking the following link:

<a href="{{ .VerificationURL }}">{{ .VerificationURL }}</a>

Customizing template content for specific users​

To enable customizing the content of templates based on the identity of the recipient of the email, the Identity object is available inside the templates. This object is a map containing all the attributes of an identity defined in the identity schema, such as id, state, recovery_addresses, verifiable_addresses and traits.

tip

Read this document to learn more about the Ory Identity and the identity schema.

Translated templates (i18n)​

You can use nested templates to render email.subject.gotmpl, email.body.gotmpl and email.body.plaintext.gotmpl templates based on user settings, for example based on their chosen language.

To enable i18n customization of templates, customize the identity schema to include the user's preferred communication language. For example:

Sample custom Identity Schema with user language
{
  // ...
  "properties": {
    "traits": {
      "type": "object",
      "properties": {
        // ...
        "lang": {
          "type": "string",
          "title": "Your preferred language"
      },
      "required": [
        "email"
      ],
      "additionalProperties": false,
    }
  }
}

This identity trait can then be used inside the template to render a section conditionally.

The following example defines various templates for the recovery_code.valid template and renders the respective template depending on the language set in the lang identity traits, that was defined above:

recovery_code/valid/email.body.gotmpl
{{define "en"}}
Hi,

Please enter the following code to recover your account:

{{ .RecoveryCode }}
{{end}}

{{define "fr"}}
Bonjour,

Veuillez entrer le code suivant pour récupérer votre compte:

{{ .RecoveryCode }}
{{end}}

{{define "de"}}
Hallo,

Bitte geben Sie den folgenden Code ein, um Ihr Konto wiederherzustellen:

{{ .RecoveryURL }}
{{end}}

{{- else if eq .Identity.traits.lang "fr" -}}
{{ template "fr" . }}
{{- else if eq .Identity.traits.lang "de" -}}
{{ template "de" . }}
{{- else -}}
{{ template "en" . }}
{{- end -}}
tip

You can use Sprig functions in the nested templates. For security reasons, some functions are disabled in the Ory Network. Click here to see the list of disabled functions.

Metadata in templates​

As an administrator, you can set identity metadata, such as the user's language, in your application code using Identity metadata property. Read this document to learn more.

You can access metadata_public through .Identity.metadata_public in email templates.

The following example requires that the field lang is set in the public metadata. Your application could set this value after user completes registration.

recovery_code/valid/email.body.gotmpl
{{define "en"}}
Hi,

Please enter the following code to recover your account:

{{ .RecoveryCode }}
{{end}}

{{define "fr"}}
Bonjour,

Veuillez entrer le code suivant pour récupérer votre compte:

{{ .RecoveryCode }}
{{end}}

{{define "de"}}
Hallo,

Bitte geben Sie den folgenden Code ein, um Ihr Konto wiederherzustellen:

{{ .RecoveryURL }}
{{end}}

{{- else if eq .Identity.metadata_public.lang "fr" -}}
{{ template "fr" . }}
{{- else if eq .Identity.metadata_public.lang "de" -}}
{{ template "de" . }}
{{- else -}}
{{ template "en" . }}
{{- end -}}
danger

Since metadata is not validated by Ory Identities, missing entries or unexpected values can cause errors in the template rendering process. If the system encounters errors in the rendering process, Ory Identities uses the default templates.