📨 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 -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" }
    ]
  }'

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}`);

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}`);

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

$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.

Request Body

Field	Type	Required	Description
`api_key`	`string`	✅	Your Fire SMS API key
`mode`	`string`	✅	Must be `batch`
`batchName`	`string`	✅	A name for this campaign
`messages`	`array`	✅	Array of `{ to, text }` objects
`startTime`	`string`	—	Schedule time: `"2024-03-04 08:00:00"`. Omit to start immediately
`from`	`string`	—	Sender ID (e.g. `"FireSMS"`) — max 11 characters

Example Request

curl -X POST https://firesms.vercel.app/api/v1/bulk-send \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "mode": "batch",
    "batchName": "March Promo",
    "from": "FireSMS",
    "startTime": "2024-03-04 08:00:00",
    "messages": [
      { "to": "27821234567", "text": "Hi John, get 20% off this March!" },
      { "to": "27831234567", "text": "Hi Sarah, get 20% off this March!" }
    ]
  }'

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: 'batch',
    batchName: 'March Promo',
    from: 'FireSMS',
    startTime: '2024-03-04 08:00:00',
    messages: [
      { to: '27821234567', text: 'Hi John, get 20% off this March!' },
      { to: '27831234567', text: 'Hi Sarah, get 20% off this March!' },
    ],
  }),
});

const data = await response.json();
console.log('Batch ID:', data.batchId);
console.log('Scheduled for:', data.scheduled);

interface BatchBulkResponse {
  status: 'success' | 'error';
  mode: 'batch';
  batchId: string;
  total: number;
  scheduled: string;
  cost: 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: 'batch',
    batchName: 'March Promo',
    from: 'FireSMS',
    startTime: '2024-03-04 08:00:00',
    messages: [
      { to: '27821234567', text: 'Hi John, get 20% off this March!' },
      { to: '27831234567', text: 'Hi Sarah, get 20% off this March!' },
    ],
  }),
});

const data: BatchBulkResponse = await response.json();
console.log('Batch ID:', data.batchId);

import requests
import os

response = requests.post(
    'https://firesms.vercel.app/api/v1/bulk-send',
    json={
        'api_key': os.environ['FIRESMS_API_KEY'],
        'mode': 'batch',
        'batchName': 'March Promo',
        'from': 'FireSMS',
        'startTime': '2024-03-04 08:00:00',
        'messages': [
            { 'to': '27821234567', 'text': 'Hi John, get 20% off this March!' },
            { 'to': '27831234567', 'text': 'Hi Sarah, get 20% off this March!' },
        ],
    }
)

data = response.json()
print('Batch ID:', data['batchId'])
print('Scheduled for:', data['scheduled'])

<?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'      => 'batch',
            'batchName' => 'March Promo',
            'from'      => 'FireSMS',
            'startTime' => '2024-03-04 08:00:00',
            'messages'  => [
                ['to' => '27821234567', 'text' => 'Hi John, get 20% off this March!'],
                ['to' => '27831234567', 'text' => 'Hi Sarah, get 20% off this March!'],
            ],
        ]),
    ],
]));

$data = json_decode($response, true);
echo 'Batch ID: ' . $data['batchId'];

Response

{
  "status": "success",
  "mode": "batch",
  "batchId": "batch_xyz789",
  "total": 2,
  "scheduled": "2024-03-04 08:00:00",
  "cost": "0.50"
}

Error Response

{
  "status": "error",
  "error": "Insufficient credits. Need R25.00, have R10.00."
}

HTTP status	Meaning
`400`	Missing or invalid parameters
`401`	Invalid or missing API key
`402`	Insufficient credits
`422`	No provider configured, or provider doesn't support bulk
`500`	Send failed

Bulk Send

On this page