# Send a Message

Messages are sent from your account’s default number. You can add dedicated numbers ([10DLC](https://developers.mobile-text-alerts.com/messaging-routes/10dlc), [toll-free](https://developers.mobile-text-alerts.com/messaging-routes/toll-free), or [short code](https://developers.mobile-text-alerts.com/messaging-routes/short-code)) if you need higher throughput or two-way messaging.

{% hint style="info" %}

#### Ready to send your own content?

You may be restricted to sending templated message content if you’re still on a trial account and/or have an unverified phone number. [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 %}

## Send a message with the Mobile Text Alerts API

Messages are sent via the API with `POST` requests to the [<mark style="color:blue;">`/send`</mark>](https://developers.mobile-text-alerts.com/api-reference/send#post-send) endpoint. The request data must contain both **recipient** and **content** information.

**Required Fields:** (Must be one of the following from each)

* **Recipient(s):**
  * `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.&#x20;
    * To ensure your messages are sent to the intended recipients this field must be formatted correctly based on how your subscribers are stored. E.164 formatted strings are recommended. See [phone-number-format-guide](https://developers.mobile-text-alerts.com/tutorials/phone-number-format-guide "mention") to learn more.
  * `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:**
  * `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. This URL needs to be publicly accessible; this ensures Mobile Text Alerts can access it when sending.
  * `templateId: number` - Messages can be saved as pre-set [message templates](https://developers.mobile-text-alerts.com/tutorials/message-sending/message-templates) for reuse with saved controlled templates on your account assigned a `templateId`. To retrieve the templates configured on your account, use the [List Templates endpoint](https://developers.mobile-text-alerts.com/api-reference/templates#get-templates).

{% hint style="warning" %}
If using a `templateId` of a [template](https://developers.mobile-text-alerts.com/tutorials/message-sending/message-templates) that requires a link, then a `linkId` is also required.
{% endhint %}

### How to build a sample request to the API

Let's create a simple request to the [<mark style="color:blue;">`/send`</mark>](https://developers.mobile-text-alerts.com/api-reference/send) endpoint.

{% stepper %}
{% step %}

### Indicate the recipient(s)

You can send a message to a phone number as a test. Set the `subscribers` field to the recipient phone number.

<pre><code>"subscribers": [<a data-footnote-ref href="#user-content-fn-1">1112223333</a>]
</code></pre>

{% endstep %}

{% step %}

### Create message content

Write the content of the `message` to be sent.

{% code overflow="wrap" %}

```
"message": "Use promo code TESTMESSAGE for 5% off when you sign up. STOP to end"
```

{% endcode %}

{% 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 %}
{% endstep %}

{% step %}

### Form API request

Create the API request to the <mark style="color:blue;">`/send`</mark> endpoint. Remember to include [Authorization](https://developers.mobile-text-alerts.com/developer-center-introduction#authentication) header.

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

```bash
curl --location 'https://api.mobile-text-alerts.com/v3/send' \
--header 'Authorization: Bearer <APIKey>' \
--data '{"subscribers": [1112223333],"message": "Use promo code TESTMESSAGE for 5% off when you sign up. STOP to end"}'
```

{% endtab %}

{% tab title="Node.js" %}
In a `test_send.js` file :

Requirements: Node.js `18+` (native `fetch`) and an `MTA_API_KEY` environment variable.

```js
async function sendSMS() {
  const response = await fetch('https://api.mobile-text-alerts.com/v3/send', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MTA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      // --- RECIPIENTS ---
      subscribers: ['+12345678900'], // Array of E.164 phone numbers
      // --- CONTENT (Stackable) ---
      message: 'Use promo code TESTMESSAGE for 5% off when you sign up. STOP to end', // Plain text body
      // image: 'https://example.com/photo.jpg', // Optional: Triggers MMS
      // templateId: 123, // Optional: Uses a pre-saved template
      // --- PRODUCTION CONTROLS ---
      // externalId: 'otp_user_42', // Optional: For tracking in webhooks
    })
  });
  
  const data = await response.json();
  console.log("MTA Response:", data);
}
sendSMS();
```

{% endtab %}

{% tab title="Python" %}
Use this as a standalone script to send a test, in a `test_send.py` file:

Requirements: `pip install requests python-dotenv` and an `MTA_API_KEY` environment variable.

```python
import os
import requests
from dotenv import load_dotenv

load_dotenv()

def send_sms():
    url = "https://api.mobile-text-alerts.com/v3/send"
    
    payload = {
        # --- RECIPIENTS ---
        "subscribers": ["+12345678900"],
        
        # --- CONTENT (Stackable) ---
        "message": "Use promo code TESTMESSAGE for 5% off when you sign up. STOP to end",
        # "image": "https://example.com/photo.jpg",
        # "templateId": 123,
        
        # --- PRODUCTION CONTROLS ---
        # "externalId": "otp_user_42",
    }

    response = requests.post(
        url, 
        headers={"Authorization": f"Bearer {os.getenv('MTA_API_KEY')}"}, 
        json=payload
    )
    
    print("MTA Response:", response.json())

if __name__ == "__main__":
    send_sms()
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Receive Response

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

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

See [error-response-codes](https://developers.mobile-text-alerts.com/api-basics/error-response-codes "mention") to learn about possible reasons your request may fail.
{% endstep %}
{% endstepper %}

## Learn more

[Send a Message API Reference](https://developers.mobile-text-alerts.com/api-reference/send)

Learn how you can [customize your message sends](https://developers.mobile-text-alerts.com/tutorials/message-sending).

[^1]: Recipient's phone number