> For the complete documentation index, see [llms.txt](https://developers.mobile-text-alerts.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.mobile-text-alerts.com/tutorials/message-sending/message-templates.md).

# Message Templates

Learn how to use Message Templates when calling the Mobile Text Alerts API

Saved message templates allow you to create a message once and then send it at any time. You can create and send message templates in the platform, mobile app, and the API.

## Use a template to send a message with the API

Templates can be sent by making a `POST` request to the [<mark style="color:blue;">`/send`</mark> endpoint](/api-reference/send.md#post-send). All requests to this endpoint must contain both **recipient** and **content** information. When using a message template, the `templateId` is used as the content.

**Required request fields:**

* **Choose recipient(s):** (Must be one of the following.)
  * `subscriberIds: number[]` - List of subscriber IDs of recipients. Messages can be sent to specific subscribers, with each subscriber assigned a unique `subscriberId`.
  * `subscribers: (number | string)[]` - List of recipient phone numbers or email addresses. A new subscriber will be created for new recipients that are not already subscribers on your account.
  * `allSubscribers: boolean` - Indicates whether to send a message to all subscribers. When `allSubscribers` is set to `true`, no other recipient fields should be specified. The default value is `false`.
  * `groups: number[]` - List of group IDs of recipients. Messages can be sent to specific groups, with each group assigned a unique `groupId`.
  * `threadId: number` - Messages can be sent in reply to a thread, with each thread assigned a unique `threadId`.
* **Content:**
  * `templateId: number` - The ID of a saved template on your account.
* **Other fields:**
  * `linkId: number` - Include this field when the template requires a shortlink. Links can be created with the [/links/shortlinks endpoint](/api-reference/links.md#post-links-shortlinks).

### Send a message template with the API

{% stepper %}
{% step %}

### Indicate the recipient(s)

You can send a message to a phone number as a test. Set the `subscribers` field to the recipient's phone number.

```json
"subscribers": [1112223333]
```

{% endstep %}

{% step %}

### Indicate the template to send

Use the `templateId` field to indicate which template will be used.

```json
"templateId": 101
```

{% endstep %}

{% step %}

### Form API request

Create the API request to the `/send` endpoint. Remember to include the [Authorization](/developer-center-introduction.md#authentication) header.

```bash
curl --location 'https://api.mobile-text-alerts.com/v3/send' \
  --header 'Authorization: Bearer <APIKey>' \
  --header 'Content-Type: application/json' \
  --data '{"subscribers": [1112223333],
        "templateId": 101 }'
```

{% endstep %}

{% step %}

### Receive response

The API will return a message about the status of your request.

```json
{
  "data": {
    "messageId": "uuid",
    "totalSent": 1,
    "totalFailedInternationalRecipients": 0
  }
}
```

{% endstep %}
{% endstepper %}

<a href="/api-reference/send.md#post-send" class="button primary medium" data-icon="rectangle-api">POST /send</a>

## Using Shortlinks with Controlled Templates

When sending or scheduling a message, the `/send` endpoint composes the message body using the provided `templateId` for a controlled template. If required, it also uses the provided `linkId`. Links can be created with the `/links/shortlinks` endpoint:

<a href="/api-reference/links.md#post-links-shortlinks" class="button primary medium" data-icon="rectangle-api">Create Link /links/shortlinks</a>

## Include personalization in a template

Mobile Text Alerts supports Liquid templates for message personalization. A template can include custom variables such as `{{firstName}}`, which are replaced using per-recipient properties. This requires a `properties` object that maps each phone number to its corresponding data.

See [Send an SMS Message](/tutorials/message-sending/send-an-sms-message.md#properties-field-for-custom-variables-in-messages) to learn more.

## Templates API endpoints

### View all templates

You can call <mark style="color:green;background-color:green;">GET</mark> `/templates` to see all the available templates on your account:

<a href="/api-reference/templates.md#get-templates" class="button primary medium" data-icon="rectangle-api">List Templates GET /templates</a>

### View a specific template

To see the details of a specific template, you need the template's `{id}`. Then call <mark style="color:green;background-color:green;">GET</mark> `/templates/{id}`:

<a href="/api-reference/templates.md#get-templates-id" class="button primary medium" data-icon="rectangle-api">Get Template GET /templates/{id}</a>

### Update a specific template

To make changes to a specific template, you need the template's `{id}`. Then call [<mark style="color:purple;background-color:purple;">PATCH</mark> `/templates/{id}`](/api-reference/templates.md#patch-templates-id) with a body containing the new template data. The `message` field is required.

**Example request:**

```bash
curl --location --request PATCH 'https://api.mobile-text-alerts.com/v3/templates/123' \
  --header 'Authorization: Bearer <APIKey>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated Template Name",
    "message": "This is an updated template message",
    "isMMS": true
}'
```

<a href="/api-reference/templates.md#patch-templates-id" class="button primary medium" data-icon="rectangle-api">Update Template PATCH /templates/{id}</a>

### Delete a template

To remove a specific template, you need the template's `{id}`. Then call <mark style="color:blue;">POST</mark> `/templates/{id}`.

<a href="/api-reference/templates.md#post-templates-id" class="button primary medium" data-icon="rectangle-api">Delete Template POST /templates/{id}</a>

### Create a new template

When creating a new template, the `message` field is required to hold the content of the message.

**Example request:**

```bash
curl --location 'https://api.mobile-text-alerts.com/v3/templates' \
  --header 'Authorization: Bearer <APIKey>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "New Template",
    "message": "This is a template message",
    "isMMS": true
}'
```

<a href="/api-reference/templates.md#post-templates" class="button primary medium" data-icon="rectangle-api">Create Templates POST /templates</a>

## Template-Only Sending

If your account is configured for template-only message sending, please use the [Controlled Template endpoints](/api-reference/controlled-templates.md) to view available templates:

### Template Examples

* [91 Sample Text Messages to Customers, Message Templates](https://mobile-text-alerts.com/articles/sample-text-messages-to-customers)
* [43 Auto Reply Text Message Examples (+ 3 Tips)](https://mobile-text-alerts.com/articles/auto-reply-text-message-examples)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.mobile-text-alerts.com/tutorials/message-sending/message-templates.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.