Create a Message Template
On this page
FusionAuth uses email templates for a number of built in workflows.
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
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#
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.
{
"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 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
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
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 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
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
API documentation for the FusionAuth Complete Multi-Factor Authentication API.
API documentation for the FusionAuth Disable Multi-Factor API.
API documentation for the FusionAuth Enable Multi-Factor API.
API documentation for the FusionAuth Generate a Secret API.