Send a batch

One text or template to up to 100 numbers in one call, each with its own variables and reference.

Request#

The headers are those of Send a message. The fields that apply to every message come once, and messages lists the recipients.

Each message#

How it's sent#

• What applies to every message is checked first: your account, the sender ID, the template, validity_period and callback_url. If one fails, the call fails with the usual error and nothing is sent.
• Then each message is sent and charged as Send a message would send it, and answers for itself: a bad number, a missing variable or a country you don't send to refuses that message alone.
• Messages count against your messages per second like any other, but a batch waits its turn instead of refusing them. One that would wait more than 25 seconds is refused as rate_limited, with retry_after: send those again.
• With an Idempotency-Key, a repeat of the call with the same key returns the messages sent the first time instead of sending them again. Each message is keyed by its place in messages, so keep the order when you retry.

{
  "from": "YourBrand",
  "body": "Hi {{name}}, your table is booked for {{time}}.",
  "variables": { "time": "19:30" },
  "validity_period": 3600,
  "messages": [
    { "to": "+447700900123", "variables": { "name": "Amy" }, "client_reference": "booking-311" },
    { "to": "+447700900456", "variables": { "name": "Ben", "time": "20:00" }, "client_reference": "booking-312" },
    { "to": "07700 900789", "variables": { "name": "Cy" }, "client_reference": "booking-313" }
  ]
}

Response#

200 OK once the batch was looked at, whatever became of each message: accepted and refused count them, and data has one entry per message, in the order sent. An accepted one has its message; a refused one has to and client_reference as you sent them, and the error it would have got on its own.

{
  "accepted": 2,
  "refused": 1,
  "data": [
    {
      "index": 0,
      "message": {
        "id": "01a18c17-566b-7b3d-9f42-6a8e0d51c2b7",
        "to": "+447700900123",
        "from": "YourBrand",
        "body": "Hi Amy, your table is booked for 19:30.",
        "status": "queued",
        "price_micros": 30000,
        "client_reference": "booking-311",
        "expires_at": "2026-10-30T10:15:02.123456Z",
        …
      }
    },
    {
      "index": 1,
      "message": {
        "id": "01a18c17-566b-7c01-a3c2-5b7e9d0f1a22",
        "body": "Hi Ben, your table is booked for 20:00.",
        …
      }
    },
    {
      "index": 2,
      "to": "07700 900789",
      "client_reference": "booking-313",
      "error": {
        "code": "invalid_to",
        "message": "to must be a valid phone number in E.164 format, e.g. +447700900123"
      }
    }
  ]
}

Errors#

Those of Send a message, for the whole batch or per message, and: