Skip to main content
POST
cURL
Refer to Authentication for information on how to obtain a bearer token. This endpoint requires the message.sms.send.oneway API client authorization scope to send one way messages. You can set up scopes on the API Clients page.

Rate Limit

This endpoint is rate limited to 400 messages per second.

Request Modes

The required type field selects one of four request modes. Free-form modes compose raw message text; template modes send a pre-approved template by referencing its templateId (see SMS Templates).

Limits

Request Schemas

Send individually tailored free-form messages to multiple recipients.Each item in messages:
Important: for TemplateSendToEach and TemplateSendToMany, after all parameters are substituted, the final message must not exceed 960 characters. A longer resolved message is rejected with Resolved content cannot be longer than 960 characters. There is no truncation or fallback.

Errors

General errors

Recipients with no matching active service channel, or on a channel with an insufficient balance, do not cause an error. The request succeeds with HTTP 200 and those numbers are returned in skipped — even when every recipient is skipped. Malformed phone numbers still return HTTP 400.

Template parameter validation errors

When parameter validation fails, the response is HTTP 400 with desc set to Template parameter validation failed. For TemplateSendToEach, errors are keyed by recipient phone number:
For TemplateSendToMany, errors are returned under a single errors key:

Common parameter validation messages

Success Response

On success the endpoint returns HTTP 200:
skipped is always present. It is an empty array ([]) when every recipient was accepted.

Skipped recipients

A request is no longer rejected when some — or all — of its recipients cannot be processed. Only recipients that can be routed on an active SMS service channel are debited and dispatched; the rest are returned in skipped. A phone number is added to skipped when: Accepted recipients appear only under addresses and units for their channel.

Partial success

When a request mixes routable and non-routable recipients, the routable ones are processed normally (units deducted, message dispatched), the rest are listed in skipped, and the API still returns HTTP 200. Request against a service configured for Safaricom only:
Response:

All recipients skipped

If none of the provided phone numbers has a matching service channel:
  • The API returns HTTP 200not HTTP 400.
  • units and addresses are empty.
  • skipped contains every submitted phone number, exactly as provided in the request.
  • No units are consumed and no messages are dispatched.
  • For template sends, template lookup and validation are not performed, since nothing is routable.

Integration guidance

Treat HTTP 200 as acceptance of the request, not as confirmation that every recipient was sent a message. Always inspect skipped.
  • Retry skipped numbers through another service or channel where appropriate, or surface them to operators when delivery was expected.
  • Use addresses and units for billing and delivery expectations for this request.
  • Use requestId to correlate delivery receipts for the recipients that were dispatched.
  • Do not treat a non-empty skipped list as a failure of the whole request.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

serviceId
string
required

Unique identifier for the messaging service

Body

application/json

Message details for sending to one or multiple recipients

Send message to a single recipient

type
enum<string>
required

Indicates sending to a single recipient

Available options:
SendToEach
messages
object[]
required

Messages and recipients

receiptRequest
object

Response

Message(s) sent successfully

desc
object

The response