# Send a Message

Messages are sent from your account’s default number. You can add dedicated numbers ([10DLC](/messaging-routes/10dlc.md), [toll-free](/messaging-routes/toll-free.md), or [short code](/messaging-routes/short-code.md)) 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>](/api-reference/send.md#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](/tutorials/phone-number-format-guide.md) 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](/tutorials/message-sending/message-templates.md) 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](/api-reference/templates.md#get-templates).

{% hint style="warning" %}
If using a `templateId` of a [template](/tutorials/message-sending/message-templates.md) 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>](/api-reference/send.md) 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](/tutorials/message-sending/message-templates.md) 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](/developer-center-introduction.md#authentication) header.

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

```bash
curl --location 'https://api.mobile-text-alerts.com/v3/send' \
  --header 'Authorization: Bearer <APIKey>' \
  --header 'Content-Type: application/json' \
  --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](/api-basics/error-response-codes.md) to learn about possible reasons your request may fail.
{% endstep %}
{% endstepper %}

## Learn more

* [Send an SMS Message](/tutorials/message-sending/send-an-sms-message.md)
* [Send](/api-reference/send.md) API Reference
* Learn how you can [customize your message sends](/tutorials/message-sending.md).

[^1]: Recipient's phone number


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.mobile-text-alerts.com/getting-started/send-a-message.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.