Broadcast

POST /api/v1/broadcast

Send one message to many numbers in a single request. Provide the message body once and a list of recipient numbers — the same text is delivered to every number.

Need a different message per recipient? Use the Bulk Send endpoint instead.

Request Headers

Header	Required	Description
`Authorization`	Yes	`Bearer YOUR_API_KEY`
`Content-Type`	Yes	Must be `application/json`

Request Body

Field	Type	Required	Description
`to`	`string[]`	Yes	Array of recipient numbers. Bare numbers are auto-normalized to E.164 (e.g. `27821234567` becomes `+27821234567`). Max 500 numbers.
`text`	`string`	Yes	Message body sent to every number. Max 1600 characters.

Example Request

curl -X POST https://next.firesms.co/api/v1/broadcast \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["+27821234567", "+27831234567", "+26659001234"],
    "text": "Your appointment is confirmed for tomorrow at 9am."
  }'

const numbers = ['+27821234567', '+27831234567', '+26659001234'];
const text = 'Your appointment is confirmed for tomorrow at 9am.';

const response = await fetch('https://next.firesms.co/api/v1/broadcast', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.FIRESMS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ to: numbers, text }),
});

const data = await response.json();
console.log(`Sent ${data.sent}/${data.total} — Cost: R${data.cost}`);

interface BroadcastResponse {
  status: 'success' | 'error';
  total: number;
  sent: number;
  failed: number;
  cost: number;
  remaining_credits: number;
  low_credits: boolean;
  results: {
    to: string;
    success: boolean;
    messageId?: string;
    error?: string;
  }[];
}

const numbers = ['+27821234567', '+27831234567', '+26659001234'];
const text = 'Your appointment is confirmed for tomorrow at 9am.';

const response = await fetch('https://next.firesms.co/api/v1/broadcast', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.FIRESMS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ to: numbers, text }),
});

const data: BroadcastResponse = await response.json();
console.log(`Sent ${data.sent}/${data.total} — Cost: R${data.cost}`);

import os
import requests

numbers = ['+27821234567', '+27831234567', '+26659001234']
text = 'Your appointment is confirmed for tomorrow at 9am.'

response = requests.post(
    'https://next.firesms.co/api/v1/broadcast',
    headers={
        'Authorization': f"Bearer {os.environ['FIRESMS_API_KEY']}",
        'Content-Type': 'application/json',
    },
    json={
        'to': numbers,
        'text': text,
    },
)

data = response.json()
print(f"Sent {data['sent']}/{data['total']} — Cost: R{data['cost']}")

Response

{
  "status": "success",
  "total": 3,
  "sent": 3,
  "failed": 0,
  "cost": 0.75,
  "remaining_credits": 1119.25,
  "low_credits": false,
  "results": [
    { "to": "+27821234567", "success": true, "messageId": "pan_abc123" },
    { "to": "+27831234567", "success": true, "messageId": "pan_abc124" },
    { "to": "+26659001234", "success": true, "messageId": "vcl_abc125" }
  ]
}

Field	Type	Description
`status`	string	`"success"` when the request was accepted
`total`	number	Number of recipients in the request
`sent`	number	Number of messages accepted by a provider
`failed`	number	Number of messages that could not be sent
`cost`	number	Total charged for the messages that were sent (dynamic pricing)
`remaining_credits`	number	Your remaining account credits after the broadcast
`low_credits`	boolean	`true` if credits are running low
`results`	array	Per-recipient outcome — `success`, `messageId`, and an `error` string on failure

Errors

Invalid API Key

{ "status": "error", "error": "Invalid or missing Authorization header" }

HTTP Status: 401 Unauthorized

Insufficient Credits

{
  "status": "error",
  "error": "Insufficient credits. Need R0.75 for 3 messages."
}

HTTP Status: 402 Payment Required

Credits are reserved for the entire recipient list up front. If you don't have enough credit for every number, the request fails with 402 and no messages are sent.

Invalid Request

{
  "status": "error",
  "error": "Invalid request",
  "issues": [
    { "path": ["to"], "message": "At least one recipient is required" }
  ]
}

HTTP Status: 400 Bad Request

Broadcast

On this page