SMS Blast API

A high-performance RESTful interface for sending SMS messages at scale and tracking their delivery in real time. Send a single message or a million — the API behaves the same way.

Base URL

All API requests are made to the following base URL. Replace [BASE_URL] with your assigned gateway endpoint.

Authentication

Every request must include the following HTTP headers. Missing or invalid credentials will result in a 401 or 403 response.

Send SMS Blast

Submit one or more SMS messages to be dispatched immediately. Each message in the array is processed independently.

{
  "messages": [
    {
      "message_reference": "string",
      "destination":       "string",
      "sender":            "string",
      "content":           "string",
      "coding":            "string"
    }
  ]
}

curl -X 'POST' \
  '[BASE_URL]/api/sms/blast' \
  -H 'accept: */*' \
  -H 'profile_id: 1' \
  -H 'client_id: 1234' \
  -H 'client_secret: 1234' \
  -H 'Content-Type: application/json' \
  -d '{
  "messages": [
    {
      "message_reference": "23456789031",
      "destination":       "255600000000",
      "sender":            "NOTIVERSE",
      "content":           "Hello! Your OTP is 483920.",
      "coding":            "GSM"
    }
  ]
}'

{
  "success": true,
  "message": "Your request was submitted successfully",
  "data":    "Submission accepted: 1 message queued for termination."
}

{
  "success": false,
  "message": "We failed to process your request",
  "data":    "Api credential is disabled"
}

Poll Message Status

Query the current delivery state of any submitted message using its unique reference ID.

curl -X 'GET' \
  '[BASE_URL]/api/sms/blast/poll/23456789031' \
  -H 'accept: */*' \
  -H 'profile_id: 1' \
  -H 'client_id: 1234' \
  -H 'client_secret: 1234'

{
  "success": true,
  "message": "Message found",
  "data": {
    "reference":         "23456789031",
    "status":            "Delivered",
    "status_description":"Success",
    "submitted_at":      "2025-12-01T16:25:24.89176",
    "sent_at":           null,
    "final_status_at":   "2025-12-01T16:25:32.672695"
  }
}

Callbacks

Enable callbacks to receive delivery status updates pushed to your webhook URL automatically — no polling required.

Your registered endpoint will receive a POST request with the following JSON array:

[
  {
    "reference":          "23456789031",
    "status":             "Delivered",
    "status_description": "Success",
    "submitted_at":       "2025-12-01T16:25:24.89176",
    "sent_at":            "2025-12-01T16:25:24.89176",
    "final_status_at":    "2025-12-01T16:25:32.672695"
  }
]

Error Handling

Always check the success field before processing a response. When false, the data field contains a human-readable description of the failure.

Best Practices

Follow these recommendations to maximize delivery rates and build a reliable integration.

• ✓
  Unique References: Always use unique message_reference values per message to avoid conflicts and enable accurate tracking.
• ✓
  E.164 Phone Format: Format all destination numbers as countrycode + number with no spaces or symbols (e.g. 255600000000).
• ✓
  Check the success field: Never assume success based on HTTP status alone — always inspect "success": true/false in the JSON response.
• ✓
  Don't poll immediately: Wait at least a few seconds after submission before polling status — messages take time to reach the carrier.
• ✓
  Use callbacks in production: Webhooks are more efficient than polling for high-volume environments — register a callback URL with your account manager.
• ✓
  Batch wisely: You can include multiple messages in a single blast request. Batch them for efficiency without sacrificing individual tracking via message_reference.

Rate Limits

Rate limits are configured per account based on your agreed volume tier. There is no hard global cap — your limit scales with your plan.