Quick Start

Single Recipient

curl -X POST "https://api.airtexts.com/sms/send" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d 
'
{
    "to": "+25884000000",
    "from": "YourApp",
    "message": "Hello! This is a test message from AirTexts."
  }
'

Multiple Recipients (Comma Separated/Semicolon Separated)

curl -X POST "https://api.airtexts.com/sms/send" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d 
'
{
    "to": "+25884000000,+25884000001,+25884000002;25884000002",
    "from": "YourApp",
    "message": "Group message sent to multiple recipients!"
  }
'

Request Parameters

Required Parameters

Parameter	Type	Description	Example
`to`	string	Phone number(s) in international format	`"+258845888195"`
`message`	string	SMS message content (up to 1600 characters)	`"Hello World!"`

Optional Parameters

Parameter	Type	Description	Default	Example
`from`	string	Sender ID or phone number	`"SMS"`	`"YourApp"`
`route`	string	SMS route for delivery	`"auto"`	`"premium"`
`scheduled_time`	string	Schedule message for later (ISO 8601)	`null`	`"2025-08-20T10:00:00Z"`
`reference`	string	Your internal reference ID	`null`	`"order_12345"`
`webhook_url`	string	URL for delivery notifications	`null`	`"https://yourapp.com/webhook"`

Multiple Recipients Format

You can send to multiple recipients using these separators:

Comma (,): "+2588400000,+2588400004;+2588400009"
Mixed format: "+25884000007, +25884000008; +2588400009" (spaces are ignored)

Alternative Parameter Names

to can also be sent as phone, recipient, or recipients
from can also be sent as sender or sender_id
message can also be sent as text or body

Message Types

Standard SMS (160 characters)

{
  "to": "+25884000007",
  "from": "YourApp",
  "message": "Short message within 160 characters limit for single SMS cost."
}

Long SMS (Concatenated)

{
  "to": "+25884000007",
  "from": "YourApp", 
  "message": "This is a longer message that exceeds 160 characters and will be automatically split into multiple SMS parts. Each part will be charged separately but will be displayed as a single message on the recipient's device."
}

Success Response

Single Recipient

{
  "status": "success",
  "message": "SMS sent successfully",
  "data": {
    "message_id": "msg_67890abcdef12345",
    "to": "+25884000007",
    "from": "YourApp",
    "message": "Hello! This is a test message.",
    "parts": 1,
    "cost": 0.05,
    "balance": 45.50,
    "status": "sent",
    "reference": null
  }
}

Multiple Recipients

{
  "status": "success",
  "message": "SMS sent to multiple recipients",
  "data": {
    "total_recipients": 3,
    "successful": 3,
    "failed": 0,
    "total_cost": 0.15,
    "balance": 45.35,
    "messages": [
      {
        "message_id": "msg_67890abcdef12345",
        "to": "+25884000007",
        "status": "sent",
        "cost": 0.05
      },
      {
        "message_id": "msg_67890abcdef12346", 
        "to": "+25884000007",
        "status": "sent",
        "cost": 0.05
      },
      {
        "message_id": "msg_67890abcdef12347",
        "to": "+25884000007", 
        "status": "sent",
        "cost": 0.05
      }
    ]
  }
}

Best Practices

Phone Number Formatting

Always use international format: +[country_code][number]
Remove spaces and special characters: +25884000007
Validate before sending: Check format and country codes

Multiple Recipients

Batch wisely: Don't exceed 1000 recipients per request
Handle failures gracefully: Check individual message status
Use appropriate separators: Comma (,) or semicolon (;)
Monitor costs: Calculate total cost before sending