Analytics API

API reference for retrieving email sending analytics and time series data in Taifa Mail.

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

All endpoints require authentication via API Key or JWT cookie.

Get analytics overview

GET /v1/analytics/overview

Returns aggregate email sending statistics for the specified period.

Query parameters:

Parameter	Type	Default	Description
`period`	string	`30d`	Time period to query. Valid values: `24h`, `7d`, `30d`, `90d`.

cURL:

curl "https://govconnect.ke/v1/analytics/overview?period=30d" \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Python:

import requests
 
response = requests.get(
    "https://govconnect.ke/v1/analytics/overview",
    params={"period": "30d"},
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
)
print(response.json())

Node.js:

const response = await fetch(
  "https://govconnect.ke/v1/analytics/overview?period=30d",
  {
    headers: { Authorization: "Bearer tfm_k_YOUR_API_KEY" },
  }
);
const data = await response.json();

Response:

{
  "total_sent": 12450,
  "delivered": 12105,
  "bounced": 187,
  "failed": 158,
  "opens": 8723,
  "clicks": 2341,
  "period": "30d"
}

Field	Type	Description
`total_sent`	integer	Total emails sent during the period.
`delivered`	integer	Emails successfully delivered.
`bounced`	integer	Emails that hard-bounced.
`failed`	integer	Emails that failed to send (configuration errors, suppressed, etc.).
`opens`	integer	Total open events tracked (includes multiple opens per email).
`clicks`	integer	Total click events tracked (includes multiple clicks per email).
`period`	string	The period that was queried.

To calculate your delivery rate, divide delivered by total_sent. A healthy delivery rate is above 95%.

Get time series data

GET /v1/analytics/timeseries

Returns email sending data bucketed over time. Use this to build charts and dashboards.

Query parameters:

Parameter	Type	Default	Description
`period`	string	`30d`	Time period to query. Valid values: `24h`, `7d`, `30d`, `90d`.
`granularity`	string	`day`	Bucket size. Valid values: `hour`, `day`.

Hourly granularity produces many buckets over long periods. Pair granularity=hour with the 24h or 7d period for readable charts.

cURL:

curl "https://govconnect.ke/v1/analytics/timeseries?period=7d&granularity=day" \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Python:

import requests
 
response = requests.get(
    "https://govconnect.ke/v1/analytics/timeseries",
    params={"period": "7d", "granularity": "day"},
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
)
data = response.json()
for point in data["data"]:
    print(f"{point['timestamp']}: {point['sent']} sent, {point['delivered']} delivered")

Node.js:

const response = await fetch(
  "https://govconnect.ke/v1/analytics/timeseries?period=7d&granularity=day",
  {
    headers: { Authorization: "Bearer tfm_k_YOUR_API_KEY" },
  }
);
const data = await response.json();
data.data.forEach((point) => {
  console.log(
    `${point.timestamp}: ${point.sent} sent, ${point.delivered} delivered`
  );
});

Response:

{
  "data": [
    {
      "timestamp": "2026-04-01T00:00:00Z",
      "sent": 1820,
      "delivered": 1790,
      "bounced": 18,
      "failed": 12,
      "opens": 1240
    },
    {
      "timestamp": "2026-04-02T00:00:00Z",
      "sent": 2105,
      "delivered": 2070,
      "bounced": 22,
      "failed": 13,
      "opens": 1488
    }
  ],
  "period": "7d",
  "granularity": "day"
}

Field	Type	Description
`data`	array	Array of time series data points.
`data[].timestamp`	string (ISO 8601)	Start of the time bucket.
`data[].sent`	integer	Emails sent during this bucket.
`data[].delivered`	integer	Emails delivered during this bucket.
`data[].bounced`	integer	Emails bounced during this bucket.
`data[].failed`	integer	Emails failed during this bucket.
`data[].opens`	integer	Open events recorded during this bucket.
`period`	string	The period that was queried.
`granularity`	string	The bucket size used.

Get domain stats

GET /v1/analytics/domain-stats

Returns a per-recipient-domain breakdown of sent, delivered, bounced, opens, and clicks. Recipient addresses are grouped by their domain and ranked by send volume.

Query parameters:

Parameter	Type	Default	Description
`period`	string	`30d`	Time period to query. Valid values: `24h`, `7d`, `30d`, `90d`.
`limit`	integer	20	Maximum number of domains to return (1-100).

curl "https://govconnect.ke/v1/analytics/domain-stats?period=30d&limit=10" \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Response:

[
  {
    "domain": "gmail.com",
    "sent": 5210,
    "delivered": 5104,
    "bounced": 62,
    "opens": 3870,
    "clicks": 940
  },
  {
    "domain": "outlook.com",
    "sent": 1830,
    "delivered": 1788,
    "bounced": 28,
    "opens": 1102,
    "clicks": 311
  }
]

Field	Type	Description
`domain`	string	The recipient email domain.
`sent`	integer	Distinct emails sent to this domain.
`delivered`	integer	Emails delivered to this domain.
`bounced`	integer	Emails bounced for this domain.
`opens`	integer	Distinct emails opened by recipients on this domain.
`clicks`	integer	Distinct emails with a click from this domain.

Errors

Status	Cause
`400 Bad Request`	Invalid `period` value. Use `24h`, `7d`, `30d`, or `90d`.
`401 Unauthorized`	Missing or invalid authentication token.

Analytics API

Get analytics overview

Get time series data

Get domain stats

Errors

On this page