Notifications API

API reference for reading notifications and managing notification preferences 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 Notification preferences for concepts.

List notifications

GET /v1/notifications

Query parameters:

Parameter	Type	Default	Description
`unread`	boolean	`false`	If `true`, return only unread notifications.
`category`	string	--	Filter by category (e.g. `alerts`, `sends`).
`limit`	integer	50	Maximum results to return (1-200).

curl "https://govconnect.ke/v1/notifications?unread=true" \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Response:

{
  "items": [
    {
      "id": "ntf_abc123",
      "category": "alerts",
      "severity": "info",
      "title": "New API key created",
      "body": "Key 'Production backend' was just created.",
      "href": "/api-keys",
      "read_at": null,
      "created_at": "2026-04-06T10:00:00Z"
    }
  ],
  "total": 1,
  "unread": 1
}

total is the count of all notifications for the user; unread is the count of those with read_at unset. Both ignore the limit and filters.

Mark a notification as read

POST /v1/notifications/{notification_id}/read

Mark all as read

POST /v1/notifications/read-all

Get notification preferences

GET /v1/notifications/preferences

Returns the per-category channel matrix for the authenticated user.

Response:

{
  "preferences": {
    "alerts": { "web": true, "email": true, "slack": false },
    "sends":  { "web": true, "email": false, "slack": false },
    "team":   { "web": true, "email": true, "slack": false }
  }
}

Update notification preferences

PUT /v1/notifications/preferences

Request body:

{
  "preferences": {
    "alerts": { "web": true, "email": true, "slack": true },
    "sends":  { "web": true, "email": false, "slack": false },
    "team":   { "web": true, "email": false, "slack": false }
  }
}

Valid channels are web, email and slack. Unknown keys are ignored.

curl -X PUT https://govconnect.ke/v1/notifications/preferences \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preferences": {"alerts": {"web": true, "email": true, "slack": true}}}'

Errors

Status	Cause
`400 Bad Request`	`preferences` is not an object.
`401 Unauthorized`	Missing or invalid authentication.
`404 Not Found`	Notification ID does not exist.