History & status

List sent messages, filter them, and check delivery status.

List messages

Retrieve a paginated history of messages, filtered by status, recipient, sender, date range, or a full-text search on the body.

GET/api/v1/messages

Query params

page

integer

Page number (default 1)

page_size

integer

Results per page (default 20, max 100)

status

string

queued | sent | delivered | failed

phone

string

Filter by recipient phone

sender_id

string

Filter by sender ID UUID

string

Full-text search on message body

date_from

ISO 8601

Start of date range (e.g. 2026-05-01T00:00:00Z)

date_to

ISO 8601

End of date range

campaign_id

string

Filter messages sent by a specific campaign ID

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/messages?status=delivered&phone=%2B254712345678&page_size=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get a message

Fetch a single message by its UUID to read its current status and metadata.

GET/api/v1/messages/{uuid}

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/messages/msg-uuid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

200: OK

{
  "success": true,
  "data": {
    "uuid": "msg-uuid",
    "to": "+254712345678",
    "message": "Your OTP is 483920. Valid for 10 minutes.",
    "sender_id": "MYAPP",
    "status": "delivered",
    "parts": 1,
    "created_at": "2026-05-11T09:00:00Z"
  }
}

Message statuses

Every message moves through these states as it is dispatched and confirmed:

queued, accepted and placed in the send queue.
sent, handed off to the carrier or SMSC.
delivered, carrier confirmed delivery to the handset.
failed, carrier returned a terminal failure (number inactive, wrong NPI, and similar).
expired, message TTL elapsed before delivery.

Delivery is asynchronous

A message returns queued on send and reaches delivered or a terminal state once the carrier reports back. Poll this endpoint or list history filtered by status to track progress.