Create Free API Account
Page cover

Message Templates

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

Pre-set message templates allow you to create a message once and then have it on hand to send 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 in a message by sending a POST request to the /send endpoint. All requests to this endpoint must contain both recipient and content information. When using a message template, the templateId will be 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 - Flag to indicate send message to all subscribers if true. When allSubscribers is set to true, no other recipient fields should be specified. 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 - Messages can be saved as pre-set message templates for reuse with saved controlled templates on your account assigned a templateId.

  • Other fields:

    • linkId: number - if a message contains a linkId then this field is required. Links can be created with the /shortlinks endpoint.

Send a message template with the API

1

Indicate the recipients(s)

You can send a message to a phone number as a test. Here you would set the subscribers field to the recipient phone number.

"subscribers": [1112223333]
2

Indicate the template to be sent

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

"templateId": 101
3

Form API request

Create the API request to the /send endpoint. Remember to include Authorization header.

curl --location 'https://api.mobile-text-alerts.com/v3/send' \
--header 'Authorization: Bearer 89fa747a-e01b-5940-99c2-4e96fa996258' \
--data '{"subscribers": [1112223333],
        "templateId": 101
        }'
4

Receive response

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

{
  "data": {
    "messageId": "uuid",
    "totalSent": 1,
    "totalFailedInternationalRecipients": 0
  },
Send Message POST /send

Send Message from API

post
Authorizations
Body
groupsnumber[]Optional
subscriberIdsnumber[]Optional
allSubscribersbooleanOptional
excludedGroupIdsnumber[]Optional
threadIdnumberOptional
messagestringRequired
imagestringOptional
rehostbooleanOptional
externalIdstringOptional
scheduledDatestringOptional
headerstringOptional
footerstringOptional
isMMSbooleanOptional
repeatall ofOptional
and
linkClickDaysnumberOptional
templateIdnumberOptional
linkIdnumberOptional
longcodeIdnumberOptional
eventIdstringOptional
skipHeaderFooterbooleanOptional
addPlaceholderbooleanOptional
sourcestring · enumOptionalPossible values:
userSignaturestringOptional
poolIdstringOptional
userIdnumberOptional
senderNamestringOptional
customRepeatFrequencyTypenumber | nullableOptional
customRepeatFrequencynumber | nullableOptional
customRepeatDaysall ofOptional
and
undefined · enumOptional

Used when a reference can be null

Possible values:
customEndMessageTypenumber | nullableOptional
customEndMessageDatestring | nullableOptional
customEndMessageOccurrencesnumber | nullableOptional
Responses
200
Success
application/json
Responseall of
post
POST /v3/send HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 1032

{
  "groups": [
    1
  ],
  "subscribers": [
    1
  ],
  "subscriberIds": [
    1
  ],
  "allSubscribers": true,
  "excludedGroupIds": [
    1
  ],
  "threadId": 1,
  "message": "text",
  "image": "text",
  "rehost": true,
  "externalId": "text",
  "scheduledDate": "text",
  "header": "text",
  "footer": "text",
  "properties": {
    "ANY_ADDITIONAL_PROPERTY": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  },
  "isMMS": true,
  "repeat": {
    "monday": true,
    "tuesday": true,
    "wednesday": true,
    "thursday": true,
    "friday": true,
    "saturday": true,
    "sunday": true,
    "type": "week",
    "frequency": -1,
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "linkClickDays": 1,
  "templateId": 1,
  "linkId": 1,
  "longcodeId": 1,
  "eventId": "text",
  "skipHeaderFooter": true,
  "addPlaceholder": true,
  "source": "control-panel",
  "userSignature": "text",
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "poolId": "text",
  "userId": 1,
  "senderName": "text",
  "customRepeatFrequencyType": 1,
  "customRepeatFrequency": 1,
  "customRepeatDays": {
    "monday": true,
    "tuesday": true,
    "wednesday": true,
    "thursday": true,
    "friday": true,
    "saturday": true,
    "sunday": true
  },
  "customEndMessageType": 1,
  "customEndMessageDate": "text",
  "customEndMessageOccurrences": 1
}
{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "messageId": "text",
    "totalSent": 1,
    "totalFailedInternationalRecipients": 1,
    "outboundIds": [
      1
    ]
  }
}

Using Shortlinks with Controlled Templates

When sending or scheduling a message, the /send endpoint will compose the message body using the provided templateId for a controlled template and, if required by the template, a provided linkId. Links can be created with the /shortlinks endpoint.

Create Short Link POST /shortlinks

Create Link

post
Authorizations
Body
longUrlstringRequired
trackingEnabledbooleanOptional
isMMSbooleanOptional
ageCheckbooleanOptional
tagsstring[]Optional
isWebinarbooleanOptional
Responses
200
Success
application/json
Responseall of
post
POST /v3/links/shortlinks HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 103

{
  "longUrl": "text",
  "trackingEnabled": true,
  "isMMS": true,
  "ageCheck": true,
  "tags": [
    "text"
  ],
  "isWebinar": true
}
{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "id": 1,
    "created": "2025-07-13T03:55:50.796Z",
    "longUrl": "text",
    "shortUrl": "text",
    "finalUrl": "text",
    "trackingEnabled": true,
    "isMms": true,
    "clicks": 1,
    "tags": [
      {
        "id": 1,
        "tag": "text"
      }
    ]
  }
}

Templates API endpoints

View all templates

You can call GET /templates to see all the available templates on your account:

List Templates GET /templates

List Templates

get
Authorizations
Query parameters
pagenumberOptional
pageSizenumberOptional
sortBystringOptional
sortDirectionstring · enumOptionalPossible values:
querystringOptional
Responses
200
Success
application/json
Responseall of
get
GET /v3/templates HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Accept: */*

{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "rows": [
      {
        "id": 1,
        "name": "text",
        "message": "text",
        "timestamp": "2025-07-13T03:55:50.796Z",
        "attachment": "text",
        "mms": true
      }
    ],
    "page": 1,
    "pageSize": 1,
    "total": 1
  }
}

View a specific template

To see the details on a specific template, you will need the {id} of the template. Then call GET /templates/{id} :

Get Template GET /templates/{id}

Get Template

get
Authorizations
Path parameters
idstringRequired
Query parameters
isMMSstringRequired
Responses
200
Success
application/json
Responseall of
get
GET /v3/templates/{id} HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Accept: */*

{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "id": 1,
    "name": "text",
    "message": "text",
    "timestamp": "2025-07-13T03:55:50.796Z",
    "attachment": "text",
    "mms": true
  }
}

Update a specific template

To make changes to a specific template, you will need the {id} of the template. Then call PATCH /templates/{id} with the body containing the new template data, message is required.

isMMS will default to false and a SMS template will be created unless an attachment is provided. If name is not provided, up to the first 32 characters of the message will be used as the name.

Example request:

curl --location --request PATCH 'https://api.mobile-text-alerts.com/v3/templates/123' \
--data '{
    "name": "Updated Template Name",
    "message": "This is an updated template message",
    "isMMS": true
}'
Update Template PATCH /templates/{id}

Update Template

patch
Authorizations
Path parameters
idstringRequired
Body
namestringOptional
messagestringOptional
attachmentstringOptional
isMMSbooleanOptional
updateAsMMSbooleanOptional
Responses
200
Success
application/json
Responseall of
patch
PATCH /v3/templates/{id} HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 84

{
  "name": "text",
  "message": "text",
  "attachment": "text",
  "isMMS": true,
  "updateAsMMS": true
}
{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "id": 1,
    "name": "text",
    "message": "text",
    "timestamp": "2025-07-13T03:55:50.796Z",
    "attachment": "text",
    "mms": true
  }
}

Delete a Template

To remove a specific template, you will need the {id} of the template, then call DELETE /templates/{id}

Delete Template DELETE /templates/{id}

Delete Template

post
Authorizations
Path parameters
idstringRequired
Body
isMMSbooleanRequired
Responses
200
Success
application/json
post
POST /v3/templates/{id} HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "isMMS": true
}
{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": null
}

Create a new template

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

isMMS will default to false and a SMS template will be created unless an attachment is provided. If name is not provided, up to the first 32 characters of the message will be used as the name.

Example request:

curl --location 'https://api.mobile-text-alerts.com/v3/templates' \
--data '{
    "name": "New Template",
    "message": "This is a template message",
    "isMMS": true
}'
Create Template POST /templates

Create Template

post

Required Fields: message

Defaults:
isMMS will default to false and a regular sms template will be created unless an attachment is provided. If name is not provided, up to the first 32 characters of the message will be used as the name.

undefined

Authorizations
Body
namestringOptional
messagestringRequired
attachmentstringOptional
isMMSbooleanOptional
Responses
200
Success
application/json
Responseall of
post
POST /v3/templates HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "name": "text",
  "message": "text",
  "attachment": "text",
  "isMMS": true
}
{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "id": 1,
    "name": "text",
    "message": "text",
    "timestamp": "2025-07-13T03:55:50.796Z",
    "attachment": "text",
    "mms": true
  }
}

Template-Only Sending

If your account is configured for template-only message sending, please use the Controlled Template endpoints below to view available templates:

List Controlled Templates GET /controlled-templates

List Controlled Templates

get
Authorizations
Responses
200
Success
application/json
Responseall of
get
GET /v3/controlled-templates HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Accept: */*

{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "rows": [
      {
        "id": 1,
        "accountId": 1,
        "name": "text",
        "message": "text",
        "requiresLink": true,
        "type": "dispensary",
        "isMMS": true,
        "url": "text",
        "createdAt": "2025-07-13T03:55:50.796Z",
        "updatedAt": "2025-07-13T03:55:50.796Z",
        "assignedChildAccounts": [
          {
            "id": 1,
            "accountName": "text"
          }
        ]
      }
    ],
    "page": 1,
    "pageSize": 1,
    "total": 1
  }
}

Get Controlled Template Endpoint GET /controlled-templates/{controlledTemplateId}

Get Controlled Template

get
Authorizations
Path parameters
controlledTemplateIdstringRequired
Responses
200
Success
application/json
Responseall of
get
GET /v3/controlled-templates/{controlledTemplateId} HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Accept: */*

{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "id": 1,
    "accountId": 1,
    "name": "text",
    "message": "text",
    "requiresLink": true,
    "type": "dispensary",
    "isMMS": true,
    "url": "text",
    "createdAt": "2025-07-13T03:55:50.796Z",
    "updatedAt": "2025-07-13T03:55:50.796Z",
    "assignedChildAccounts": [
      {
        "id": 1,
        "accountName": "text"
      }
    ]
  }
}

Template Examples

PreviousSMS FallbackNextReceive and Reply to Messages

Last updated

Was this helpful?