Broadcasts API

API reference for creating, sending and tracking broadcasts and A/B variants in Taifa Mail.

Base URL: https://govconnect.ke/v1

All endpoints require authentication via API Key or JWT cookie. API keys use the tfm_k_ prefix.

See the Broadcasts overview for concepts.

List broadcasts

GET /v1/broadcasts/

Returns the broadcasts in your workspace, newest first.

Query parameters:

Parameter	Type	Default	Description
`status`	string	--	Filter by status: `draft`, `scheduled`, `sending`, `sent`, `cancelled`.
`limit`	integer	50	Results to return (1-200).

curl "https://govconnect.ke/v1/broadcasts/?status=sent" \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Create a broadcast

POST /v1/broadcasts/

Creates a broadcast in draft status, or scheduled when scheduled_at is set.

Request body:

Field	Type	Required	Description
`name`	string	Yes	Internal name for the broadcast.
`subject`	string	Yes	Subject line.
`from_address`	string	Yes	Sender address used in the `From` header.
`html_body`	string	No	HTML body.
`text_body`	string	No	Plain-text body.
`reply_to`	string	No	Reply-To address.
`contact_list_id`	string (UUID)	No	The contact list to send to. Required before sending.
`sender_address_id`	string (UUID)	No	A sender address in your workspace.
`scheduled_at`	string (ISO 8601)	No	If set, the broadcast is created `scheduled` and sends automatically at this time.

curl -X POST https://govconnect.ke/v1/broadcasts/ \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "April newsletter",
    "subject": "What'\''s new in April",
    "from_address": "news@yourdomain.com",
    "html_body": "<h1>Hello</h1>",
    "text_body": "Hello",
    "contact_list_id": "8f1d2c3a-..."
  }'

Response (201 Created):

{
  "id": "8f1d2c3a-...",
  "org_id": "...",
  "user_id": "...",
  "contact_list_id": "...",
  "sender_address_id": null,
  "name": "April newsletter",
  "subject": "What's new in April",
  "html_body": "<h1>Hello</h1>",
  "text_body": "Hello",
  "from_address": "news@yourdomain.com",
  "reply_to": null,
  "status": "draft",
  "scheduled_at": null,
  "sent_at": null,
  "recipient_count": 0,
  "queued_count": 0,
  "delivered_count": 0,
  "bounced_count": 0,
  "failed_count": 0,
  "opened_count": 0,
  "clicked_count": 0,
  "created_at": "2026-04-06T10:00:00Z",
  "updated_at": "2026-04-06T10:00:00Z"
}

Get a broadcast

GET /v1/broadcasts/{broadcast_id}

Returns the broadcast with its aggregate counters (recipient_count, queued_count, delivered_count, bounced_count, failed_count, opened_count, clicked_count).

Update a broadcast

PATCH /v1/broadcasts/{broadcast_id}

Updates a draft or scheduled broadcast. Editing a broadcast in any other status returns 409. Accepts the same fields as create, all optional. Setting or clearing scheduled_at moves the status between scheduled and draft.

Delete a broadcast

DELETE /v1/broadcasts/{broadcast_id}

Deletes a broadcast. A sending broadcast must be cancelled first. Returns 204 No Content.

Send a broadcast

POST /v1/broadcasts/{broadcast_id}/send

Hands a draft or scheduled broadcast off for delivery and moves it to sending. Recipients come from the broadcast's contact_list_id, which must be set and non-empty. The sender address, if set, must be active and visible to your workspace.

curl -X POST https://govconnect.ke/v1/broadcasts/8f1d2c3a-.../send \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Returns the updated BroadcastResponse.

Cancel a broadcast

POST /v1/broadcasts/{broadcast_id}/cancel

Stops a scheduled or sending broadcast and sets its status to cancelled. Returns the updated BroadcastResponse.

Parameter	Type	Default	Description
`limit`	integer	10	Number of links to return (1-50).

Variants (A/B testing)

GET    /v1/broadcasts/{broadcast_id}/variants
POST   /v1/broadcasts/{broadcast_id}/variants
PATCH  /v1/broadcasts/{broadcast_id}/variants/{variant_id}
DELETE /v1/broadcasts/{broadcast_id}/variants/{variant_id}

Variants can only be created, edited, or deleted while the broadcast is draft or scheduled. See A/B testing.

Create variant request body:

Field	Type	Required	Description
`label`	string	Yes	Variant label. Must be unique within the broadcast.
`subject`	string	Yes	Subject line for this variant.
`html_body`	string	No	HTML body override.
`text_body`	string	No	Plain-text body override.
`weight`	integer	No	Relative send weight (1 or higher). Defaults to `1`.

curl -X POST https://govconnect.ke/v1/broadcasts/8f1d2c3a-.../variants \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Short subject", "subject": "April news", "weight": 1 }'

Variant response:

{
  "id": "...",
  "broadcast_id": "...",
  "label": "Short subject",
  "subject": "April news",
  "html_body": null,
  "text_body": null,
  "weight": 1,
  "recipient_count": 0,
  "delivered_count": 0,
  "bounced_count": 0,
  "failed_count": 0,
  "opened_count": 0,
  "clicked_count": 0,
  "created_at": "2026-04-06T10:00:00Z"
}

PATCH accepts the same fields, all optional. DELETE returns 204 No Content.

Errors

Status	Cause
`401 Unauthorized`	Missing or invalid authentication.
`404 Not Found`	Broadcast or variant ID does not exist.
`409 Conflict`	Invalid status transition, or a variant label already exists.
`422 Unprocessable Entity`	Validation failed, e.g. no contact list, empty list, inactive sender address, or invalid status filter.