Send SMS /api/sms/send

Sends a one-way SMS to a single recipient. The call is synchronous up to provider
acceptance (not final delivery) — on success you get a message_id to correlate with
later logs and delivery webhooks.

Headers

Header	Required	Notes
`x-api-key`	yes	Your API key.
`Content-Type: application/json`	yes
`Idempotency-Key`	no	See Idempotency. Strongly recommended.

Body

Field	Type	Required	Rules
`recipient`	string	yes	Phone number. Max 20 chars. Normalised to E.164 in your org's country (defaults to Nigeria / `NG`); must be a deliverable number.
`body`	string	yes	The message text. Max 1600 chars. When `template` is set, this is the template's variable value(s) instead.
`sender_id`	string (UUID)	no	UUID of one of your approved sender IDs (or the platform default). Omit to auto-select your approved sender ID, then the platform default.
`message_type`	string	no	One of `one_way`, `two_way`, `multimedia`. Defaults to `one_way`. Only `one_way` is currently supported — others are rejected.
`template`	string	no	Name of an approved template in your account. Max 100 chars. When set, the message content comes from the template.

Example request

Success — 200 OK

{
  "success": true,
  "message": "SMS accepted for delivery",
  "data": { "message_id": "a3d5f0c1-9e22-4b7a-8f1c-2d6e9b0a4c77", "status": "accepted" }
}

message_id is the message's UUID — use it to look it up in /sms/logs
and to match delivery webhooks. status: "accepted" means the
provider accepted it for delivery; poll the logs (or use a webhook) for the final state.

Billing. A provisional charge is held from your wallet at send time and trued-up to
the provider's exact cost once the delivery report arrives (no markup). The balance
check is segment-aware (long / non-GSM messages cost more units). If the provider rejects
the send outright (502), the charge is automatically refunded.

Errors specific to this endpoint

HTTP	When	`message` (example)
`422`	Body fails validation	`SMS body is required` (+ `errors` map)
`400`	Invalid recipient number	`Invalid phone number. Please provide a valid recipient.`
`400`	`sender_id` not yours / not approved	`Invalid or unauthorized sender_id`
`400`	No approved sender ID and no default	`No approved sender ID found. Please request and get a sender ID approved before sending.`
`400`	Non–one-way `message_type`	`Only one-way messaging is currently supported`
`404`	`template` name not found	`Template not found or invalid`
`402`	Wallet too low	`Insufficient wallet balance…` (+ `code: insufficient_funds`)
`502`	Provider rejected the send	`The SMS could not be submitted to the provider. It was not charged — please retry shortly…`

Request

Responses