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.
  - 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 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. This URL needs to be publicly accessible; this ensures Mobile Text Alerts can access it when sending. By default, messages with attachments will be sent as an MMS.
- images:string[] - Use this field for multiple attachments, this is an array of image attachment URLs. Overrides image when present.
- 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>' \
  --header 'Content-Type: application/json' \
  --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 an SMS Message
For messages with attachments such as images or contact cards see Send an MMS Message.
Send API Reference
Learn how you can customize your message sends.

PreviousGet an API Key NextAdd a Subscriber

Last updated 4 minutes ago

Was this helpful?