Api reference
Send Bulk SMS
Send the same SMS message to multiple recipients in one request
Send Bulk SMS
Send the same message to up to 1,000 recipients in a single request. The API queues the batch and deducts units upfront from your SMS balance.
Endpoint
POST https://api.bridgeagw.com/sms/bulkRequest Headers
Authorization: Basic <base64_encoded_credentials>
Content-Type: application/jsonRequest Body
{
"service_id": 1,
"recipients": [
"233XXXXXXXXX",
"233XXXXXXXXY",
"233XXXXXXXXZ"
],
"msg_body": "Your payment was received. Thank you.",
"sender_id": "MMDA"
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
service_id | integer | Yes | Your TheBridge service identifier |
recipients | array of strings | Yes | Recipient mobile numbers (Ghana MSISDN format); maximum 1,000 per request |
msg_body | string | Yes | SMS message text (shared by all recipients) |
sender_id | string | Yes | Sender ID displayed to recipients |
Response
Success (response_code: 370)
{
"response_code": "370",
"response_message": "SMS request has been received for processing",
"response_data": {
"batch_id": "BATCH_123",
"total_recipients": 3,
"page_count": 1,
"units_per_recipient": 1,
"total_units_charged": 3,
"sms_balance": 4996,
"status": "QUEUED",
"status_code": "Q",
"encoding": "GSM"
}
}| Field | Description |
|---|---|
batch_id | Batch reference; use to filter send history |
total_recipients | Number of recipients accepted |
page_count | Pages per message |
units_per_recipient | Units charged per recipient |
total_units_charged | Total units deducted (page_count × total_recipients) |
sms_balance | Remaining SMS balance after upfront deduction |
status / status_code | Initial batch status is QUEUED / Q |
encoding | GSM or UNICODE |
Error response
{
"response_code": "<ERROR_CODE>",
"response_message": "<ERROR_MESSAGE>"
}| Code | Message |
|---|---|
216 | Missing SMS Sender ID in request |
237 | You don't have sufficient balance to complete this request |
371 | SMS request could not be processed |
389 | Missing or invalid recipients in request |
390 | Too many recipients in bulk SMS request |
Example Usage
curl -X POST "https://api.bridgeagw.com/sms/bulk" \
-H "Authorization: Basic <your_credentials>" \
-H "Content-Type: application/json" \
-d '{
"service_id": 1,
"recipients": ["233XXXXXXXXX", "233XXXXXXXXY", "233XXXXXXXXZ"],
"msg_body": "Your payment was received. Thank you.",
"sender_id": "MMDA"
}'const response = await fetch('https://api.bridgeagw.com/sms/bulk', {
method: 'POST',
headers: {
'Authorization': 'Basic <your_credentials>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
service_id: 1,
recipients: ["233XXXXXXXXX", "233XXXXXXXXY", "233XXXXXXXXZ"],
msg_body: "Your payment was received. Thank you.",
sender_id: "MMDA"
})
});
const result = await response.json();
console.log(result);import requests
url = "https://api.bridgeagw.com/sms/bulk"
headers = {
"Authorization": "Basic <your_credentials>",
"Content-Type": "application/json"
}
data = {
"service_id": 1,
"recipients": ["233XXXXXXXXX", "233XXXXXXXXY", "233XXXXXXXXZ"],
"msg_body": "Your payment was received. Thank you.",
"sender_id": "MMDA"
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)Sandbox testing
In sandbox mode, bulk SMS uses the same MSISDN allowlist as single SMS. Every entry in recipients must be an allowlisted number. The last-digit outcome rule applies per number — a number ending in 9 will be marked REFUNDED, others will be SENT. See the API Reference sandbox overview for the allowlist.
The batch response returns 370 with status: "ACKNOWLEDGED" immediately. Individual statuses become visible in Get SMS Send History after approximately 800ms.
Example sandbox request:
{
"service_id": 12345,
"recipients": ["0244000001", "0244000002", "0270000003"],
"msg_body": "Hello from sandbox",
"sender_id": "MYAPP"
}| Scenario | Entry in recipients | History status |
|---|---|---|
| Delivered | 0244000001 (last digit 0–8) | SENT |
| Failed + refund | 0244000009 (last digit 9) | REFUNDED |
| Not allowed | 0541840988 | Request rejected with S002 |
Notes
- Maximum 1,000 recipients per request.
- Use
batch_idwith Get SMS Send History to review batch sends. - Ensure sufficient balance via Check SMS Balance before large sends.