Batches

A batch sends many messages in one request. There are three ways to create one:

A list of messages, up to 1,000, each with its own recipient and content.
Your contact lists, with one message or template for everyone.
A CSV or Excel file you upload.

Each message in a batch is a normal message. To get them, call GET /v2/sms with batchId.

Sending a list of messages

Put the values every message shares in defaults, and anything specific in each message:

{
  "defaults": { "sender": "YourBrand", "clientTag": "reminders" },
  "messages": [
    { "recipient": "+447700900123", "content": "Hi Sam, see you at 10am tomorrow." },
    { "recipient": "+447700900456", "content": "Hi Alex, see you at 2pm tomorrow." }
  ]
}

Messages that aren’t valid are listed in errors (by their position, from 0) and skipped. The rest are sent. If none are valid, the response is a 400.

API reference: POST /v2/sms/batches

Sending to contact lists

Send list.ids with up to 20 list IDs instead of messages, plus a sender and either content or a template. Contacts in more than one list get one message. list.excludeIds leaves out the contacts in up to 20 other lists.

{
  "list": { "ids": ["301245883010879500"] },
  "sender": "YourBrand",
  "template": { "name": "spring-offer" },
  "kind": "marketing",
  "skipMessagedWithinHours": 24
}

skipMessagedWithinHours skips contacts you have messaged in the last 6, 12, 24, 48, 72 or 168 hours.
pacing sends gradually instead of all at once, for example { "ratePerPeriod": 500, "period": "hour" }.

Importing a file

POST /v2/sms/batches/import sends a message to every row of a CSV or Excel file. The request is multipart/form-data with the file and the batch settings as form fields.

The file needs sender, recipient and content columns, and can have a unicode column with a mode per row. If your headers are named differently, map them with columnMap, for example {"recipient":"Mobile Number","content":"Message"}. A row with an invalid sender or recipient rejects the whole import.

Checking a batch first

POST /v2/sms/batches/preview takes the same body as creating a batch and tells you how many messages would be sent, how many would be skipped, the cost, and whether your balance is high enough. Nothing is sent.

Following a batch

The batch’s counts say how many of its messages are queued, sent, delivered, failed, skipped or cancelled. Get them with GET /v2/sms/batches/{id}, or listen for the batch.completed event.

DELETE /v2/sms/batches/{id} cancels every message in the batch that hasn’t been sent yet.