Send an SMS Message

Learn how to customize your message sends with the Mobile Text Alerts API

SMS differences from MMS

SMS stands for Short Message Service. It is used for sending short text messages (under 160 characters) between mobile devices. SMS messages do not support pictures, videos, or multimedia attachments. MMS was created for these types of messages and 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 ISO 8601 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 template variables in your messages. This lets you personalize each subscriber's message with a single API call. This is useful for a subscriber's first name or a custom link.

The properties field is a map between the subscribers you're sending to and the values of the variables in your message. These variables exist only in the context of a single send. Each property must be explicitly defined in the properties object if it is used in the message. For predefined subscriber fields that persist beyond a single send, use subscriber attributes.

Note that Properties are not the same as Subscriber Attributes. Subscriber attributes are a separate 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": {
        "3175551111": {
            "firstName": "John",
            "link": "https://example.com/20percent"
        },
        "3175552222": {
            "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 lets you save pre-set messages. See the Message Templates tutorial to learn how to use templates with the Mobile Text Alerts 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 Mobile Text Alerts 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 the 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 provided as either 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 messages with no attachment true for messages with an attachment Indicates if the message will be sent 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 the message metadata. This externalId is included in webhook notifications.
properties	{ [key: string]: string }	Properties are used to populate Liquid template variables in your message.
scheduledDate	string	The date and time a message is scheduled to send. Must be in ISO 8601 format (e.g., "20230302T173000-0500").
repeat	(custom)	repeat indicates how a scheduled message should be sent 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

401

403

429

500