Campaign Status

Check the overall delivery status of a bulk SMS campaign — total sent, failed, and delivery rate.

When to use: Poll this endpoint after sending with Send Bulk SMS or Send to Address Book to monitor campaign progress.

Endpoint

POST /v1/sms/campaigns/status/

Authentication: Bearer API key

Request Body

{
  "campaign_id": "44210c48-5ba9-4784-b434-dd57bf1d2b46"
}

Field	Type	Required	Description
`campaign_id`	UUID string	Yes	The `campaign_id` returned when you sent the bulk campaign

Request

curl -X POST https://api.talkntalk.africa/v1/sms/campaigns/status/ \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "44210c48-5ba9-4784-b434-dd57bf1d2b46" }'

Response

200 OK

{
  "campaign_id":      "44210c48-5ba9-4784-b434-dd57bf1d2b46",
  "status":           "completed",
  "message":          "Your invoice is ready. Log in to view it.",
  "sender_id":        "TALKNTALK",
  "recipients_count": 1248,
  "sent_count":       1245,
  "failed_count":     3,
  "delivery_rate":    99.8,
  "created_at":       "2026-05-20T11:00:00+03:00",
  "started_at":       "2026-05-20T11:00:02+03:00",
  "finished_at":      "2026-05-20T11:06:44+03:00"
}

Field	Description
`campaign_id`	UUID of the campaign
`status`	Current campaign state — see Campaign statuses
`message`	The message body that was sent
`sender_id`	Sender name used
`recipients_count`	Total unique recipients in this campaign
`sent_count`	Number successfully submitted to the network
`failed_count`	Number that could not be sent
`delivery_rate`	`sent_count / recipients_count × 100`, rounded to 1 decimal
`created_at`	When the campaign was created
`started_at`	When the campaign worker began dispatching
`finished_at`	When all recipients were processed (`null` if still running)

Campaign Statuses

Status	Meaning
`queued`	Accepted — waiting for the worker to start
`running`	Currently dispatching messages to recipients
`completed`	All recipients processed
`failed`	Campaign encountered a fatal error
`paused`	Paused mid-run (e.g. provider credits depleted — resumes automatically)

Polling pattern

// Node.js — poll until completed
async function waitForCampaign(campaignId, intervalMs = 5000) {
  while (true) {
    const res = await fetch('https://api.talkntalk.africa/v1/sms/campaigns/status/', {
      method:  'POST',
      headers: { 'Authorization': 'Bearer tk_live_xxxx', 'Content-Type': 'application/json' },
      body:    JSON.stringify({ campaign_id: campaignId }),
    });
    const data = await res.json();
 
    console.log(`Status: ${data.status} | ${data.sent_count}/${data.recipients_count} sent`);
 
    if (['completed', 'failed'].includes(data.status)) return data;
    await new Promise(r => setTimeout(r, intervalMs));
  }
}

# Python — poll until completed
import time, requests
 
def wait_for_campaign(campaign_id, interval=5):
    while True:
        r = requests.post(
            'https://api.talkntalk.africa/v1/sms/campaigns/status/',
            headers={'Authorization': 'Bearer tk_live_xxxx'},
            json={'campaign_id': campaign_id},
        )
        data = r.json()
        print(f"Status: {data['status']} | {data['sent_count']}/{data['recipients_count']} sent")
        if data['status'] in ('completed', 'failed'):
            return data
        time.sleep(interval)

Tip: For real-time notifications instead of polling, use Webhooks — TalkNTalk fires sms.sent, sms.delivered, and sms.failed events per message.

Error Responses

Status	Description
`400 Bad Request`	`campaign_id` missing
`401 Unauthorized`	Missing or invalid API key
`404 Not Found`	Campaign not found or does not belong to your organisation

Fetch Messages Campaign Messages