Message Template Reference

On this page

This page contains an overview of each message template that ships with FusionAuth.

Retrieve Default Templates#

You can use the Admin UI to version control or customize templates. If you would rather have the message templates as a collection of files, they live in extractedcode/templates-messengers in the docs repository. Browse that folder to see exactly what you are getting, or download every file in it at once:

$ npx degit FusionAuth/fusionauth-site/astro/extractedcode/templates-messengers templates-messengers

If you would rather not use Node, pull the same folder out of a repository tarball:

$ curl -L https://github.com/FusionAuth/fusionauth-site/archive/refs/heads/main.tar.gz \
  | tar -xz --strip-components=4 fusionauth-site-main/astro/extractedcode/templates-messengers

Either command writes the templates into a templates-messengers directory. Both always match the folder linked above, so there is no separate list of files to fall out of date.

Forgot Password#

This is also known as the "Change Password" template.

[#setting url_escaping_charset="UTF-8"]
To change your password click on the following link.

  [#-- The optional 'state' map provided on the Forgot Password API call is exposed in the template as 'state'.
       If we have an application context, append the client_id to ensure the correct application theme when applicable.
  --]
[#assign url = "${baseUrl}/password/change/${changePasswordId}?client_id=${(application.oauthConfiguration.clientId)!''}&tenantId=${user.tenantId}" /]
[#list state!{} as key, value][#if key != "tenantId" && key != "client_id" && value??][#assign url = url + "&" + key?url + "=" + value?url/][/#if][/#list]

${url}

- FusionAuth Admin

Replacement Variables#

application Application

The Application object, see the Application API for field definitions.

Note: This object may not be available depending upon when this template is constructed. If you utilize this object in your template, ensure you first check to see if it is defined.

baseUrl String Available since 1.68.0

The base URL used when rendering links in this template. FusionAuth resolves this value from the Application baseURL, then the Tenant baseURL, then a local development fallback URL.

changePasswordId String

The change password Id that must be included as a path segment in the /password/change link. See the theme variables documentation for more information on how this value is used.

state Object

If the state was provided during the Forgot Password request, it will be available to you in the message template.

tenant Tenant

The Tenant object, see the Tenant API for field definitions.

user User

The User object, see the User API for field definitions of a User.

[#setting url_escaping_charset="UTF-8"]
You have requested to log into FusionAuth using this phone number. If you do not recognize this request please ignore this message.

[#if oneTimeCode??]
  Login code: ${oneTimeCode}
[#else]
[#-- The optional 'state' map provided on the Start Passwordless API call is exposed in the template as 'state' --]
    [#assign url = "${baseUrl}/oauth2/passwordless/${code}?tenantId=${user.tenantId}" /]
    [#list state!{} as key, value][#if key != "tenantId" && value??][#assign url = url + "&" + key?url + "=" + value?url/][/#if][/#list]

    ${url}
[/#if]

- FusionAuth Admin

Replacement Variables#

application Application

The Application object, see the Application API for field definitions.

Note: This object may not be available depending upon when this template is constructed. If you utilize this object in your template, ensure you first check to see if it is defined.

baseUrl String Available since 1.68.0

The base URL used when rendering links in this template. FusionAuth resolves this value from the Application baseURL, then the Tenant baseURL, then a local development fallback URL.

code String

The unique code intended to be used by the Complete a Passwordless Login API.

state Object

If the state was provided when the Passwordless request was initiated, it will be available to you in the template.

tenant Tenant

The Tenant object, see the Tenant API for field definitions of a Tenant.

user User

The User object, see the User API for field definitions of a User.

Phone Verification#

[#-- When a one-time code is provided, you will want the user to enter this value interactively using a form. In this workflow the verificationId
     is not shown to the user and instead the one-time code must be paired with the verificationId which is usually in a hidden form field. When the two
     values are presented together, the phone number can be verified --]
[#if verificationOneTimeCode??]
Verification code: ${verificationOneTimeCode}
[#else]
To complete your phone number verification click on the following link.

${baseUrl}/phone/verify/${verificationId}?client_id=${(application.oauthConfiguration.clientId)!''}&tenantId=${tenant.id}
[/#if]

- FusionAuth Admin

Replacement Variables#

application Application

The Application object, see the Application API for field definitions.

Note: This object may not be available depending upon when this template is constructed. If you utilize this object in your template, ensure you first check to see if it is defined.

baseUrl String Available since 1.68.0

The base URL used when rendering links in this template. FusionAuth resolves this value from the Application baseURL, then the Tenant baseURL, then a local development fallback URL.

tenant Tenant

The Tenant object, see the Tenant API for field definitions.

user User

The User object, see the User API for field definitions of a User.

verificationId String

The verification Id intended to be used by the Identity Verify API.

verificationOneTimeCode String

The verification One Time Code (OTP) to be used with the gated Phone Verification workflow. The user enters this code to verify their phone number.

Set Up Password#

Your account has been created and you must click the following link to set a password.

${baseUrl}/password/change/${changePasswordId}?client_id=${(application.oauthConfiguration.clientId)!''}&tenantId=${user.tenantId}

Replacement Variables#

application Application

The Application object, see the Application API for field definitions.

Note: This object may not be available depending upon when this template is constructed. If you utilize this object in your template, ensure you first check to see if it is defined.

baseUrl String Available since 1.68.0

The base URL used when rendering links in this template. FusionAuth resolves this value from the Application baseURL, then the Tenant baseURL, then a local development fallback URL.

changePasswordId String

The change password Id intended to be used by the Change a User's Password API.

tenant Tenant

The Tenant object, see the Tenant API for field definitions.

user User

The User object, see the User API for field definitions of a User.

Threat Detected#

Enterprise plan required

This feature requires an Enterprise plan.

[#setting url_escaping_charset="UTF-8"]
[#if event.type == "UserLoginSuspicious"]
A suspicious login was made on your account. If this was you, you can safely ignore this message. If this wasn't you, we recommend that you change your password as soon as possible.
[#elseif event.type == "UserLoginNewDevice"]
A login from a new device was detected on your account. If this was you, you can safely ignore this message. If this wasn't you, we recommend that you change your password as soon as possible.
[#else]
Suspicious activity has been observed on your account. In order to secure your account, it is recommended to change your password at your earliest convenience.
[/#if]

Device details

* Device name: ${(event.info.deviceName)!'-'}
* Device description: ${(event.info.deviceDescription)!'-'}
* Device type: ${(event.info.deviceType)!'-'}
* User agent: ${(event.info.userAgent)!'-'}

Event details

* IP address: ${(event.info.ipAddress)!'-'}
* City: ${(event.info.location.city)!'-'}
* Country: ${(event.info.location.country)!'-'}
* Zipcode: ${(event.info.location.zipcode)!'-'}
* Lat/long: ${(event.info.location.latitude)!'-'}/${(event.info.location.longitude)!'-'}

- FusionAuth Admin

Replacement Variables#

application Application

The Application object, see the Application API for field definitions.

event.info EventInfo

The EventInfo object, see the User Login Suspicious event definition for example field definitions.

tenant Tenant

The Tenant object, see the Tenant API for field definitions.

user User

The User object, see the User API for field definitions of a User.

Two-Factor Authentication#

Enterprise plan required

This feature requires an Enterprise plan.

FusionAuth ships two templates for a two-factor code request, one for messengers that deliver text and one for messengers that place a voice call. The voice template uses spokenCode rather than code so that the digits are read out individually instead of as a single number.

Text#

Used by messengers that deliver the code as a message, whether that is SMS, RCS, or a chat platform such as WhatsApp.

Two Factor Code: ${code}

Voice#

Used by messengers that deliver the code as a phone call.

This is your two factor code: ${spokenCode}, repeat ${spokenCode}

Replacement Variables#

application Application

The Application object, see the Application API for field definitions.

Note: This object may not be available depending upon when this template is constructed. If you utilize this object in your template, ensure you first check to see if it is defined. You can check for this variable safely in FreeMarker using the missing value test operator and an if statement:

[#if application??]
[#-- Use application here --]
[/#if]

This object is not available on the message template when:

The multi-factor workflow was started without providing the applicationId on that request.
Multi-factor authentication is required during a call to the login API without providing the applicationId parameter. That documentation points out that there is likely no production use case where calling the API without the applicationId parameter is useful.
The message is being sent to enable or disable a multi-factor method without providing the applicationId on the request.

code String

A code that the user must provide to complete multi-factor authentication.

email String

Email address associated with the user.

mobilePhone String

Mobile phone number associated with the user.

spokenCode String

The same code as code, with the digits separated so that a voice messenger reads them out one at a time rather than as a single number. Use this instead of code in templates delivered by voice.

tenant Tenant

The Tenant object, see the Tenant API for field definitions.

user User

The User object, see the User API for field definitions of a User.

Two-Factor Authentication Method Added#

Enterprise plan required

This feature requires an Enterprise plan.

The following two factor method was added to ${user.phoneNumber}:

- Method: ${method.method}
- Identifier: ${method.id}

- FusionAuth Admin

Replacement Variables#

application Application

The Application object, see the Application API for field definitions.

Note: This object may not be available depending upon when this template is constructed. If you utilize this object in your template, ensure you first check to see if it is defined. You can check for this variable safely in freemarker by wrapping the variable as such: ${(application)!""}.

event Event

The Event object for a two-factor add event. See the Webhooks & Events section for field definitions.

method Object

The two-factor method that was added. See the Multi-Factor/Two-Factor APIs for property definitions and example JSON.

tenant Tenant

The Tenant object, see the Tenant API for field definitions.

user User

The User object, see the User API for field definitions of a User.

Two-Factor Authentication Method Removed#

Enterprise plan required

This feature requires an Enterprise plan.

The following two factor method was removed from ${user.phoneNumber}:

- Method: ${method.method}
- Identifier: ${method.id}

- FusionAuth Admin

Replacement Variables#

application Application

The Application object, see the Application API for field definitions.

Note: This object may not be available depending upon when this template is constructed. If you utilize this object in your template, ensure you first check to see if it is defined. You can check for this variable safely in freemarker by wrapping the variable as such: ${(application)!""}.

event Event

The Event object for a two-factor remove event. See the Webhooks & Events section for field definitions.

method Object

The two-factor method that was removed. See the Multi-Factor/Two-Factor APIs for property definitions and example JSON.

tenant Tenant

The Tenant object, see the Tenant API for field definitions.

user User

The User object, see the User API for field definitions of a User.

Admin Two-Factor Authentication Method Removed#

Your ${(method.method == "sms")?then("SMS", method.method)} two-factor authentication method[#if method.name?has_content], ${method.name},[/#if] was removed from ${user.phoneNumber} by your administrator. Contact your administrator if you have questions.

Replacement Variables#

method Object Available since 1.68.0

The two-factor method that was removed by an administrator. See the User API under user.twoFactor.methods for property definitions and example JSON.

tenant Tenant Available since 1.68.0

The Tenant object, see the Tenant API for field definitions.

user User Available since 1.68.0

The User object, see the User API for field definitions of a User.

A collection of default email templates that ship with FusionAuth.

replacement variablesfreemarker

APIs

API documentation for the FusionAuth Create an Email Template API.

freemarker

APIs

Learn about the APIs for creating, retrieving, updating and deleting email templates as well as sending emails to users.

freemarker