Send an SMS Message

Learn how to customize your message sends with the MTA API

SMS differences from MMS

SMS stands for Short Message Service, used for sending short text messages (under 160 characters) between mobile devices. SMS messages do not allow pictures, videos, or multimedia attachments. MMS was created for these types of messages, which stands for Multimedia Messaging Service. MMS message sends have a higher credit cost per send.

SMS Messaging vs. MMS Messaging

A message with an attachment will be sent as MMS by default (messages without an attachment will be sent as SMS). Messages without an attachment can be sent as MMS if isMMS is set to true.

Credit Costs

• 1 credit cost per SMS message (160 character limit, no attachment)

• 3 credit cost per MMS message (1550 character limit, plus 500KB image attachment)

Schedule Message Sends

You can indicate the exact time a message will be sent (in UTC) with the scheduledDate request field. This field uses ISO8601 format, so it is structured: year, month, day, hour, minutes, seconds, and milliseconds.

For example, "20250306T193000-0000" would represent March 6, 2025, 7:30:00 PM UTC.

Repeat scheduled message sends

Scheduled messages can be set to repeat on a custom schedule by using the repeat request field. In this field, each day of the week is represented by a boolean value, which when true indicates the days the message send request will be repeated.

The type field is a string with the value either week or month, which indicates if the message sends should be repeated by the day of month or the day of week.

The frequency is a number between -1 and 5 each indicating a specific frequency of repeats:

CUSTOM = -1,
NEVER = 0,      
DAILY = 1,      
WEEKLY = 2,      
BIWEEKLY = 3,      
MONTHLY = 4,      
ANNUALLY = 5 

Example repeat schedule

If a message is scheduled on Saturday March 1, 2025 and is repeated by day of month, then the next send would be Tuesday April 1, 2025. But if it is repeated by day of week, then the next message would be sent on the first Saturday in April, so Saturday April 5, 2025.

Example repeat field:

 "repeat": {
      "monday": false,
      "tuesday": false,
      "wednesday": false,
      "thursday": false,
      "friday": false,
      "saturday": true,
      "sunday": false,
      "type": "month",
      "frequency": 2,
    }

Properties field for custom variables in messages

With the properties field you can include Liquid Templates variables in your messages. This allows custom messages to each subscriber but only one call to the API. This is useful to include a subscriber's first name or a custom link to a message.

The properties field is a map between the individual subscribers you're sending your message to, and the values of the variables in your message. These variables only exist in the context of a single send, and each property must be explicitly enumerated in the properties array if a corresponding property is used in the message. For predefined subscriber fields that persist beyond a single send, subscriber attributes can be used.

Note that Properties are not the same as Subscriber Attributes, a separately defined system for tracking fields stored on a subscriber record.

• Custom Subscriber Attributes - are defined fields for a subscriber that can be added and edited through the API, platform, Workflow Builder and more. Subscriber attributes are enclosed in single square brackets: [first name]
• Properties - only exist in the context of a single send, these are Liquid Template variables enclosed in double curly braces: {{firstName}}

How to include properties in a /send message request

1

Include your variable(s) in the message field, wrapped between {{ and }} .

"message": "Hello {{firstName}}! Visit {{link}} to reveal your discount!"

2

Define the values of your variable(s) for each subscriber that will receive the message in the properties field.

"properties": {
        "": {
            "firstName": "John",
            "link": "https://example.com/20percent"
        },
        "": {
            "firstName": "Jane",
            "link": "https://example.com/10percent"
        }
    }

3

Create your request to the /send endpoint.

curl --location 'https://api.mobile-text-alerts.com/v3/send' \
--header 'Authorization: Bearer 89fa747a-e01b-5940-99c2-4e96fa996258' \
--data 
'{
    "subscribers": ["3175551111", "3175552222"],
    "message": "Hello {{firstName}}! Visit {{link}} to reveal your discount!",
    "properties": {
        "3175551111": {
            "firstName": "John",
            "link": "https://example.com/20percent"
        },
        "3175552222": {
            "firstName": "Jane",
            "link": "https://example.com/10percent"
        }
    }
}'

Message Templates

Message Templates allows you to save pre-set messages. See the Message Templates tutorial to learn how to use templates with the MTA API.

Send Message API Endpoint

POST /send

See below for the API reference for the /send endpoint.

For steps on how to create an example request to this endpoint see Send a message with the Mobile Text Alerts API.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <APIKey>

Request Fields

Name	Type	Description
message	string	The content of the message being sent.
image	string	The URL of an attachment for a message. By default, messages with attachments (image) will be sent as an MMS.
rehost	boolean	Specifies if the attached image should be rehosted by MTA before being sent.
templateId	number	Unique id of the template corresponding to the controlled template to be used as the message body.
linkId	number	If message contains a templateId and the template includes a link, linkId is required to identify the link.
subscriberIds	number[]	List of subscriber ids to send the message to.
subscribers	number[] or string[]	A list of phone numbers and/or emails to send the message to. Phone numbers can be type number or string.
allSubscribers	boolean	Default value is false. If true, send the message to all subscribers.
groups	number[]	List of group ids to send the message to.
threadId	number	Unique id of the thread to send the message to.
isMMS	boolean	Default value: false for message with no attachment true for messages with attachment Indicates if message will be send as an MMS.
header	string	A header is a message that is included before the message body. A newline will be added between the header and message body.
footer	string	A footer is a message to include at the end of the message body. A space will be added between the message body and footer.
longcodeId	number	Unique id corresponding to the dedicated number to send the message from.
senderName	string	If your account is enabled for iMessage sending, this field is used to specify the desired sender name.
externalId	number	An id to assign to message in the metadata of your message, this externalID is included in webhook notifications.
properties	{ [key: string]: string }	Properties are used to populate the liquid template variables in your message.
scheduledDate	string	The date and time a message is scheduled to send. Must be in ISO 8601 format (eg. "20230302T173000-0500").
repeat	(custom)	repeat indicates the how a scheduled message should go out repeatedly. Default: If a value for repeat is not provided, the scheduled message will not repeat.
tags	(custom)	Tags is a map of custom data to be included with your webhook notifications.

Response

200

{
  "data": {
    "messageId": "uuid",
    "totalSent": 1,
    "totalFailedInternationalRecipients": 0
  },
  "message": "Message Sent to 1 Recipient."
}

400

{
  "httpCode": 400,
  "message": "text",
  "timestamp": "2025-03-03T14:27:08.966Z",
  "type": "bad_request_error",
  "name": "MTABadRequestError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

401

{
  "httpCode": 401,
  "message": "text",
  "timestamp": "2025-03-04T19:24:00.365Z",
  "type": "unauthorized_error",
  "name": "MTAUnauthorizedError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

403

{
  "httpCode": 403,
  "message": "text",
  "timestamp": "2025-03-04T19:24:00.365Z",
  "type": "forbidden_error",
  "name": "MTAForbiddenError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "reason": null
}

420

{
  "httpCode": 429,
  "message": "text",
  "timestamp": "2025-03-04T19:24:00.365Z",
  "type": "rate_limit_error",
  "name": "MTARateLimitError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

500

{
  "httpCode": 500,
  "message": "text",
  "timestamp": "2025-03-04T19:24:00.365Z",
  "type": "internal_server_error",
  "name": "MTAInternalServerError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}