> For the complete documentation index, see [llms.txt](/docs/llms.txt)

# Message Template API | FusionAuth Docs

Learn about the APIs for creating, retrieving, updating and deleting message templates.

# Message Template API

Available since `1.26.0`

This page contains the APIs for managing Message Templates as well as messaging users using those templates. Here are the APIs:

## Create a Message Template[#](#create-a-message-template)

This API is used to create a Message Template. Specifying an Id on the URI will instruct FusionAuth to use that Id when creating the Message Template. Otherwise, FusionAuth will generate an Id for the Message Template.

### Request[#](#request)

Create a Message Template without providing an Id. An Id will be automatically generated.

POST/api/message/template

OpenAPI Spec

Create a Message Template with the provided Id

POST/api/message/template/{messageTemplateId}

OpenAPI Spec

#### Request Parameters[#](#request-parameters)

`messageTemplateId`UUIDoptionalDefaults to secure random UUIDImmutable

The Id to use for the new Message Template. If not specified a secure random UUID will be generated.

#### Request Body[#](#request-body)

`messageTemplate.data`Objectoptional

An object that can hold any information about the Message Template that should be persisted.

`messageTemplate.defaultTemplate`\[String (FreeMarker Enabled)\]required

The default Message Template.

`messageTemplate.localizedTemplates`\[Map<Locale,String (FreeMarker Enabled)>\]optional

The Message Template used when sending messages to users who speak other languages. This overrides the default Message Template based on the user's list of preferred languages.

`messageTemplate.name`Stringrequired

A descriptive name for the Message Template (i.e. "Two-Factor Code Message")

`messageTemplate.type`Stringrequired

The type of the template. This must have the value `SMS` or `Voice`.

*Example Request JSON*

```
{
  "messageTemplate": {
    "data": {
      "updatedBy": "richard@fusionauth.io"
    },
    "defaultTemplate": "Here's your Two Factor Code: ${code}",
    "localizedTemplates": {
      "de": "Hier ist Ihr Zwei-Faktoren-Code: ${code}",
      "es": "Este es su código de dos factores: ${code}"
    },
    "name": "Default Two Factor Request",
    "type": "SMS"
  }
}
```

### Response[#](#response)

The response for this API contains the information for the Message Template that was created.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. The response will contain a JSON body. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](/docs/apis/errors) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](/docs/apis/authentication). |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |

#### Response Body[#](#response-body)

`messageTemplate.data`Object

An object that can hold any information about the Message Template that should be persisted.

`messageTemplate.defaultTemplate`\[String (FreeMarker Enabled)\]

The default Message Template.

`messageTemplate.id`UUID

The unique identifier for this Message Template.

`messageTemplate.insertInstant`Long

The [instant](/docs/reference/data-types#instants) that the Application was added to the FusionAuth database.

`messageTemplate.lastUpdateInstant`Long

The [instant](/docs/reference/data-types#instants) that the Application was last updated in the FusionAuth database.

`messageTemplate.localizedTemplates`Map<Locale,String (FreeMarker Enabled)>

The Message Template used when sending messages to users who speak other languages. This overrides the default Message Template based on the user's list of preferred languages.

`messageTemplate.name`String

A descriptive name for the message template.

`messageTemplate.type`String

The type of the template. This will have the value `SMS` or `Voice`.

*Example Response JSON for a Single Message Template*

```
{
  "messageTemplate": {
    "data": {
      "updatedBy": "richard@fusionauth.io"
    },
    "id": "da6edb51-3d1b-40cf-b791-43b657536621",
    "insertInstant": 1619822235060,
    "lastUpdateInstant": 1619822235060,
    "defaultTemplate": "Here's your Two Factor Code: ${code}",
    "localizedTemplates": {
      "de": "Hier ist Ihr Zwei-Faktoren-Code: ${code}",
      "es": "Este es su código de dos factores: ${code}"
    },
    "name": "Default Two Factor Request",
    "type": "SMS"
  }
}
```

## Retrieve a Message Template[#](#retrieve-a-message-template)

This API is used to retrieve one or all of the configured Message Templates. Specifying an Id on the URI will retrieve a single Message Template. Leaving off the Id will retrieve all of the Message Templates.

### Request[#](#request-1)

Retrieve all of the Message Templates

GET/api/message/template

OpenAPI Spec

Retrieve a single Message Template by Id

GET/api/message/template/{messageTemplateId}

OpenAPI Spec

#### Request Parameters[#](#request-parameters-1)

`messageTemplateId`UUIDoptional

The Id of the Message Template to retrieve.

### Response[#](#response-1)

The response for this API contains either a single Message Template or all of the Message Templates. When you call this API with an Id the response will contain just that Message Template. When you call this API without an Id the response will contain all of the Message Templates. Both response types are defined below along with an example JSON response.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. The response will contain a JSON body. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](/docs/apis/authentication). |
| 404 | The object you requested doesn't exist. The response will be empty. |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |

#### Response Body[#](#response-body)

`messageTemplate.data`Object

An object that can hold any information about the Message Template that should be persisted.

`messageTemplate.defaultTemplate`\[String (FreeMarker Enabled)\]

The default Message Template.

`messageTemplate.id`UUID

The unique identifier for this Message Template.

`messageTemplate.insertInstant`Long

The [instant](/docs/reference/data-types#instants) that the Application was added to the FusionAuth database.

`messageTemplate.lastUpdateInstant`Long

The [instant](/docs/reference/data-types#instants) that the Application was last updated in the FusionAuth database.

`messageTemplate.localizedTemplates`Map<Locale,String (FreeMarker Enabled)>

The Message Template used when sending messages to users who speak other languages. This overrides the default Message Template based on the user's list of preferred languages.

`messageTemplate.name`String

A descriptive name for the message template.

`messageTemplate.type`String

The type of the template. This will have the value `SMS` or `Voice`.

*Example Response JSON for a Single Message Template*

```
{
  "messageTemplate": {
    "data": {
      "updatedBy": "richard@fusionauth.io"
    },
    "id": "da6edb51-3d1b-40cf-b791-43b657536621",
    "insertInstant": 1619822235060,
    "lastUpdateInstant": 1619822235060,
    "defaultTemplate": "Here's your Two Factor Code: ${code}",
    "localizedTemplates": {
      "de": "Hier ist Ihr Zwei-Faktoren-Code: ${code}",
      "es": "Este es su código de dos factores: ${code}"
    },
    "name": "Default Two Factor Request",
    "type": "SMS"
  }
}
```

#### Response Body[#](#response-body)

`messageTemplates[x]`Array

The list of Message Template objects.

`messageTemplates[x].data`Object

An object that can hold any information about the Message Template that should be persisted.

`messageTemplates[x].defaultTemplate`\[String (FreeMarker Enabled)\]

The default Message Template.

`messageTemplates[x].id`UUID

The unique identifier for this Message Template.

`messageTemplates[x].insertInstant`Long

The [instant](/docs/reference/data-types#instants) that the Application was added to the FusionAuth database.

`messageTemplates[x].lastUpdateInstant`Long

The [instant](/docs/reference/data-types#instants) that the Application was last updated in the FusionAuth database.

`messageTemplates[x].localizedTemplates`Map<Locale,String (FreeMarker Enabled)>

The Message Template used when sending messages to users who speak other languages. This overrides the default Message Template based on the user's list of preferred languages.

`messageTemplates[x].name`String

A descriptive name for the message template.

`messageTemplates[x].type`String

The type of the template. This will have the value `SMS` or `Voice`.

*Example Response JSON for all Message Templates*

```
{
  "messageTemplates": [
    {
      "data": {
        "updatedBy": "richard@fusionauth.io"
      },
      "id": "da6edb51-3d1b-40cf-b791-43b657536621",
      "insertInstant": 1619822235060,
      "lastUpdateInstant": 1619822235060,
      "defaultTemplate": "Here's your Two Factor Code: ${code}",
      "localizedTemplates": {
        "de": "Hier ist Ihr Zwei-Faktoren-Code: ${code}",
        "es": "Este es su código de dos factores: ${code}"
      },
      "name": "Default Two Factor Request",
      "type": "SMS"
    }
  ]
}
```

## Update a Message Template[#](#update-a-message-template)

This API is used to update an existing Message Template.

You must specify all of the properties of the Message Template when calling this API with the `PUT` HTTP method. When used with `PUT`, this API doesn't merge the existing Message Template and your new data. It replaces the existing Message Template with your new data.

Utilize the `PATCH` HTTP method to send specific changes to merge into an existing Message Template.

### Request[#](#request-2)

Update a Message Template by Id

PUT/api/message/template/{messageTemplateId}

OpenAPI Spec

PATCH/api/message/template/{messageTemplateId}

OpenAPI Spec

For backward compatibility, the `PATCH` method accepts the same media type (specified by a `Content-Type` of `application/json`) and body as the `PUT` request. You can also use the following media types for different behavior:

*   [JSON Patch/RFC 6902](https://www.rfc-editor.org/rfc/rfc6902): `application/json-patch+json`
*   [JSON Merge Patch/RFC 7396](https://www.rfc-editor.org/rfc/rfc7396): `merge-patch+json`

For details, see the [PATCH documentation](/docs/apis/#the-patch-http-method).

Using a media type of `application/json` merges the provided request parameters into the existing object. As a result, all parameters are optional with `PATCH`: only provide the values you want to change. To remove a value, provide a `null` value. Patching an `Array` appends all values in the new list to the old list.

#### Request Parameters[#](#request-parameters-2)

`messageTemplateId`UUIDrequired

The Id of the Message Template to update.

#### Request Body[#](#request-body)

`messageTemplate.data`Objectoptional

An object that can hold any information about the Message Template that should be persisted.

`messageTemplate.defaultTemplate`\[String (FreeMarker Enabled)\]required

The default Message Template.

`messageTemplate.localizedTemplates`\[Map<Locale,String (FreeMarker Enabled)>\]optional

The Message Template used when sending messages to users who speak other languages. This overrides the default Message Template based on the user's list of preferred languages.

`messageTemplate.name`Stringrequired

A descriptive name for the Message Template (i.e. "Two-Factor Code Message")

`messageTemplate.type`Stringrequired

The type of the template. This must have the value `SMS` or `Voice`.

*Example Request JSON*

```
{
  "messageTemplate": {
    "data": {
      "updatedBy": "richard@fusionauth.io"
    },
    "defaultTemplate": "Here's your Two Factor Code: ${code}",
    "localizedTemplates": {
      "de": "Hier ist Ihr Zwei-Faktoren-Code: ${code}",
      "es": "Este es su código de dos factores: ${code}"
    },
    "name": "Default Two Factor Request",
    "type": "SMS"
  }
}
```

### Response[#](#response-2)

The response for this API contains the new information for the Message Template that was updated.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. The response will contain a JSON body. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](/docs/apis/errors) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](/docs/apis/authentication). |
| 404 | The object you are trying to update doesn't exist. The response will be empty. |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |

#### Response Body[#](#response-body)

`messageTemplate.data`Object

An object that can hold any information about the Message Template that should be persisted.

`messageTemplate.defaultTemplate`\[String (FreeMarker Enabled)\]

The default Message Template.

`messageTemplate.id`UUID

The unique identifier for this Message Template.

`messageTemplate.insertInstant`Long

The [instant](/docs/reference/data-types#instants) that the Application was added to the FusionAuth database.

`messageTemplate.lastUpdateInstant`Long

The [instant](/docs/reference/data-types#instants) that the Application was last updated in the FusionAuth database.

`messageTemplate.localizedTemplates`Map<Locale,String (FreeMarker Enabled)>

The Message Template used when sending messages to users who speak other languages. This overrides the default Message Template based on the user's list of preferred languages.

`messageTemplate.name`String

A descriptive name for the message template.

`messageTemplate.type`String

The type of the template. This will have the value `SMS` or `Voice`.

*Example Response JSON for a Single Message Template*

```
{
  "messageTemplate": {
    "data": {
      "updatedBy": "richard@fusionauth.io"
    },
    "id": "da6edb51-3d1b-40cf-b791-43b657536621",
    "insertInstant": 1619822235060,
    "lastUpdateInstant": 1619822235060,
    "defaultTemplate": "Here's your Two Factor Code: ${code}",
    "localizedTemplates": {
      "de": "Hier ist Ihr Zwei-Faktoren-Code: ${code}",
      "es": "Este es su código de dos factores: ${code}"
    },
    "name": "Default Two Factor Request",
    "type": "SMS"
  }
}
```

## Delete a Message Template[#](#delete-a-message-template)

This API is used to delete a Message Template. You must specify the Id of the Message Template on the URI.

### Request[#](#request-3)

Delete a Message Template By Id

DELETE/api/message/template/{messageTemplateId}

OpenAPI Spec

#### Request Parameters[#](#request-parameters-3)

`messageTemplateId`UUIDrequired

The Id of the Message Template to delete.

### Response[#](#response-3)

This API does not return a JSON response body.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](/docs/apis/errors) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](/docs/apis/authentication). |
| 404 | The object you requested doesn't exist. The response will be empty. |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |

## Preview a Message Template[#](#preview-a-message-template)

This API is used to preview a Message Template. You pass all of the information for the Message Template in the request and a rendered version of the Message is sent back to you in the response. See [previewing message templates](/docs/customize/email-and-messages/message-templates-replacement-variables#previewing-message-templates) for the sample values that are used with the request.

The Message Template in the request does not need to be completely filled out. You can send in a partial Message Template and the response will contain only what you provided.

### Request[#](#request-4)

Preview a Message Template

POST/api/message/template/preview

OpenAPI Spec

#### Request Body[#](#request-body)

`locale`Localeoptional

The locale to use when rendering the Message Template. If this is null or omitted, the defaults will be used and the localized versions will be ignored.

`messageTemplate.defaultTemplate`required

The default Message Template to preview.

`messageTemplate.localizedTemplates`optional

The Message Template used when sending messages to users who speak other languages. This overrides the default Message Template based on the **locale** string passed.

`messageTemplate.type`Stringrequired

The type of the template. This must be the value `SMS`.

*Example Preview Request JSON*

```
{
  "messageTemplate": {
    "defaultTemplate": "Your code is: ${code}",
    "localizedTemplates": {
      "de": "Hier ist Ihr Zwei-Faktoren-Code: ${code}"
    },
    "type": "SMS"
  },
  "locale": "en"
}
```

### Response[#](#response-4)

The response for this API contains the rendered Message and also an Errors that contains any rendering issues FusionAuth found. The template might have syntax or logic errors and FusionAuth will put these errors into the response.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. The response will contain a JSON body. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](/docs/apis/errors) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](/docs/apis/authentication). |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |

#### Response Body[#](#response-body)

`previewMessage`Available since 1.65.0

The rendered text of the message.

`message.textMessage`String

Deprecated since 1.65.0

Use `previewMessage` instead.

The SMS message text. Present when previewing an SMS message template.

`message.type`String

Deprecated since 1.65.0

The type of the message. Present when previewing an SMS message template. Value will always be `SMS`.

`errors`

An [Errors](/docs/apis/errors) object that contains any errors in the Message Template.

*Example Successful Response JSON*

```
{
  "errors": {},
  "previewMessage": "Your code is: 123456",
  "message": {
    "textMessage": "Your code is: 123456",
    "type": "SMS"
  }
}
```

*Example Errors Response JSON*

```
{
  "errors": {
    "fieldErrors": {
      "messageTemplate.defaultTemplate": [
        {
          "code": "[invalidTemplate]messageTemplate.defaultTemplate",
          "message": "Freemarker processing error: [Syntax error in nameless template in line 1, column 14:\nUnexpected end of file reached. You have an unclosed \"{\".]"
        }
      ]
    }
  },
  "message": {
    "type": "SMS"
  }
}
```