Send an SMS Message
Learn how to customize your message sends with the MTA API
Last updated
Learn how to customize your message sends with the MTA API
Last updated
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 per send.
1 credit cost per SMS message (160 character limit, no attachment)
3 credit cost per MMS message (1550 character limit, plus 500KB image attachment)
For example, "20250306T193000-0000" would represent March 6, 2025, 7:30:00 PM UTC.
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:
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:
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.
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}}
properties in a /send message requestInclude your variable(s) in the message field, wrapped between {{ and }} .
"message": "Hello {{firstName}}! Visit {{link}} to reveal your discount!"
Define the values of your variable(s) for each subscriber that will receive the message in the properties field.
Create your request to the /send endpoint.
POST /send
See below for the API reference for the /send endpoint.
Headers
Content-Type
application/json
Authorization
Request Fields
message
string
The content of the message being sent.
image
string
rehost
boolean
templateId
number
linkId
number
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
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
externalId
number
properties
{ [key: string]: string }
scheduledDate
string
repeat
Default: If a value for repeat is not provided, the scheduled message will not repeat.
tags
(custom)
Response
You can indicate the exact time a message will be sent (in UTC) with the scheduledDate request field. This field uses , so it is structured: year, month, day, hour, minutes, seconds, and milliseconds.
Message Templates allows you to save pre-set messages. See the tutorial to learn how to use templates with the MTA API.
For steps on how to create an example request to this endpoint see .
Bearer
The URL of an for a message. By default, messages with attachments (image) will be sent as an .
Specifies if the by MTA before being sent.
Unique id of the corresponding to the controlled template to be used as the message body.
If message contains a templateId and the includes a link, linkId is required to identify the link.
Indicates if message will be send as an .
If your account is sending, this field is used to specify the desired sender name.
An id to assign to message in the metadata of your message, this externalID is included in notifications.
are used to populate the liquid template variables in your message.
The date and time a
Must be in format (eg. "20230302T173000-0500").
repeat indicates the how a scheduled message should go out.
Tags is a map of custom data to be included with your notifications.
