Send an SMS

Send one message to one recipient. This is the endpoint you will use most.

Endpoint

text

POST https://api.sms.pesarails.com/v1/messages

Parameters

Field	Required	Description
`to`	yes	Recipient number. 254..., 07... or +254... are all accepted and normalised.
`message`	yes*	The text to send. Required unless you pass `templateId`.
`sender`	yes	Your sender ID. You may pass `senderId` (the UUID) instead.
`templateId`	no	Send from a template instead of `message`. Pair with `variables`.
`variables`	no	Key/value pairs that fill a template's `{{placeholders}}`.
`scheduledAt`	no	ISO 8601 time to send later. See Scheduling.
`idempotencyKey`	no	Make a send safe to retry. The same key returns the same message, charged once.
`ref`	no	Your own reference, echoed back on the message.

Request

curl

curl https://api.sms.pesarails.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "0712345678",
    "sender": "PESARAILS",
    "message": "Your order #1024 is on the way"
  }'

Response

200 OK

{
  "message": {
    "id": "a1b2c3",
    "status": "sent",
    "to": "254712345678",
    "sender": "PESARAILS",
    "segments": 1,
    "priceKes": 0.5,
    "hostrillMessageId": "998812",
    "balanceAfter": 499.5
  }
}

Tip

Sending the same OTP or receipt twice is a classic retry bug. Pass an idempotencyKey and a repeated request returns the original message instead of sending (and charging) again.

Message statuses

A message moves through these states. Final delivery status arrives by webhook.

Status	Meaning
`queued`	Accepted, about to be sent.
`scheduled`	Held until `scheduledAt`.
`sent`	Handed to the network.
`delivered`	Confirmed on the handset.
`undelivered`	The network could not deliver it.
`failed`	Rejected before sending. Credit is refunded.

Many recipients

To send the same or different messages to many numbers, use bulk messages rather than looping this endpoint.