Fetch Messages

Retrieve a paginated list of outbound SMS messages sent by your organisation. Filter by status, recipient number, sender ID, or source.

Endpoint

GET /v1/bulk-sms/messages/

Authentication: Bearer API key

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: `1`)
`page_size`	integer	No	Results per page (default: `100`, max: `500`)
`status`	string	No	Filter by status — see Status values below
`mobile`	string	No	Filter by recipient phone number (partial match)
`sender_id`	string	No	Filter by sender ID name (exact, case-insensitive)
`source`	string	No	`api` or `web`

Request

curl https://api.talkntalk.africa/v1/bulk-sms/messages/ \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

With filters:

curl "https://api.talkntalk.africa/v1/bulk-sms/messages/?status=delivered&page=1&page_size=50" \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

200 OK

{
  "total": 1248,
  "page": 1,
  "page_size": 100,
  "total_pages": 13,
  "next": "https://api.talkntalk.africa/v1/bulk-sms/messages/?page=2&page_size=100",
  "previous": null,
  "results": [
    {
      "id": "018f3a2b-7c4d-7e1a-b3f2-9d8e2c1a4b5f",
      "mobile": "254712345678",
      "sender_id": "TALKNTALK",
      "message": "Your OTP is 847291. Valid for 5 minutes.",
      "status": "delivered",
      "network": "safaricom",
      "source": "api",
      "scheduled_at": null,
      "created_at": "2026-05-20T11:30:00+03:00",
      "updated_at": "2026-05-20T11:30:04+03:00"
    }
  ]
}

Response Fields

Field	Type	Description
`id`	UUID string	Unique message identifier
`mobile`	string	Recipient phone number in international format (`254XXXXXXXXX`)
`sender_id`	string	Sender name shown on the recipient's device
`message`	string	The full message body
`status`	string	Current delivery status — see below
`network`	string	Detected recipient network (`safaricom`, `airtel`, `telkom`)
`source`	string	`api` — sent via API key · `web` — sent via the dashboard
`scheduled_at`	string\|null	ISO 8601 timestamp if the message was scheduled, otherwise `null`
`created_at`	string	When the message was created (ISO 8601, Africa/Nairobi)
`updated_at`	string	Last status update timestamp

Status Values

Status	Meaning
`queued`	Accepted and waiting to be dispatched
`sent`	Submitted to the SMS provider
`delivered`	Confirmed delivered to the handset
`failed`	Submission to the provider failed
`undelivered`	Provider could not deliver to the handset
`cancelled`	Message was cancelled before sending
`held`	Waiting — provider credits depleted, will send when topped up
`blocked`	Blocked (DND registry or network policy)

Code Examples

Node.js

const response = await fetch(
  'https://api.talkntalk.africa/v1/bulk-sms/messages/?status=delivered&page_size=50',
  { headers: { Authorization: 'Bearer tk_live_xxxx' } }
);
const { results, total, total_pages } = await response.json();
console.log(`${total} messages across ${total_pages} pages`);

Python

import requests
 
r = requests.get(
    'https://api.talkntalk.africa/v1/bulk-sms/messages/',
    headers={'Authorization': 'Bearer tk_live_xxxx'},
    params={'status': 'delivered', 'page_size': 50},
)
data = r.json()
for msg in data['results']:
    print(msg['mobile'], msg['status'])

PHP

$ch = curl_init('https://api.talkntalk.africa/v1/bulk-sms/messages/?page_size=50');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer tk_live_xxxx']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
foreach ($data['results'] as $msg) {
    echo $msg['mobile'] . ' — ' . $msg['status'] . PHP_EOL;
}

Error Responses

Status	Code	Description
`401 Unauthorized`	`authentication_failed`	Missing or invalid API key
`403 Forbidden`	`permission_denied`	API key does not have read access

Send to Address Book Campaign Status