Skip to main content
POST
/
v1
/
messages
/
bulk
curl -X POST https://api.tracklysms.com/api/v1/messages/bulk \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from_phone_number_id": "pn_abc123def456",
    "messages": [
      {
        "to_msisdn": "+14155551234",
        "body": "Hello John! Check out our latest offer."
      },
      {
        "to_msisdn": "+14155551235",
        "body": "Hello Jane! Check out our latest offer."
      },
      {
        "to_msisdn": "+14155551236",
        "body": "Hello Bob! Check out our latest offer."
      }
    ]
  }'

{
  "queued_count": 3,
  "error_count": 0,
  "errors": [],
  "deprecated": true
}

Documentation Index

Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt

Use this file to discover all available pages before exploring further.

Deprecated: The v1 API is deprecated. All responses include deprecation headers.
Send up to 1,000 SMS messages in a single API request. Each message can have a unique body, allowing for personalization.

​
Request

​
from_phone_number_id
string
required
The ID of your sending list/phone number. All messages will be sent from this number.
​
messages
array
required
Array of message objects to send. Maximum 1,000 per request.Each message object contains:
  • to_msisdn (string, required): Recipient phone number
  • body (string, required): Message body text

​
Response

​
queued_count
integer
Number of messages successfully queued
​
error_count
integer
Number of messages that failed validation
​
errors
array
List of errors for failed messages, each containing:
  • index: Position in the original array
  • to_msisdn: The phone number that failed
  • error: Description of the error
​
deprecated
boolean
API deprecation flag. Always true for v1 endpoints.
curl -X POST https://api.tracklysms.com/api/v1/messages/bulk \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from_phone_number_id": "pn_abc123def456",
    "messages": [
      {
        "to_msisdn": "+14155551234",
        "body": "Hello John! Check out our latest offer."
      },
      {
        "to_msisdn": "+14155551235",
        "body": "Hello Jane! Check out our latest offer."
      },
      {
        "to_msisdn": "+14155551236",
        "body": "Hello Bob! Check out our latest offer."
      }
    ]
  }'

{
  "queued_count": 3,
  "error_count": 0,
  "errors": [],
  "deprecated": true
}

​
Error Codes

CodeHTTPDescription
missing_from400Sending number ID (from_phone_number_id) not provided
missing_messages400messages array not provided or empty
too_many_messages400More than 1,000 messages in one request
list_not_found404Sending list ID doesn’t exist or isn’t active
missing_api_key401No API key in request headers
invalid_api_key401API key is invalid or revoked
Per-message validation errors (missing phone number, missing body, invalid phone format, body over 1,600 characters) are returned in-band inside the errors array — they do not fail the whole batch.

​
Limits

LimitValue
Maximum messages per request1,000
Maximum message body length1,600 characters (10 segments)
For sends larger than 1,000 messages, split your request into multiple batches or use the dashboard’s campaign scheduling feature.

​
Partial Failures

The bulk endpoint uses a partial success model:
  • Valid messages are queued even if some fail
  • The response includes both queued_count and error_count
  • The errors array provides details on each failure
This allows you to:
  1. Process the successful sends
  2. Review and retry failed messages separately

​
Error Handling Example

response = requests.post(url, headers=headers, json=payload)
result = response.json()

if result['error_count'] > 0:
    for error in result['errors']:
        print(f"Failed: {error['to_msisdn']} - {error['error']}")
        # Log for retry or manual review

print(f"Successfully queued: {result['queued_count']} messages")

​
Performance Tips

Batch Appropriately

Use batches of 500-1000 for optimal throughput

Validate First

Pre-validate phone numbers to reduce errors

Handle Errors

Always check the errors array and handle failures

Use Campaigns

For large sends, use dashboard campaigns instead