Send Bulk SMS

Send one approved SMS template to many numbers with a single request, each with its own variables. Up to 1,000 numbers per request.

We check the whole list first, then send in the background. You get a bulk_id straight away and can follow progress with SMS status, or get each result on your server with delivery reports.

Any approved template works here, whatever its type: promotional, transactional, service implicit or service explicit. The type, sender ID and price come from the template.

Note: SMS must be Active on your account and the template must be Approved. See Set up SMS and SMS templates.

Endpoint

POST

https://api.splashifypro.com/api/v1/public/sms/send-bulk

Headers

Header	Value
`Authorization`	`Basic YOUR_API_KEY`
`Content-Type`	`application/json`
`Idempotency-Key`	Optional, and recommended. Your own id for this send, up to 255 characters. It makes a retry safe. See Retry safely

Request body

{
  "dlt_template_id": "1107160000000000002",
  "name": "Order alerts 26 Sep",
  "messages": [
    { "to": "+919876543210", "variables": ["Aarav", "AB-1042"] },
    { "to": "+919876543211", "variables": ["Diya", "AB-1043"] },
    { "to": "+919876543212", "variables": ["Kabir", "AB-1044"] }
  ]
}

Field	Required	Notes
`dlt_template_id`	yes	The 19-digit DLT template ID of an approved SMS template
`name`	optional	A name for this send, only for you, up to 100 characters (longer names are cut). For example `Order alerts 26 Sep`. Without one, the name is the date and time, such as `API send 26 Sep 2026 14:05 UTC`
`messages`	yes	1 to 1,000 rows
`messages[].to`	yes	An Indian mobile number. `+91 98765 43210`, `+919876543210`, `919876543210`, `09876543210` and `9876543210` all work
`messages[].variables`	if the template has any	A list of text values, one for each `{#var#}` in the template, in order. Each can be up to 30 characters and cannot be empty

What we check before sending

Nothing is sent until the whole request passes these checks:

The template can send. It is approved, its sender ID is approved, and your DLT chain is verified.
Every row has the right variables. A row with too many or too few, or with a value that is empty or over 30 characters, is refused with 400 and code: "invalid_variables". The message and row name the first bad row. Nothing is queued.
Every number is an Indian mobile. Numbers that are not are skipped and counted in skipped.invalid.
Duplicates are sent once. The first row with a number is sent. Later rows with the same number count in skipped.duplicate.
Opted-out numbers are skipped. People who asked not to get your messages count in skipped.opted_out and are not charged.
Your wallet covers the estimate. This is checked on the numbers left after opted-out ones are taken out, so your balance only needs to cover the messages that will go. If it does not, the request is refused with 402 and nothing is queued.
Something is left to send. If every row was skipped, the request is refused with 400 and code: "no_recipients".

Every skipped row is listed in skipped_rows, so you can fix your data.

Examples

cURL

curl -X POST https://api.splashifypro.com/api/v1/public/sms/send-bulk \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-alerts-26-sep" \
  -d '{
    "dlt_template_id": "1107160000000000002",
    "name": "Order alerts 26 Sep",
    "messages": [
      { "to": "+919876543210", "variables": ["Aarav", "AB-1042"] },
      { "to": "+919876543211", "variables": ["Diya", "AB-1043"] }
    ]
  }'

Node.js / TypeScript

type Row = { to: string; variables: string[] };

// idempotencyKey: make it once for this list, and send the same one on every retry.
async function sendOrderAlerts(rows: Row[], idempotencyKey: string) {
  const res = await fetch("https://api.splashifypro.com/api/v1/public/sms/send-bulk", {
    method: "POST",
    headers: {
      "Authorization":   `Basic ${process.env.SPLASHIFY_API_KEY!}`,
      "Content-Type":    "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({
      dlt_template_id: "1107160000000000002",
      name:            "Order alerts 26 Sep",
      messages:        rows, // up to 1,000
    }),
  });

  const data = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${data.code ?? ""}: ${data.message ?? ""}`);
  return data.bulk_id; // follow it with GET /api/v1/public/sms/bulk/:bulk_id
}

Python

import os, requests

# idempotency_key: make it once for this list, and send the same one on every retry.
def send_order_alerts(rows: list[dict], idempotency_key: str) -> str:
    r = requests.post(
        "https://api.splashifypro.com/api/v1/public/sms/send-bulk",
        headers={
            "Authorization":   f"Basic {os.environ['SPLASHIFY_API_KEY']}",
            "Content-Type":    "application/json",
            "Idempotency-Key": idempotency_key,
        },
        json={
            "dlt_template_id": "1107160000000000002",
            "name":            "Order alerts 26 Sep",
            "messages":        rows,  # up to 1,000
        },
        timeout=60,
    )
    data = r.json()
    if r.status_code != 200:
        raise RuntimeError(f"{r.status_code} {data.get('code')}: {data.get('message')}")
    return data["bulk_id"]

For more than 1,000 numbers, split the list and send one request per 1,000.

Successful response (`200 OK`)

{
  "success": true,
  "bulk_id": "9d2f4b61-1c7e-4a35-8f90-6b3e2d7c5a18",
  "name": "Order alerts 26 Sep",
  "queued": 2,
  "skipped": { "opted_out": 1, "invalid": 0, "duplicate": 0 },
  "skipped_rows": [
    { "row": 3, "to": "+919876543212", "reason": "opted_out" }
  ],
  "estimated_parts": 2,
  "estimated_cost": 0.32,
  "status": "queued"
}

Field	Notes
`bulk_id`	Your id for this send. Use it with bulk progress
`name`	The name you sent, or the date and time when you sent none
`queued`	How many SMS will be sent
`skipped`	How many rows were left out, by reason: `opted_out`, `invalid` (not an Indian mobile) and `duplicate`
`skipped_rows`	Each row left out. `row` counts from 1 in the order of your `messages`, `to` is the number as you sent it, and `reason` is `opted_out`, `invalid` or `duplicate`. An empty list when nothing was skipped
`estimated_parts`	SMS parts we expect to send in total
`estimated_cost`	What we expect it to cost. Each SMS is charged as it is sent, so the final amount can differ a little
`status`	`queued` when accepted. Sending starts in the background. On a replay, the status the send has now
`replayed`	Only on a replay: `true`, and nothing new was queued

Retry safely

A bulk send can take a while to check. If your request times out or you get a 5xx, you cannot tell whether the list was queued. Send an Idempotency-Key header, and you can simply send the same request again with the same key:

If the first request went through, you get its answer back: the same bulk_id, the send's status as it is now, and "replayed": true. The response also has the header Idempotency-Replayed: true. Nothing is sent or charged again.
If the first request failed, the key is not kept, and the retry is a normal send.
If the first request is still running, you get 409 with code: "idempotency_in_progress". Wait a few seconds and try again with the same key.
The same key with a different body gets 422 with code: "idempotency_key_reused". Use a new key for a new list.

A key is kept for 24 hours. Use one key per list you decide to send, such as order-alerts-26-sep, and reuse it on every retry of that list. See Idempotency.

Errors

Errors look like this. Switch on code, and show message to a person:

{
  "success": false,
  "code": "invalid_variables",
  "message": "Row 2: this template needs 2 variable(s) and 1 were given.",
  "row": 2
}

Status	`code`	Meaning
`400`	`invalid_request`	The body is not valid JSON, `dlt_template_id` is missing, or `messages` is empty
`400`	`too_many_messages`	More than 1,000 rows. Split the list
`400`	`invalid_variables`	A row has the wrong number of `variables`, or a value that is empty or over 30 characters. `row` says which
`400`	`no_recipients`	Every row was skipped. The body also has `skipped` and `skipped_rows`
`400`	`template_not_approved`	The template is not approved yet
`400`	`sender_not_approved`	The template's sender ID is not approved yet
`400`	`dlt_chain_not_verified`	Your DLT chain is not verified yet. See Set up SMS
`402`	`insufficient_balance`	Your wallet cannot cover the estimated cost. Nothing was queued. Add funds and send again
`402`	`sending_paused`	Sending is paused on your account. Nothing was queued. The `message` says what to do
`404`	`sms_not_set_up`	SMS is not set up on your account
`404`	`template_not_found`	No template with that `dlt_template_id` on your account
`409`	`idempotency_in_progress`	A request with this `Idempotency-Key` is still running. Try again shortly with the same key
`422`	`idempotency_key_reused`	This `Idempotency-Key` was used with a different body. Use a new key
`429`	`rate_limited`	More than 10 bulk sends in a minute. Wait for the number of seconds in `Retry-After`
`503`	`unavailable`	SMS sending is not available right now, or the send could not be queued. Nothing was sent. Try again shortly

A 402 also tells you the estimate, and for insufficient_balance your balance. The estimate leaves out the opted-out numbers we found. When your balance cannot cover the list, we stop checking for opt-outs as soon as that is clear, or do not check at all when it cannot cover one message, so the estimate can include numbers that opted out:

{
  "success": false,
  "code": "insufficient_balance",
  "message": "Your wallet balance is too low for this send. Nothing was queued. Add funds and try again.",
  "estimated_parts": 1000,
  "estimated_cost": 160,
  "balance": 42.5
}

The checks every Public API request goes through answer the same way as on Send SMS: 401 for a missing or invalid API key, 403 when your plan does not include the Public API, your IP is not on the allowlist or your account is suspended, and 429 over your plan's rate limit. One bulk request counts as one request toward that limit.

Rate limits

Bulk sends have their own limit: 10 a minute for your account. It counts only bulk sends, and the 60 a minute limit on single sends does not apply here. Over it, you get 429 with a Retry-After header and this body:

{
  "success": false,
  "code": "rate_limited",
  "error": "rate_limit_exceeded",
  "message": "Too many bulk sends. You can make 10 a minute. Wait a moment and try again.",
  "retry_after": 42,
  "limit": 10
}

Nothing is queued by a request that gets 429. To send more numbers, put up to 1,000 in each request.

Good to know

Send an Idempotency-Key. Without one, a second identical request is a second send, and everyone on it gets the SMS twice. With one, a retry gets the first answer back. See Retry safely.
Promotional SMS do not reach numbers on Do Not Disturb. Use a transactional or service template for messages people asked for.
Opted-out numbers are never charged. They are left out before anything is sent.