Suppressions API

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

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

Using an official SDK? The suppressions resource wraps these endpoints. Guides: TypeScript, Python, Go, PHP, Ruby, Rust, Java, .NET, Swift.

List suppressions

GET /v1/suppressions

Returns a paginated list of suppressed email addresses.

Query parameters:

Parameter	Type	Default	Description
`page`	integer	0	Page number (zero-indexed).
`limit`	integer	50	Results per page (max 200).
`search`	string	--	Filter by email address substring.

cURL:

curl "https://govconnect.ke/v1/suppressions?page=0&limit=50&search=example.com" \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Python:

import requests
 
response = requests.get(
    "https://govconnect.ke/v1/suppressions",
    params={"page": 0, "limit": 50, "search": "example.com"},
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
)
print(response.json())

Node.js:

const response = await fetch(
  "https://govconnect.ke/v1/suppressions?page=0&limit=50&search=example.com",
  {
    headers: { Authorization: "Bearer tfm_k_YOUR_API_KEY" },
  }
);
const data = await response.json();

Response:

{
  "items": [
    {
      "id": "sup_abc123",
      "email_address": "bounced@example.com",
      "reason": "bounce",
      "created_at": "2026-04-06T10:00:00Z"
    },
    {
      "id": "sup_def456",
      "email_address": "complained@example.com",
      "reason": "complaint",
      "created_at": "2026-04-05T14:30:00Z"
    }
  ],
  "total": 2,
  "page": 0,
  "limit": 50
}

Add a suppression

POST /v1/suppressions

Add an email address to the suppression list. Emails to suppressed addresses are silently dropped at send time.

Request body:

{
  "email_address": "bad-address@example.com",
  "reason": "manual"
}

Field	Type	Required	Description
`email_address`	string	Yes	The email address to suppress.
`reason`	string	No	Reason for suppression. Defaults to `"manual"`.

Valid reasons:

Reason	Description
`bounce`	The address hard-bounced.
`complaint`	The recipient filed a spam complaint.
`manual`	Manually added by an account user or API call.

curl -X POST https://govconnect.ke/v1/suppressions \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "bad-address@example.com",
    "reason": "manual"
  }'

Response (201 Created):

{
  "id": "sup_ghi789",
  "email_address": "bad-address@example.com",
  "reason": "manual"
}

Remove a suppression

DELETE /v1/suppressions/{suppression_id}

Remove an email address from the suppression list, allowing future emails to be delivered to it.

cURL:

curl -X DELETE https://govconnect.ke/v1/suppressions/sup_ghi789 \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Python:

import requests
 
response = requests.delete(
    "https://govconnect.ke/v1/suppressions/sup_ghi789",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
)
# 204 No Content on success

Node.js:

const response = await fetch(
  "https://govconnect.ke/v1/suppressions/sup_ghi789",
  {
    method: "DELETE",
    headers: { Authorization: "Bearer tfm_k_YOUR_API_KEY" },
  }
);
// 204 No Content on success

Response: 204 No Content

No response body is returned.

Bulk suppress from CSV

POST /v1/suppressions/bulk

Upload a CSV file of email addresses to add to the suppression list in bulk. The file is read line by line; each line is treated as one email address (surrounding quotes and commas are stripped). Lines without an @ are ignored.

Bulk suppression requires the Starter plan or above. Free plan users will receive a 403 error.

Request: multipart/form-data with a file field containing the CSV.

cURL:

curl -X POST https://govconnect.ke/v1/suppressions/bulk \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -F "file=@suppressions.csv"

Python:

import requests
 
with open("suppressions.csv", "rb") as f:
    response = requests.post(
        "https://govconnect.ke/v1/suppressions/bulk",
        headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
        files={"file": ("suppressions.csv", f, "text/csv")},
    )
print(response.json())

Node.js:

const fs = require("fs");
const FormData = require("form-data");
 
const form = new FormData();
form.append("file", fs.createReadStream("suppressions.csv"));
 
const response = await fetch("https://govconnect.ke/v1/suppressions/bulk", {
  method: "POST",
  headers: {
    Authorization: "Bearer tfm_k_YOUR_API_KEY",
    ...form.getHeaders(),
  },
  body: form,
});
const data = await response.json();

Response (201 Created):

{
  "added": 142,
  "skipped": 8,
  "total_processed": 150
}

Field	Type	Description
`added`	integer	Number of new emails added to the suppression list.
`skipped`	integer	Number of emails that were already suppressed or invalid.
`total_processed`	integer	Total rows processed from the CSV.

Errors

Status	Cause
`400 Bad Request`	Invalid email address format or missing required fields.
`401 Unauthorized`	Missing or invalid authentication token.
`403 Forbidden`	Plan does not support this feature (bulk suppress on Free plan).
`404 Not Found`	Suppression ID does not exist.
`409 Conflict`	Email address is already on the suppression list.
`422 Unprocessable Entity`	Request body validation failed.

Suppressions API

List suppressions

Add a suppression

Remove a suppression

Bulk suppress from CSV

Errors

On this page