Send SMS

Send one or more SMS messages by creating a batch.

Endpoint

Method	Path	Content-Type
POST	/v2/batches	application/json

Quickstart

curl -X POST "https://api.ip1sms.com/v2/batches" \
  -H "Authorization: Bearer $IP1_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "YourCompany",
    "recipients": ["$RECIPIENT"],
    "body": "Your message"
  }'

Enter phone numbers as MSISDNs: country code and number without +, spaces or a leading 00.

Request fields

Field	Required	Type	Conditions
sender	Yes	string	Numeric sender in E.164 format, up to 15 digits, or an alphanumeric sender with 3–11 characters (A–Z, a–z, 0–9).
recipients	Yes	string[] or object	MSISDN, up to 15 digits and digits only. Use the object form for template variables.
body	Yes	string	Must not be empty and may contain up to 2,000 characters.
type	No	string	sms (default) or flash.
datacoding	No	string	gsm for GSM 7-bit or ucs for Unicode. The published default is ucs.
priority	No	integer	1 (default) or 2. High priority may incur a surcharge.
deliveryWindows	No	object[]	One or more time windows with opens and closes in ISO 8601. Windows must not overlap.
deliveryReportUrl	No	string	Absolute HTTPS URL that receives status updates by POST.
reference	No	string	Your own reference, 1–40 characters.
tags	No	string[]	Tags used to categorize and filter batches.

Check the current price list before using priority: 2; the fixed surcharge stated in older documentation may change.

Per-recipient templates

Replace the recipient list with an object when the same message needs different variable values:

{
  "sender": "YourCompany",
  "recipients": {
    "46700000001": { "firstName": "Anna" },
    "46700000002": {},
    "default": { "firstName": "customer" }
  },
  "body": "Hello {firstName}, your booking is confirmed."
}

Each top-level key is the recipient’s MSISDN. Keys below the recipient are matched to placeholders in body. default is used when a recipient has no value.

Scheduling

{
  "deliveryWindows": [
    {
      "opens": "2026-10-05T08:00:00Z",
      "closes": "2026-10-05T10:00:00Z"
    }
  ]
}

If opens is null, the current time is used. If closes is null, the published documentation sets it to 72 hours after opening. If the field is omitted, the system creates a default window.

JavaScript example

Run this on a server, not in a browser:

const response = await fetch('https://api.ip1sms.com/v2/batches', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.IP1_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sender: 'YourCompany',
    recipients: [process.env.TEST_RECIPIENT],
    body: 'Test from the iP.1 SMS API',
    reference: crypto.randomUUID(),
  }),
});

if (!response.ok) {
  throw new Error(`SMS request failed: ${response.status} ${await response.text()}`);
}

const batch = await response.json();
console.log(batch.id);

Batch response

A successful request returns the batch document. Key fields:

Field	Type	Description
id	string	Unique batch ID.
sender	string	Registered sender.
body	string	Original text before templating.
owner	string	Account that owns the batch.
direction	string	MT for outbound or MO for inbound.
type	string	sms or flash.
datacoding	string	gsm or ucs.
templated	boolean	Whether recipient templates were used.
priceSummary	object	Total, currency and average cost.
messageSummary	object	Message and segment counts by status code.
deliveryWindows	object[]	The batch’s delivery windows.
status	integer	Aggregate batch status.
deliveryReportUrl	string | null	Delivery-report callback.
reference	string | null	Your own reference.
tags	string[]	The batch’s tags.

Common HTTP errors

Code	Meaning	Check
400	Bad Request	JSON, required fields and field formats.
401	Unauthorized	The Bearer token is missing or invalid.
403	Forbidden	The key lacks permission or the sender is not allowed.
404	Not Found	The resource or path does not exist.
405	Method Not Allowed	The HTTP method is incorrect.
409	Conflict	The resource conflicts with the existing state.
500	Internal Server Error	Temporary server error; log correlation data and retry in a controlled way.
503	Service Unavailable	Temporary unavailability; use backoff.

The error response body normally contains a more detailed description. Do not log the Bearer token or complete recipient numbers when troubleshooting.