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

Account recovery

When you set the account verification method to code, the system uses the recovery_code.valid template to send the recovery code to the user.

If you enabled sending attempted recovery notifications to unregistered addresses, the system uses the recovery_code.invalid template.

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

• recovery.valid
• recovery.invalid

info

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

Address verification

When you set the account verification method to code, the system uses the verification_code.valid template to send the verification code and a URL to the form to the user.

If you enabled notifications to unknown recipients, the verification_code.invalid template is used.

If you set the account verification method to link, the system uses these templates instead:

• verification.valid
• verification.invalid

info

To read more about the verification flow, read Email and phone verification.

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.

Ory Console

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.

Ory CLI

1. List all your projects and get the Ory Identities config file:

   ## List all available projects
   ory list projects
   
   ## Get config
   ory get identity-config <project-id> --format yaml > identity-config.yaml

2. Add your Base64-encoded custom message templates to the config:

   identity-config.yaml

   courier:
     smtp:
       from_name: MyProject via Ory
     templates:
       recovery:
         invalid:
           email:
             body: { "html": "base64://ENCODED_HTML_TEMPLATE", "plaintext": "base64://ENCODED_PLAINTEXT_TEMPLATE" }
         valid:
           email:
             body: {}
       verification:
         invalid:
           email:
             body: {}
         valid:
           email:
             body: {}

3. Upload the edited config:

   ory update identity-config <project-id> --file updated_config.yaml

danger

In the Ory Network, you can use only Base64-encoded templates. http:// or file:// URIs are not supported. If you provide custom templates using unsupported methods, the system uses the default templates.

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:

• https://pkg.go.dev/text/template
• https://pkg.go.dev/html/template

tip

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

danger

For security reasons, these Sprig 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:

Recovery (via code)

For the recovery_code.valid template, the following variables are available:

Variable	Description
To	The email address the email will be sent to
RecoveryCode	The recovery code
Identity	The identity to be recovered

note

The recovery_code.invalid template does not allow to send a direct link to the user, as the recovery flow enforces anti-CSRF measures, which would lead to the flow failing, in case the user opens the link in a different browser.

For the recovery_code.invalid template, the following variables are available:

Variable	Description
To	the email address the email will be sent to

Verification (via code)

For the verification_code.valid template, the following variables are available:

Variable	Description
To	the email address the email will be sent to
VerificationCode	the verification code
VerificationURL	the verification link
Identity	the identity of the email address

For the verification_code.invalid template, the following variables are available:

Variable	Description
To	the email address the email will be sent to

Recovery (via magic link)

For the recovery.valid template, the following variables are available:

Variable	Description
To	The email address the email will be sent to
RecoveryURL	The recovery link
Identity	The identity to be recovered

For the recovery.invalid template, the following variables are available:

Variable	Description
To	the email address the email will be sent to

Verification (via magic link)

For the verification.valid template, the following variables are available:

Variable	Description
To	the email address the email will be sent to
VerificationURL	the verification link
Identity	the identity of the email address

For the verification.invalid template, the following variables are available:

Variable	Description
To	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.

HTML

courier/template/templates/verification/valid/email.body.gotmpl

Hi, please verify your account by clicking the following link:

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

Plain text

The plaintext version doesn't contain any HTML and keeps only the gotmpl logic ({{ .VerificationURL }}) and plain text.

courier/template/templates/verification/valid/email.body.plaintext.gotmpl

Hi, please verify your account by clicking the following link: {{ .VerificationURL }}

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.