Bridge API DocsBridge API Docs
Bridge API Docs
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/bulk

Request Headers

Authorization: Basic <base64_encoded_credentials>
Content-Type: application/json

Request Body

{
  "service_id": 1,
  "recipients": [
    "233XXXXXXXXX",
    "233XXXXXXXXY",
    "233XXXXXXXXZ"
  ],
  "msg_body": "Your payment was received. Thank you.",
  "sender_id": "MMDA"
}

Parameters

ParameterTypeRequiredDescription
service_idintegerYesYour TheBridge service identifier
recipientsarray of stringsYesRecipient mobile numbers (Ghana MSISDN format); maximum 1,000 per request
msg_bodystringYesSMS message text (shared by all recipients)
sender_idstringYesSender 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"
  }
}
FieldDescription
batch_idBatch reference; use to filter send history
total_recipientsNumber of recipients accepted
page_countPages per message
units_per_recipientUnits charged per recipient
total_units_chargedTotal units deducted (page_count × total_recipients)
sms_balanceRemaining SMS balance after upfront deduction
status / status_codeInitial batch status is QUEUED / Q
encodingGSM or UNICODE

Error response

{
  "response_code": "<ERROR_CODE>",
  "response_message": "<ERROR_MESSAGE>"
}
CodeMessage
216Missing SMS Sender ID in request
237You don't have sufficient balance to complete this request
371SMS request could not be processed
389Missing or invalid recipients in request
390Too 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"
}
ScenarioEntry in recipientsHistory status
Delivered0244000001 (last digit 0–8)SENT
Failed + refund0244000009 (last digit 9)REFUNDED
Not allowed0541840988Request rejected with S002

Notes