Bulk SMS

Send the same message to multiple recipients in a single API call.

Endpoint

POST https://api.galatext.com/api/sms/bulk

Headers

Header	Value	Required
Content-Type	application/json	Yes
x-api-key	Your API key	Yes

Request Body

Parameter	Type	Required	Description
recipients	array	Yes	Array of recipient objects (max varies by tier)
message	string	Yes	Message content sent to all recipients
senderId	string	No	Sender ID (default: GALATEX)
reference	string	No	Optional batch reference for reconciliation

Recipient Object

Field	Type	Required	Description
phoneNumber	string	Yes	Phone number in E.164 format
variables	object	No	Template variables for personalized messages

Batch Size Limits

Tier	Max Recipients per Call
Free	100
Starter	1,000
Business	10,000
Enterprise	Custom

Example Request

curl -X POST https://api.galatext.com/api/sms/bulk \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "recipients": [
      { "phoneNumber": "+254712345678" },
      { "phoneNumber": "+254723456789" },
      { "phoneNumber": "+254734567890" }
    ],
    "message": "Thank you for choosing our service! Your account is now active.",
    "senderId": "YOURBRAND"
  }'

Personalized Bulk SMS

Use template variables with in the message to personalize each message:

curl -X POST https://api.galatext.com/api/sms/bulk \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "recipients": [
      {
        "phoneNumber": "+254712345678",
        "variables": { "name": "Alice", "code": "A1B2C3" }
      },
      {
        "phoneNumber": "+254723456789",
        "variables": { "name": "Bob", "code": "D4E5F6" }
      }
    ],
    "message": "Hi {{name}}, your verification code is {{code}}.",
    "senderId": "YOURBRAND"
  }'

JavaScript (fetch)

const response = await fetch('https://api.galatext.com/api/sms/bulk', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.GALATEXT_API_KEY
  },
  body: JSON.stringify({
    recipients: [
      { phoneNumber: '+254712345678' },
      { phoneNumber: '+254723456789' }
    ],
    message: 'Welcome to our platform!',
    senderId: 'YOURBRAND'
  })
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    'https://api.galatext.com/api/sms/bulk',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'recipients': [
            {'phoneNumber': '+254712345678'},
            {'phoneNumber': '+254723456789'}
        ],
        'message': 'Welcome to our platform!',
        'senderId': 'YOURBRAND'
    }
)

data = response.json()
print(data)

Response

Success (202 Accepted)

{
  "success": true,
  "data": {
    "batchId": "batch_xyz789abc012",
    "totalRecipients": 3,
    "totalSegments": 3,
    "totalCredits": 3,
    "creditsRemaining": 1496,
    "messages": [
      {
        "messageId": "msg_abc111",
        "phoneNumber": "+254712345678",
        "status": "PENDING"
      },
      {
        "messageId": "msg_abc112",
        "phoneNumber": "+254723456789",
        "status": "PENDING"
      },
      {
        "messageId": "msg_abc113",
        "phoneNumber": "+254734567890",
        "status": "PENDING"
      }
    ]
  }
}

Field	Description
batchId	Unique identifier for the batch
totalRecipients	Number of recipients in the request
totalCredits	Total credits deducted
messages	Array of individual message statuses

Partial Success

If some recipients fail validation, the API returns a partial success:

{
  "success": true,
  "data": {
    "batchId": "batch_xyz789abc012",
    "totalRecipients": 3,
    "successful": 2,
    "failed": 1,
    "errors": [
      {
        "index": 2,
        "phoneNumber": "+254invalid",
        "error": {
          "code": "INVALID_PHONE_NUMBER",
          "message": "Phone number is not in valid E.164 format"
        }
      }
    ],
    "messages": [
      { "messageId": "msg_abc111", "phoneNumber": "+254712345678", "status": "PENDING" },
      { "messageId": "msg_abc112", "phoneNumber": "+254723456789", "status": "PENDING" }
    ]
  }
}

Error Codes

Status	Error Code	Description
400	BAD_REQUEST	Malformed request body
401	UNAUTHORIZED	Missing or invalid API key
402	INSUFFICIENT_CREDITS	Account balance too low
413	PAYLOAD_TOO_LARGE	Too many recipients for your tier
422	EMPTY_RECIPIENTS	Recipients array is empty

Best Practices

• Batch in chunks — Stay within your tier's limit per request
• Validate phone numbers — Pre-validate E.164 format client-side
• Use variables — Personalize messages for better engagement
• Store batchId — Reference for delivery tracking
• Respect quiet hours — Avoid sending promotional SMS after 9 PM