Skip to main content

​
Overview

The bulk SMS endpoint allows you to send the same message to multiple recipients in a single API call. Each message is tracked individually with its own message ID.

​
Send Bulk Messages

Use the /messages/bulk endpoint to send SMS to multiple recipients. 
curl -X POST https://api-message.nativehub.live/api/v1/messages/bulk \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      "+8801712345678",
      "+8801798765432",
      "+8801611122233"
    ],
    "from": "BRAND",
    "body": "Hello! This is a bulk message from NativeMessage."
  }'
Response: 
{
  "batch_id": "batch_9x8y7z6w5v4u",
  "queued": 3,
  "failed": 0,
  "rejected": 0,
  "messages": [
    {
      "id": "msg_1a2b3c4d5e6f",
      "to": "+8801712345678",
      "status": "queued",
      "part_count": 1
    },
    {
      "id": "msg_2b3c4d5e6f7g",
      "to": "+8801798765432",
      "status": "queued",
      "part_count": 1
    },
    {
      "id": "msg_3c4d5e6f7g8h",
      "to": "+8801611122233",
      "status": "queued",
      "part_count": 1
    }
  ]
}

​
Understanding Batch ID

The batch_id is a unique identifier for your bulk send operation. Use it to:
  • Track all messages from a single bulk request
  • Filter delivery reports by batch
  • Monitor campaign performance

​
Track Bulk Delivery

You can track individual messages using their message IDs or query all messages from a batch. 
curl -X GET "https://api-message.nativehub.live/api/v1/messages?batch_id=batch_9x8y7z6w5v4u" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Handling Failures

Some messages may fail due to invalid phone numbers or other issues. The response includes details for each failed message. 
{
  "batch_id": "batch_9x8y7z6w5v4u",
  "queued": 2,
  "failed": 1,
  "rejected": 0,
  "messages": [
    {
      "id": "msg_1a2b3c4d5e6f",
      "to": "+8801712345678",
      "status": "queued",
      "part_count": 1
    },
    {
      "id": "msg_2b3c4d5e6f7g",
      "to": "+8801798765432",
      "status": "queued",
      "part_count": 1
    },
    {
      "to": "+880INVALID",
      "status": "failed",
      "error": "Invalid phone number format"
    }
  ]
}
Always validate phone numbers before sending to reduce failure rates and optimize your messaging costs.

​
Best Practices

  • Keep batches under 10,000 recipients per request
  • For larger campaigns, split into multiple batches
  • Process batches sequentially to avoid rate limits
  • Check the failed and rejected counts in the response
  • Log message IDs for successful sends
  • Retry failed messages with corrected data
  • Don’t retry messages with invalid phone numbers
  • Send during off-peak hours for better delivery rates
  • Use webhooks instead of polling for status updates
  • Store batch_id for reporting and analytics
  • Monitor delivery rates per batch to identify issues
  • Default: 100 requests per minute
  • Bulk endpoint: 50 requests per minute
  • Contact support for higher limits on enterprise plans

​
Next Steps

Receive Delivery Reports

Set up webhooks to track message delivery in real-time

API Reference

Explore all bulk messaging parameters and options