Send a Message

Learn how create a request to the Mobile Text Alerts API that will send a message.

Messages are sent from your account’s default number. You can add dedicated numbers (10DLC, toll-free, or short code) if you need higher throughput or two-way messaging.

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 to learn how to get a verified number and start sending your own content.

Send a message with the Mobile Text Alerts API

Messages are sent via the API with POST requests to the /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.
- 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 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.

If using a templateId of a template that requires a link, then a linkId is also required.

How to build a sample request to the API

Let's create a simple request to the /send endpoint.

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.

"subscribers": [1112223333]

Create message content

Write the content of the message to be sent.

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

Trial accounts and unverified phone numbers are restricted to only sending templated message content. Click here to learn how to get a verified number and start sending your own content.

Form API request

Create the API request to the /send endpoint. Remember to include Authorization header.

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

In a test_send.js file :

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

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();

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.

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

Receive Response

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

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

See Error Response Codes to learn about possible reasons your request may fail.

Learn more

Send a Message API Reference

Learn how you can customize your message sends.

PreviousGet an API Key NextAdd a Subscriber

Last updated 1 day ago

Was this helpful?

hashtagReady to send your own content?

hashtagSend a message with the Mobile Text Alerts API

hashtagHow to build a sample request to the API

hashtagIndicate the recipient(s)

hashtagCreate message content

hashtagForm API request

hashtagReceive Response

hashtagLearn more

Ready to send your own content?

Send a message with the Mobile Text Alerts API

How to build a sample request to the API

Indicate the recipient(s)

Create message content

Form API request

Receive Response

Learn more