📨 Bulk Send


POST /api/v1/bulk-send

Send messages to multiple recipients in a single request. Two modes are supported:

multi — different message per recipient, results returned immediately (up to ~100 recipients)
batch — large campaigns, processed asynchronously (thousands of recipients)

Mode: multi

Send personalised messages to multiple recipients. Results are returned immediately per recipient.

Request Body

Field	Type	Required	Description
`api_key`	`string`	✅	Your Fire SMS API key
`mode`	`string`	✅	Must be `multi`
`messages`	`array`	✅	Array of `{ to, text }` objects
`messages[].to`	`string`	✅	Recipient number with country code, no `+`
`messages[].text`	`string`	✅	Message body for this recipient

Example Request

cURL


curl -X POST https://firesms.vercel.app/api/v1/bulk-send \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "mode": "multi",
    "messages": [
      { "to": "27821234567", "text": "Hello John" },
      { "to": "27831234567", "text": "Hello Sarah" },
      { "to": "26659001234", "text": "Hello from Lesotho" }
    ]
  }'

JavaScript


const response = await fetch('https://firesms.vercel.app/api/v1/bulk-send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    mode: 'multi',
    messages: [
      { to: '27821234567', text: 'Hello John' },
      { to: '27831234567', text: 'Hello Sarah' },
      { to: '26659001234', text: 'Hello from Lesotho' },
    ],
  }),
});
 
const data = await response.json();
console.log(`Sent ${data.sent}/${data.total} — Cost: R${data.cost}`);

TypeScript


interface BulkMessage {
  to: string;
  text: string;
}
 
interface MultiBulkResponse {
  status: 'success' | 'error';
  mode: 'multi';
  total: number;
  sent: number;
  failed: number;
  cost: string;
  results: {
    to: string;
    success: boolean;
    messageId?: string;
    error?: string;
  }[];
}
 
const response = await fetch('https://firesms.vercel.app/api/v1/bulk-send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_key: process.env.FIRESMS_API_KEY!,
    mode: 'multi',
    messages: [
      { to: '27821234567', text: 'Hello John' },
      { to: '27831234567', text: 'Hello Sarah' },
    ] satisfies BulkMessage[],
  }),
});
 
const data: MultiBulkResponse = await response.json();
console.log(`Sent ${data.sent}/${data.total} — Cost: R${data.cost}`);

Python


import requests
import os
 
response = requests.post(
    'https://firesms.vercel.app/api/v1/bulk-send',
    json={
        'api_key': os.environ['FIRESMS_API_KEY'],
        'mode': 'multi',
        'messages': [
            { 'to': '27821234567', 'text': 'Hello John' },
            { 'to': '27831234567', 'text': 'Hello Sarah' },
            { 'to': '26659001234', 'text': 'Hello from Lesotho' },
        ],
    }
)
 
data = response.json()
print(f"Sent {data['sent']}/{data['total']} — Cost: R{data['cost']}")

PHP


<?php
 
$response = file_get_contents('https://firesms.vercel.app/api/v1/bulk-send', false, stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => 'Content-Type: application/json',
        'content' => json_encode([
            'api_key'  => getenv('FIRESMS_API_KEY'),
            'mode'     => 'multi',
            'messages' => [
                ['to' => '27821234567', 'text' => 'Hello John'],
                ['to' => '27831234567', 'text' => 'Hello Sarah'],
            ],
        ]),
    ],
]));
 
$data = json_decode($response, true);
echo "Sent {$data['sent']}/{$data['total']} — Cost: R{$data['cost']}";

Response


{
  "status": "success",
  "mode": "multi",
  "total": 3,
  "sent": 3,
  "failed": 0,
  "cost": "0.75",
  "results": [
    { "to": "27821234567", "success": true, "messageId": "abc123" },
    { "to": "27831234567", "success": true, "messageId": "abc124" },
    { "to": "26659001234", "success": true, "messageId": "abc125" }
  ]
}

Mode: batch

Upload a large list of recipients processed asynchronously. You get back a batchId to reference the campaign.