Campaigns

Create and send bulk SMS to contact groups or an uploaded recipient list.

Send bulk SMS to one or more contact groups, or from a CSV/XLSX upload. Create the campaign in draft state, review the recipient count and cost estimate, then trigger the send. Every campaign sends from an approved sender ID.

List campaigns

GET/api/v1/campaigns

Query params

status

string

draft | sending | completed | cancelled

page

integer

Page number

page_size

integer

Results per page

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/campaigns?status=completed&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Create a campaign (group-based)

POST/api/v1/campaigns

Parameters

namereq

string

Campaign name (internal reference)

messagereq

string

SMS text to send. Long messages split automatically.

sender_idreq

string

Sender ID UUID

group_idsreq

string[]

Array of contact group UUIDs to target

scheduled_at

ISO 8601

Schedule for future send. Omit to send manually after creation.

curl -X POST "https://timisha-solutions-api.salamu.co.ke/api/v1/campaigns" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "June Flash Sale",
  "message": "Get 25% off this weekend! Code: JUNE25. Shop at acme.ke",
  "sender_id": "sid-uuid",
  "group_ids": [
    "grp-uuid-1",
    "grp-uuid-2"
  ]
}'

200: Created (draft)

{
  "success": true,
  "data": {
    "uuid": "cmp-uuid",
    "name": "June Flash Sale",
    "status": "draft",
    "recipient_count": 3842,
    "cost_units": 3842,
    "created_at": "2026-05-11T09:00:00Z"
  }
}

Draft first

Creation does not send anything. It computes recipient_count and cost_units so you can review the estimated cost before triggering the send.

Create a campaign from file upload

POST/api/v1/campaigns/uploadmultipart/form-data

Upload a CSV or XLSX file with a phone column. Optionally include a message column for personalised messages per row.

Form fields

namereq

string

Campaign name

sender_idreq

string

Sender ID UUID

message

string

Default message if the CSV has no message column

filereq

file

CSV or XLSX file

curl

curl -X POST "$NEXT_PUBLIC_API_URL/api/v1/campaigns/upload" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F 'name=Personalised Offers' \
  -F 'sender_id=sid-uuid' \
  -F 'file=@offers.csv'

Get a campaign

GET/api/v1/campaigns/{uuid}

Fetch a single campaign by UUID, including its status, recipient count, and cost.

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

Send a campaign

POST/api/v1/campaigns/{uuid}/send

Triggers dispatch. Status moves to sending and then completed once all messages are queued.

curl -X POST "https://timisha-solutions-api.salamu.co.ke/api/v1/campaigns/cmp-uuid/send" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Units are reserved on send

SMS units are reserved at this point. Ensure your balance covers cost_units before triggering the send, or the dispatch will fail.

Cancel a campaign

POST/api/v1/campaigns/{uuid}/cancel

Can only cancel campaigns in draft or sending state.

curl -X POST "https://timisha-solutions-api.salamu.co.ke/api/v1/campaigns/cmp-uuid/cancel" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Resend a campaign

POST/api/v1/campaigns/{uuid}/resend

Re-queues failed recipients from a completed campaign.

curl -X POST "https://timisha-solutions-api.salamu.co.ke/api/v1/campaigns/cmp-uuid/resend" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

List recipients

GET/api/v1/campaigns/{uuid}/recipients

Query params

page

integer

Page number

page_size

integer

Results per page

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/campaigns/cmp-uuid/recipients?page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Campaign statuses

Status reference

draft

Created, awaiting manual send trigger or scheduled_at time

sending

Dispatch in progress, messages are being queued via NSQ workers

completed

All messages dispatched to the SMS gateway

cancelled

Cancelled before or during send