# Create a Message Template

Learn how to write and manage message templates.

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

FusionAuth uses email templates for [a number of built in workflows](https://fusionauth.io/docs/messengers/template-reference.md).

The message template body supports replacement variables. This means placeholders can be inserted and the value will be calculated at the time the message template is rendered and sent to a User.

Most templates will contain the User object as returned on the Retrieve User API. This means you can utilize any value found on the User object such as email, first name, last name, etc.

## Preview Message Templates

To preview message templates:

*   in the Admin UI, go to Customizations -> Message Templates -> Edit -> Preview
*   use the [Message Template API](https://fusionauth.io/docs/apis/message-templates.md)

Preview template rendering uses the following sample values:

| Parameter | Sample Value | Purpose |
| --- | --- | --- |
| `${application}` | `{ "name": "My Application", "oauthConfiguration": { "clientId": "123456" } }` | Application name, `oauthConfiguration.clientId` for themed message links |
| `${baseUrl}` | `https://example.com` | Base URL used when rendering links in message templates. |
| `${changePasswordId}` | `1234567890` | Embedded in change password and set password URLs |
| `${code}` | `123456` | Embedded in MFA/Two-Factor messages |
| `${event}` | `{ "type": "UserLoginSuspicious", "info": {...} }` | Embedded in User Event messages |
| `${method}` | `{ "id" : "FQLM", "method" : "email" }` | Embedded in Two-Factor Add/Remove event messages |
| `${oneTimeCode}` | `88888` | Embedded in passwordless login messages |
| `${spokenCode}` | `1 2 3 4 5 6` | Embedded in MFA/Two-Factor messages when sent via voice. Use instead of `{code}` so the code is not read as a single number. |
| `${tenant}` | `{ "name": "My Tenant", "id": "78910" }` | `tenant.id` allows links embedded in messages to render using the correct theme for that tenant. |
| `${user}` | `{ "firstName": "John", "lastName": "Doe" }` | User information and `user.tenantId` for themed message links |
| `${verificationId}` | `987654` | Embedded in phone number verification messages |
| `${verificationOneTimeCode}` | `abcdef` | Embedded in phone number verification messages |

## Use Replacement Variables

Note

Always configure either the Application or Tenant **baseURL** to a public URL such as `https://auth.example.com` so links rendered from templates point to the correct host.

The following example demonstrates how to use replacement values in your message templates.

Consider the following User represented by this condensed JSON object.

```json
{
  "phoneNumber": "+15555551234",
  "firstName": "Monica",
  "id": "1c592f8a-59c6-4a09-82f8-f4257e3ea4c8",
  "lastName": "Hall"
}
```

The following are example usages with a rendered output based upon the above mentioned example User. The replacement variables are rendered using [Apache FreeMarker](https://freemarker.apache.org/docs/index.html) which is an HTML template language.

A default value should be provided for variables that may be undefined at runtime such as `firstName`. See `firstName` in the example below is followed by a bang `!` and then the string `Unknown User`. This indicates that if `firstName` is undefined when the template is rendered the value of `Unknown User` should be used as a default value.

*Template Source*

```ftl
Hi ${user.firstName!'Unknown User'}, welcome to Pied Piper.

Please verify your phone number ${user.phoneNumber} by following the provided link.

https://piedpiper.fusionauth.io/identity/verify/${verificationId}
- Admin
```

*Rendered Output*

```html
Hi Monica, welcome to Pied Piper.

Please verify your phone number +15555551234 by following the provided link.

https://piedpiper.fusionauth.io/identity/verify/YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4
- Admin
```

## Manage Templates

FusionAuth ships default templates for the text and voice two-factor workflows, but they are built into the product rather than stored as message templates you can edit, so Customizations -> Message Templates is empty on a new installation. That list shows only the templates you create. The built-in defaults are still used when a workflow has no template assigned, and they are not assigned to the tenant Multi-Factor settings by default.

To customize one, create a message template using the default content from the [Template Reference](https://fusionauth.io/docs/messengers/template-reference.md) page as a starting point, then select it under Tenants -> Edit -> Multi-Factor .

To add new templates:

*   in the Admin UI, go to Customizations -> Message Templates
*   use the [Message Template API](https://fusionauth.io/docs/apis/message-templates.md)

### Base Information

`Id`

*   optional

The unique Id of the Message Template. The template Id may not be changed and will be used to interact with the template when using the APIs.

`Name`

*   required

The name of the template. This value is for display purposes only and can be changed at any time.

`Type`

*   required

The type of the template. Supported values are `SMS` and `Voice`.

## Localization

The message template body can be localized.

You can associate the template text values with a locale. If a user has a preferred language, the localized template will be used when this text message is sent.

Related

[APIs Complete Multi-Factor Authentication API API documentation for the FusionAuth Complete Multi-Factor Authentication API. multi-factor authentication](https://fusionauth.io/docs/apis/login/complete-mfa.md)

[APIs Disable Multi-Factor API API documentation for the FusionAuth Disable Multi-Factor API. multi-factor authentication](https://fusionauth.io/docs/apis/two-factor/disable-multi-factor.md)

[APIs Enable Multi-Factor API API documentation for the FusionAuth Enable Multi-Factor API. multi-factor authentication](https://fusionauth.io/docs/apis/two-factor/enable-multi-factor.md)

[APIs Generate a Secret API API documentation for the FusionAuth Generate a Secret API. multi-factor authentication](https://fusionauth.io/docs/apis/two-factor/generate-a-secret.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.
- [Message Template Reference](https://fusionauth.io/docs/messengers/template-reference.md): A list of default message templates.
- [Configure a Twilio Messenger](https://fusionauth.io/docs/messengers/twilio-messenger.md): Learn how to add and configur a Twilio Messenger.