# Message Template Reference

A list of default message templates.

> For the index of this section of the site, see [llms.txt](https://fusionauth.io/docs/llms.txt)

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](https://github.com/FusionAuth/fusionauth-site/tree/main/astro/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:

```shell-session
$ 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:

```shell-session
$ 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.

```ftl
[#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](https://fusionauth.io/docs/apis/applications.md) 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](https://fusionauth.io/docs/theme/advanced-themes/template-variables.md) 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](https://fusionauth.io/docs/apis/tenants.md) for field definitions.

`user`

*   User

The User object, see the [User API](https://fusionauth.io/docs/apis/users.md) for field definitions of a User.

## Passwordless Login

```ftl
[#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](https://fusionauth.io/docs/apis/passwordless/complete-a-passwordless-login.md) 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](https://fusionauth.io/docs/apis/users.md) for field definitions of a User.

## Phone Verification

```ftl
[#-- 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](https://fusionauth.io/docs/apis/tenants.md) for field definitions.

`user`

*   User

The User object, see the [User API](https://fusionauth.io/docs/apis/users.md) for field definitions of a User.

`verificationId`

*   String

The verification Id intended to be used by the [Identity Verify](https://fusionauth.io/docs/apis/identity-verify.md) 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

```ftl
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](https://fusionauth.io/docs/apis/users/change-password.md) API.

`tenant`

*   Tenant

The Tenant object, see the [Tenant API](https://fusionauth.io/docs/apis/tenants.md) for field definitions.

`user`

*   User

The User object, see the [User API](https://fusionauth.io/docs/apis/users.md) for field definitions of a User.

## Threat Detected

> **PLAN:** This feature requires [an Enterprise plan](https://fusionauth.io/docs/get-started/core-concepts/plans-features.md#enterprise-features).

```ftl
[#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](https://fusionauth.io/docs/apis/applications.md) for field definitions.

`event.info`

*   EventInfo

The EventInfo object, see the [User Login Suspicious](https://fusionauth.io/docs/extend/events-and-webhooks/events/user/login/user-login-suspicious.md) event definition for example field definitions.

`tenant`

*   Tenant

The Tenant object, see the [Tenant API](https://fusionauth.io/docs/apis/tenants.md) for field definitions.

`user`

*   User

The User object, see the [User API](https://fusionauth.io/docs/apis/users.md) for field definitions of a User.

## Two-Factor Authentication

> **PLAN:** This feature requires [an Enterprise plan](https://fusionauth.io/docs/get-started/core-concepts/plans-features.md#enterprise-features).

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.

```ftl
Two Factor Code: ${code}
```

### Voice

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

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

### Replacement Variables

`application`

*   Application

The Application object, see the [Application API](https://fusionauth.io/docs/apis/applications.md) 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:

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

This object is not available on the message template when:

*   The multi-factor workflow was [started](https://fusionauth.io/docs/apis/two-factor/start-multi-factor.md) without providing the `applicationId` on that request.
*   Multi-factor authentication is required during a call to the [login API](https://fusionauth.io/docs/apis/login/authenticate.md) 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](https://fusionauth.io/docs/apis/two-factor/send-a-multi-factor-code-when-enabling-mfa.md) or [disable](https://fusionauth.io/docs/apis/two-factor/send-a-multi-factor-code-when-disabling-mfa.md) 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](https://fusionauth.io/docs/apis/tenants.md) for field definitions.

`user`

*   User

The User object, see the [User API](https://fusionauth.io/docs/apis/users.md) for field definitions of a User.

## Two-Factor Authentication Method Added

> **PLAN:** This feature requires [an Enterprise plan](https://fusionauth.io/docs/get-started/core-concepts/plans-features.md#enterprise-features).

```ftl
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](https://fusionauth.io/docs/apis/applications.md) 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](https://fusionauth.io/docs/extend/events-and-webhooks/events/user/user-two-factor-method-add.md) for field definitions.

`method`

*   Object

The two-factor method that was added. See the [Multi-Factor/Two-Factor APIs](https://fusionauth.io/docs/apis/two-factor.md) for property definitions and example JSON.

`tenant`

*   Tenant

The Tenant object, see the [Tenant API](https://fusionauth.io/docs/apis/tenants.md) for field definitions.

`user`

*   User

The User object, see the [User API](https://fusionauth.io/docs/apis/users.md) for field definitions of a User.

## Two-Factor Authentication Method Removed

> **PLAN:** This feature requires [an Enterprise plan](https://fusionauth.io/docs/get-started/core-concepts/plans-features.md#enterprise-features).

```ftl
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](https://fusionauth.io/docs/apis/applications.md) 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](https://fusionauth.io/docs/extend/events-and-webhooks/events/user/user-two-factor-method-remove.md) for field definitions.

`method`

*   Object

The two-factor method that was removed. See the [Multi-Factor/Two-Factor APIs](https://fusionauth.io/docs/apis/two-factor.md) for property definitions and example JSON.

`tenant`

*   Tenant

The Tenant object, see the [Tenant API](https://fusionauth.io/docs/apis/tenants.md) for field definitions.

`user`

*   User

The User object, see the [User API](https://fusionauth.io/docs/apis/users.md) for field definitions of a User.

## Admin Two-Factor Authentication Method Removed

```plaintext
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](https://fusionauth.io/docs/apis/users.md) under `user.twoFactor.methods` for property definitions and example JSON.

`tenant`

*   Tenant
*   Available since 1.68.0

The Tenant object, see the [Tenant API](https://fusionauth.io/docs/apis/tenants.md) for field definitions.

`user`

*   User
*   Available since 1.68.0

The User object, see the [User API](https://fusionauth.io/docs/apis/users.md) for field definitions of a User.

Related

[Email Email Template Reference A collection of default email templates that ship with FusionAuth. replacement variablesfreemarker](https://fusionauth.io/docs/email/template-reference.md)

[APIs Create an Email Template API API documentation for the FusionAuth Create an Email Template API. freemarker](https://fusionauth.io/docs/apis/emails/create-an-email-template.md)

[APIs Email API Learn about the APIs for creating, retrieving, updating and deleting email templates as well as sending emails to users. freemarker](https://fusionauth.io/docs/apis/emails.md)

[APIs Preview an Email Template API API documentation for the FusionAuth Preview an Email Template API. freemarker](https://fusionauth.io/docs/apis/emails/preview-an-email-template.md)
---

## Other pages in Messengers

> For the full index of this section, see [Messengers](https://fusionauth.io/docs/llms-messengers.txt).

- [Configure a Custom Messenger](https://fusionauth.io/docs/messengers/generic-messenger.md): Learn how to add and configure custom messengers.
- [Create a Message Template](https://fusionauth.io/docs/messengers/message-templates.md): Learn how to write and manage message templates.
- [Configure a Twilio Messenger](https://fusionauth.io/docs/messengers/twilio-messenger.md): Learn how to add and configur a Twilio Messenger.