Batches

A batch is the container for one or more messages created in the same request. Messages cannot exist without a parent batch.

Endpoints

Method	Path	Description
GET	/v2/batches	List batches. The result is paginated.
GET	/v2/batches/{batchId}	Read a single batch.
DELETE	/v2/batches/{batchId}	Delete a batch or cancel a future batch.

List batches

curl "https://api.ip1sms.com/v2/batches?start=0&limit=50&order=DESC" \
  -H "Authorization: Bearer $IP1_TOKEN" \
  -H "Accept: application/json"

Use start, limit and order, as well as the links in the response’s Link header. You can also filter batches by the tags assigned when they were created.

Read a batch

curl "https://api.ip1sms.com/v2/batches/{batchId}" \
  -H "Authorization: Bearer $IP1_TOKEN" \
  -H "Accept: application/json"

batchId is the ID returned when the batch was created.

Delete or cancel

curl -X DELETE "https://api.ip1sms.com/v2/batches/{batchId}" \
  -H "Authorization: Bearer $IP1_TOKEN"

Treat this as a destructive operation. For a scheduled batch, it cancels future delivery. Check the response before marking the local record as canceled.

Batch document

{
  "id": "batch_abc123",
  "sender": "YourCompany",
  "body": "Your booking is confirmed.",
  "owner": "ip1-XXXXX",
  "direction": "MT",
  "type": "sms",
  "datacoding": "GSM",
  "priority": 1,
  "templated": false,
  "priceSummary": {
    "total": 0.125,
    "currency": "SEK",
    "average": 0.0416
  },
  "messageSummary": {
    "201": { "messages": 3, "sms": 3 }
  },
  "deliveryWindows": [
    {
      "opens": "2026-10-05T08:00:00Z",
      "closes": "2026-10-05T10:00:00Z"
    }
  ],
  "status": 112,
  "deliveryReportUrl": "https://example.com/webhooks/ip1/delivery",
  "reference": "order-123",
  "tags": ["transactional"]
}

Fields

Field	Type	Description
id	string	Batch ID.
sender	string	Sender used for the messages.
body	string	Original message text before templating.
owner	string	Owning SMS account.
direction	string	MT for outbound or MO for inbound.
type	string	sms or flash.
datacoding	string	gsm or ucs.
priority	integer	1 or 2.
templated	boolean	Whether the text contains recipient-specific templating.
priceSummary	object	total, currency and average.
messageSummary	object	Message and SMS segment counts grouped by status code.
deliveryWindows	object[]	Time windows with opens and closes.
status	integer	Aggregate batch status.
deliveryReportUrl	string | null	URL for status callbacks.
reference	string | null	Your own reference.
tags	string[]	Your own categories.

Batch status

Name	Code	Meaning
Planned	101	The batch is scheduled for the future.
Ongoing	111	The batch is being processed and sent.
Sent	112	The batch has been sent.
Incoming	201	The batch contains inbound messages.
Canceled	203	The batch has been canceled.

Batch status is not a substitute for an individual message’s status. Read Messages or use Delivery reports when you need to handle each recipient’s outcome.