Email Templates

Overview

Email templates are utilized by FusionAuth to send a Forgot Password request, and other built in workflows. You may also create your own email templates and send them to Users via the Send Email API.

FusionAuth ships with three templates to support Forgot Password, Setup Password and Verify Email workflows. You will need to modify these templates prior to using them in production.

Apart from modifying them to be more cosmetically pleasing or to match your brand, you will need to ensure the URL used in the template is correct. You will need to ensure the URL is publicly accessible.

When you first log into FusionAuth and navigate to Settings Email Templates you will see the following three templates.

For example, below is the email body of the Email Verification template as it is shipped with FusionAuth.

At a minimum, you will need to update this URL to a publicly accessible URL that can reach FusionAuth.

If you will be handling Email Verification yourself, you will need to update this URL to be that of your own. You will notice the one replacement variable in this template named ${verificationId}. See the Replacement Variables section below for additional detail, but these variables will be replaced when the template is rendered.

Table 1. Base Information
Id	The unique Id of the email template. The template Id may not be changed and will be used to interact with the template when using the Email APIs.
Name Required	The name of the template. This value is for display purposes only and can be changed at any time.
Default Subject Required	The default subject of the email. The default value will be used unless a localized version is found to be a better match based upon the User’s preferred locales. This field supports replacement variables.
From Email Required	The from email address used to send this template.
Default from Name Optional	The default from name of the email. The default value will be used unless a localized version is found to be a better match based upon the User’s preferred locales. This field supports replacement variables.

Replacement Variables

The email template body, subject and from name fields support replacement variables. This means place holders can be inserted and the value will be calculated at the time the email template is rendered and sent to a user.

Each template 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.

In addition to the User object, the templates used for Email Verification, Forgot Password and Setup Password will also contain an identifier that will be used to complete the request. The following table defines the additional available replacement variables you have access to in these provided templates.

Template Replacement Values

Template	Replacement Values
Email Verification	`verificationId` The verification Id intended to be used by the Verify Email API.
Forgot Password & Setup Password	`changePasswordId` The change password Id intended to be used by the Change Password API.

Email Verification

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

Forgot Password & Setup Password

changePasswordId
The change password Id intended to be used by the Change Password API.

For example, consider the following User represented by this condensed JSON object.

{
  "email": "monica@piedpiper.com",
  "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 email address ${user.email} by following the provided link.

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

Rendered Output

Hi Monica, welcome to Pied Piper.

Please verify your email address monica@piedpiper.com by following the provided link.

https://piedpiper.fusionauth.io/email/verify/YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4
- Admin

Custom Replacement Variables

In addition to the variables mentioned in the previous section, when defining your own email templates to be used by the Send Email API custom data may be provided on the API request to be used in the email template.

On Send Email API request the contents of the requestData field will be made available to you when the template is rendered.

For example, consider the following request to the Send API to send email template Id 1bc118ae-d5fa-4cdf-a90e-e8ef55c3e11e to the User by Id ce485a91-906f-4615-af75-81d37dc71e90.

URI

POST /api/email/send/1bc118ae-d5fa-4cdf-a90e-e8ef55c3e11e

Example Request JSON

{
  "requestData": {
    "paymentAmount": "$9.99",
    "product": "party hat",
    "quantity": "12"
  },
  "userIds": [
    "ce485a91-906f-4615-af75-81d37dc71e90"
  ]
}

Template Source

Hello ${user.firstName!''},

Thank you for your purchase! We value your business, please come again!

Product: ${requestData.product!'unknown'}
Quantity: ${requestData.quantity!'unknown`}

- Pied Piper Customer Success

Rendered Output

Hello Kelly,

Thank you for your purchase! We value your business, please come again!

Product: party hat
Quantity: 12

- Pied Piper Customer Success