# Send an SMS Message

## 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](#credit-costs) per send.

<figure><img src="https://879775583-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM0P3gHFFZE4c6PMaPvHm%2Fuploads%2FVxJUEy4mx4rGzltgJZyF%2Fmms_services_vs_sms_infographic_48a300f951.webp?alt=media&#x26;token=c596497e-d2a0-4b1b-8b9c-c24ebcae86e7" alt=""><figcaption><p>SMS Messaging vs. MMS Messaging</p></figcaption></figure>

{% hint style="info" %}
A message **with** an attachment will be sent as MMS by default (messages without an attachment will be [sent as SMS](https://developers.mobile-text-alerts.com/tutorials/message-sending/send-an-sms-message)).  Messages **without** an attachment can be sent as MMS if `isMMS` is set to `true`.
{% endhint %}

### 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)

{% hint style="info" %}
Before sending a message, you can calculate the will cost with the [#post-send-cost](https://developers.mobile-text-alerts.com/api-reference/send#post-send-cost "mention") endpoint. The `messageCredits` field indicates the number of credits to be consumed.
{% endhint %}

## 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](https://www.iso.org/iso-8601-date-and-time-format.html), 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:**

```json
 "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.

{% hint style="warning" %}
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**](https://developers.mobile-text-alerts.com/tutorials/manage-subscribers/assign-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}}`
  {% endhint %}

### How to include `properties` in a `/send` message request

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

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

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

<pre class="language-json"><code class="lang-json">"properties": {
        "<a data-footnote-ref href="#user-content-fn-1">3175551111</a>": {
            "firstName": "John",
            "link": "https://example.com/20percent"
        },
        "<a data-footnote-ref href="#user-content-fn-1">3175552222</a>": {
            "firstName": "Jane",
            "link": "https://example.com/10percent"
        }
    }
</code></pre>

{% endstep %}

{% step %}
Create your request to the <mark style="color:blue;">`/send`</mark> endpoint.

```bash
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"
        }
    }
}'
```

{% endstep %}
{% endstepper %}

## Message Templates

Message Templates lets you save pre-set messages. See the [Message Templates](https://developers.mobile-text-alerts.com/tutorials/message-sending/message-templates) tutorial to learn how to use templates with the Mobile Text Alerts API.

{% hint style="warning" %}
Trial accounts and unverified phone numbers are restricted to only sending [templated message](https://developers.mobile-text-alerts.com/tutorials/message-sending/message-templates) content. [Click here](https://mobile-text-alerts.deskpro.com/kb/articles/phone-number-verification) to learn how to get a verified number and start sending your own content.
{% endhint %}

## Include a header and/or footer

A header or footer text can be useful in messaging for:

* Legal compliance (opt-out text)
* Branding (company name)
* Context (alert type)

You can include a header text in your messages with the `header` request field, this will be included before the message body.  Note that a newline will be added between the header and message body.

You can also include footer text in your messages with the `footer` request field, this is included at the end of the message body. Note that a space will be added between the message body and footer.

## Send Message API Endpoint

<mark style="color:green;">`POST`</mark> <mark style="color:blue;">`/send`</mark>

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](https://developers.mobile-text-alerts.com/getting-started/send-a-message#send-a-message-with-the-mobile-text-alerts-api).

**Headers**

| Name          | Value                                                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Content-Type  | `application/json`                                                                                                          |
| Authorization | `Bearer` [`<APIKey>`](https://developers.mobile-text-alerts.com/getting-started/get-an-api-key#bearer-token-authentication) |

**Request Fields**

<table><thead><tr><th width="194">Name</th><th width="139">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>message</code></td><td><code>string</code></td><td>The content of the message being sent.</td></tr><tr><td><code>image</code></td><td><code>string</code></td><td>The URL of an <a href="../send-an-mms-message#supported-attachment-types">attachment</a> for a message. By default, messages with attachments (<code>image</code>) will be sent as an <a href="send-an-mms-message">MMS</a>.</td></tr><tr><td><code>rehost</code></td><td><code>boolean</code></td><td>Specifies if the <a href="../send-an-mms-message#attachment-hosting-with-rehost-field">attached image should be rehosted</a> by Mobile Text Alerts before being sent.</td></tr><tr><td><code>templateId</code></td><td><code>number</code></td><td>Unique ID of the <a href="#message-templates">template</a> corresponding to the controlled template to be used as the message body.</td></tr><tr><td><code>linkId</code></td><td><code>number</code></td><td>If the message contains a <code>templateId</code> and the <a href="#message-templates">template</a> includes a link, <code>linkId</code> is required to identify the link.</td></tr><tr><td><code>subscriberIds</code></td><td><code>number[]</code></td><td>List of subscriber IDs to send the message to.</td></tr><tr><td><code>subscribers</code></td><td><code>number[]</code> or <code>string[]</code></td><td>A list of phone numbers and/or emails to send the message to. <a href="../phone-number-format-guide">Phone numbers can be provided as either <code>number</code> or <code>string</code>.</a></td></tr><tr><td><code>allSubscribers</code></td><td><code>boolean</code></td><td><p>Default value is <code>false</code>.</p><p>If <code>true</code>, send the message to all subscribers.</p></td></tr><tr><td><code>groups</code></td><td><code>number[]</code></td><td>List of group IDs to send the message to.</td></tr><tr><td><code>threadId</code></td><td><code>number</code></td><td>Unique ID of the thread to send the message to.</td></tr><tr><td><code>isMMS</code></td><td><code>boolean</code></td><td><p>Default value:</p><ul><li><code>false</code> for messages with <strong>no</strong> attachment</li><li><code>true</code> for messages with an attachment</li></ul><p>Indicates if the message will be sent as an <a href="send-an-mms-message">MMS</a>.</p></td></tr><tr><td><code>header</code></td><td><code>string</code></td><td>A <code>header</code> is a message that is included before the message body. A newline will be added between the <code>header</code> and message body.</td></tr><tr><td><code>footer</code></td><td><code>string</code></td><td>A <code>footer</code> is a message to include at the end of the message body. A space will be added between the message body and <code>footer</code>.</td></tr><tr><td><code>longcodeId</code></td><td><code>number</code></td><td>Unique ID corresponding to the dedicated number to send the message from.</td></tr><tr><td><code>senderName</code></td><td><code>string</code></td><td>If your account is <a href="send-an-imessage">enabled for iMessage</a> sending, this field is used to specify the desired sender name.</td></tr><tr><td><code>externalId</code></td><td><code>number</code></td><td>An ID to assign to the message metadata. This <code>externalId</code> is included in <a href="../../../getting-started/setting-up-webhooks#webhooks-overview">webhook</a> notifications.</td></tr><tr><td><code>properties</code></td><td><code>{ [key: string]: string }</code></td><td><a href="#how-to-include-properties-in-a-send-message-request">Properties</a> are used to populate Liquid template variables in your message.</td></tr><tr><td><code>scheduledDate</code></td><td><code>string</code></td><td><p>The date and time a <a href="#schedule-message-sends">message is scheduled to send</a>.</p><p>Must be in <a href="https://www.iso.org/iso-8601-date-and-time-format.html">ISO 8601</a> format (e.g., <code>"20230302T173000-0500"</code>).</p></td></tr><tr><td><code>repeat</code></td><td><a href="#repeat-scheduled-message-sends"><code>(custom)</code></a></td><td><p><code>repeat</code> indicates how a scheduled message should be sent <a href="#repeat-scheduled-message-sends">repeatedly</a>.</p><p>Default: If a value for <code>repeat</code> is not provided, the scheduled message will not repeat.</p></td></tr><tr><td><code>tags</code></td><td><code>(custom)</code></td><td>Tags is a map of custom data to be included with your <a href="../../getting-started/setting-up-webhooks">webhook</a> notifications.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

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

{% endtab %}

{% tab title="400" %}

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

{% endtab %}

{% tab title="401" %}

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

{% endtab %}

{% tab title="403" %}

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

{% endtab %}

{% tab title="429" %}

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

{% endtab %}

{% tab title="500" %}

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

{% endtab %}
{% endtabs %}

[^1]: subscriberId