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

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

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