Custom Email and SMS Templates
Modify the template for emails and SMS messages for your Authgear project.
Authgear sends emails and SMS messages for events such as verifying an email address, signing in with a one-time password (OTP) or magic link, and resetting a password. You can fully customize the wording, branding, and layout of these messages from the Portal.
To set a custom email or SMS template, log in to Authgear Portal then navigate to Branding > Email/SMS Templates.
Note: You must upgrade your project plan to a paid plan to edit the templates.
How templates work
Messages are rendered with Go's templating engine, and translation strings additionally support ICU MessageFormat for pluralization and selection. You can mix both in a single string:
Insert a value with
{{ .Code }}(Go template) or{Code}(ICU).Branch on a value with
{{ if .HasPassword }}…{{ else }}…{{ end }}(Go template) or{HasPassword, select, true{…} other{…}}(ICU).
The teamplates support the same set of variables described below.
Template variables
Available in every email and SMS template
{{ template "app.name" }}
Your organization's name.
The organization name is referenced as {{ template "app.name" }}, not as a data field. It is itself a translatable string, so changing the app.name translation updates it everywhere at once.
Per message type
{{ .Code }}
The one-time verification / OTP code. For magic-link and reset-by-link messages this is the same code encoded in the link.
Email/SMS verification, OOB OTP, login link, forgot password (link and OTP), WhatsApp OTP
{{ .Link }}
The full magic sign-in / verification / reset link.
Login-link and forgot-password link messages
{{ .Email }}
The recipient's email address.
Email messages, new-user password email
{{ .Phone }}
The recipient's phone number.
SMS messages
{{ .Password }}
An administrator-generated password.
"Send password to user" emails (Welcome email)
Advanced variables
These variables are also available in the rendering context. They are not used by the built-in templates, but you can reference them in custom templates.
{{ .HasPassword }}
boolean
true if the user already has a password set. Use it to switch wording between "reset" and "set" a password.
Forgot-password email/SMS
{{ .Host }}
string
The host the request originated from (e.g. auth.example.com).
OTP, verification, login-link, forgot-password
{{ .ClientID }}
string
The OAuth client ID that started the flow.
Interactive web flows only
{{ .ClientName }}
string
The OAuth client's display name.
Interactive web flows only
{{ .State }}
string
The OAuth state parameter.
Interactive web flows only
{{ .XState }}
string
The Authgear x_state parameter.
Interactive web flows only
{{ .UILocales }}
string
The requested ui_locales.
Interactive web flows only
Variables marked "Interactive web flows only" are populated from the request's UI parameters. They are empty when a message is sent outside an interactive flow, for example via the Admin API.
Variables by message
Variables you can use in each message in the Email/SMS Templates page.
Reset Password by Link
{{ .Link }}, {{ .Code }}
Reset Password by OTP
{{ .Code }}
Verification
{{ .Code }}
Passwordless via Email
{{ .Link }} (link mode) or {{ .Code }} (OTP mode)
Passwordless via SMS
{{ .Code }}
MFA via Email
{{ .Code }}
MFA via SMS
{{ .Code }}
Welcome Message
{{ .Email }}, {{ .Password }}
Examples
SMS verification
Set password vs. reset password using {{ .HasPassword }}
The forgot-password (link) message is also used to let a new user set their first password. Use {{ .HasPassword }} to adapt the wording.
Two equivalent forms are supported: ICU select (handy for one-line subjects) and Go-template if (handy for multi-line bodies)
Subject:
Email content:
Important notice for sending SMS to Chinese phone numbers (+86):
The template for SMS to Chinese numbers cannot be modified. As a result, Authgear will always use the default template for Chinese numbers even when you have set a custom template. All SMS other than OTPs (e.g. password reset links) will not be delivered.
Authgear will use your custom SMS template for other users with non-Chinese phone numbers.
The following is the content of the SMS template regardless of locale when sending to a Chinese phone number:
The reason for this fallback is that services are required to register their SMS templates in advance with the officials before they can deliver to Chinese numbers. Authgear has registered the default SMS template such that it will deliver without any further action on your side.
Enterprise users who still wish to customize their SMS template for Chinese numbers can contact us for more details.
Important notice for sending SMS to Vietnamese (+84) and Taiwanese (+886) phone numbers
Due to the regulatory requirements from the local governments, all SMS messages to Vietnam & Taiwan must include the application name in the message body. If your users in Vietnam & Taiwan experience difficulties receiving SMS, try adding [Authgear] at the begining of the SMS template. SMS without [Authgear] may be blocked by the mobile operators. For example, your OTP message could appears like:
Enterprise users who still wish to customize the beginning part of the message for Vietnamese & Taiwanese numbers can contact us for more details.
Last updated
Was this helpful?