Track delivery
Know whether each message reached its recipient, by webhook or by polling.
Every message moves through a few states. See Message lifecycle for the full list.
pending ──► sent ──► delivered reached the handset
│ └────► failed the network couldn't deliver it
└────────────────► failed the network refused it (cost refunded)Option 1: webhooks (recommended)
Set up a webhook endpoint and we POST sms.delivered or sms.failed the moment the network reports back. There's nothing to poll, no rate limits to plan around, and every event is signed and retried.
Option 2: polling
Fetch a message by id:
curl https://api.softlinksms.co.ke/api/v1/sms/3fae8b8e-9c3a-4e9a-9d3a-7e8e9c3a4e9a \
-H "X-Api-Key: $SOFTLINK_API_KEY"Or list recent messages, newest first, filtered by outcome:
curl "https://api.softlinksms.co.ke/api/v1/sms?status=error&page_size=100" \
-H "X-Api-Key: $SOFTLINK_API_KEY"status filter | Matches |
|---|---|
pending | Accepted, not yet handed to the network. |
sent | Handed to the network, or being retried. |
success | Delivery confirmed. |
error | Failed or bounced. |
You can also filter by mobile (part of the number) or search (number, message text or delivery description). Lists are paginated; see Pagination.
If you poll, back off: check after 5 seconds, then 30, then every few minutes. Most SMS confirm within seconds; a phone that's off can take hours or days.
Reading the outcome
| Field | Meaning |
|---|---|
status | Where the message is now. |
response_code, response_description | What the network said when we handed the message over. 200 / Success means it was accepted. |
message_id | The network's reference for the message. Quote it when contacting support. |
duration_ms | How long the handover to the network took. |
Webhook payloads add delivered_at and delivery_description, the network's own words for the outcome, such as DeliveredToTerminal or DeliveryImpossible.
Undelivered messages are still charged
Once the network accepts a message, it charges us whether or not the handset receives it. A message that ends as failed after being sent (for example, a phone that's been off for days) isn't refunded. Messages the network refuses outright are refunded automatically.