Taifa MailTaifa Mail Docs
API Reference

Forwards API

API reference for creating and managing email forwarding rules 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.

Create a forward

POST /v1/forwards/

Create an email forwarding rule. The domain that owns the source email must be verified and must have an MX record pointing to Taifa Mail so it can receive mail. The rule is synced to Postfix immediately upon creation.

Request body:

{
  "source_email": "info@yourdomain.com",
  "destination_emails": [
    "alice@gmail.com",
    "bob@company.com"
  ],
  "destination_urls": [
    "https://yourapp.com/inbound-hook"
  ],
  "domain_id": "dom_abc123"
}
FieldTypeRequiredDescription
source_emailstring (email)YesThe address to forward mail from. Must belong to a verified domain.
destination_emailsstring[] (email)NoEmail addresses to forward mail to.
destination_urlsstring[] (HTTPS URL)NoHTTPS endpoints to POST the inbound message to.
domain_idstring (UUID)YesThe ID of the verified domain that owns the source email.

At least one of destination_emails or destination_urls must contain a value. Both default to empty arrays.

cURL:

curl -X POST https://govconnect.ke/v1/forwards/ \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_email": "info@yourdomain.com",
    "destination_emails": ["alice@gmail.com", "bob@company.com"],
    "domain_id": "dom_abc123"
  }'

Python:

import requests
 
response = requests.post(
    "https://govconnect.ke/v1/forwards/",
    headers={
        "Authorization": "Bearer tfm_k_YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "source_email": "info@yourdomain.com",
        "destination_emails": ["alice@gmail.com", "bob@company.com"],
        "domain_id": "dom_abc123",
    },
)
print(response.json())

Node.js:

const response = await fetch("https://govconnect.ke/v1/forwards/", {
  method: "POST",
  headers: {
    Authorization: "Bearer tfm_k_YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source_email: "info@yourdomain.com",
    destination_emails: ["alice@gmail.com", "bob@company.com"],
    domain_id: "dom_abc123",
  }),
});
const data = await response.json();

Response (201 Created):

{
  "id": "fwd_abc123",
  "source_email": "info@yourdomain.com",
  "destination_emails": ["alice@gmail.com", "bob@company.com"],
  "destination_urls": [],
  "domain_id": "dom_abc123",
  "is_active": true,
  "last_delivered_at": null,
  "delivery_count": 0,
  "created_at": "2026-04-06T10:00:00Z"
}

List forwards

GET /v1/forwards/

Returns all email forwarding rules in your workspace as a JSON array.

cURL:

curl https://govconnect.ke/v1/forwards/ \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Python:

import requests
 
response = requests.get(
    "https://govconnect.ke/v1/forwards/",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
)
print(response.json())

Node.js:

const response = await fetch("https://govconnect.ke/v1/forwards/", {
  headers: { Authorization: "Bearer tfm_k_YOUR_API_KEY" },
});
const data = await response.json();

Response:

[
  {
    "id": "fwd_abc123",
    "source_email": "info@yourdomain.com",
    "destination_emails": ["alice@gmail.com", "bob@company.com"],
    "destination_urls": [],
    "domain_id": "dom_abc123",
    "is_active": true,
    "last_delivered_at": "2026-04-06T14:30:00Z",
    "delivery_count": 12,
    "created_at": "2026-04-06T10:00:00Z"
  }
]

Update a forward

PATCH /v1/forwards/{forward_id}

Update an existing forwarding rule. You can change the destinations or toggle the rule on and off. Changes are synced to Postfix immediately. A rule must keep at least one destination; an update that empties both destination lists returns 400.

Request body:

{
  "destination_emails": ["alice@gmail.com", "carol@company.com"],
  "is_active": false
}
FieldTypeRequiredDescription
destination_emailsstring[] (email)NoNew list of destination email addresses. Omit or pass null to leave unchanged.
destination_urlsstring[] (HTTPS URL)NoNew list of destination HTTPS endpoints. Omit or pass null to leave unchanged.
is_activebooleanNoSet to false to pause forwarding, true to resume. Omit or pass null to leave unchanged.

cURL:

curl -X PATCH https://govconnect.ke/v1/forwards/fwd_abc123 \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_emails": ["alice@gmail.com", "carol@company.com"],
    "is_active": false
  }'

Python:

import requests
 
response = requests.patch(
    "https://govconnect.ke/v1/forwards/fwd_abc123",
    headers={
        "Authorization": "Bearer tfm_k_YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "destination_emails": ["alice@gmail.com", "carol@company.com"],
        "is_active": False,
    },
)
print(response.json())

Node.js:

const response = await fetch(
  "https://govconnect.ke/v1/forwards/fwd_abc123",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer tfm_k_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      destination_emails: ["alice@gmail.com", "carol@company.com"],
      is_active: false,
    }),
  }
);
const data = await response.json();

Response:

{
  "id": "fwd_abc123",
  "source_email": "info@yourdomain.com",
  "destination_emails": ["alice@gmail.com", "carol@company.com"],
  "destination_urls": [],
  "domain_id": "dom_abc123",
  "is_active": false,
  "last_delivered_at": "2026-04-06T14:30:00Z",
  "delivery_count": 12,
  "created_at": "2026-04-06T10:00:00Z"
}

Delete a forward

DELETE /v1/forwards/{forward_id}

Delete a forwarding rule. The rule is removed from Postfix immediately.

cURL:

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

Python:

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

Node.js:

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

Response: 204 No Content

No response body is returned.

List forwarded emails

GET /v1/forwards/logs

Returns a paginated list of emails that have been forwarded.

Query parameters:

ParameterTypeDefaultDescription
forward_idstring (UUID)--Filter logs by a specific forwarding rule.
pageinteger0Page number (zero-indexed).
limitinteger20Results per page (1-100).

cURL:

curl "https://govconnect.ke/v1/forwards/logs?forward_id=fwd_abc123&page=0&limit=20" \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Python:

import requests
 
response = requests.get(
    "https://govconnect.ke/v1/forwards/logs",
    params={"forward_id": "fwd_abc123", "page": 0, "limit": 20},
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
)
print(response.json())

Node.js:

const response = await fetch(
  "https://govconnect.ke/v1/forwards/logs?forward_id=fwd_abc123&page=0&limit=20",
  {
    headers: { Authorization: "Bearer tfm_k_YOUR_API_KEY" },
  }
);
const data = await response.json();

Response (JSON array):

[
  {
    "id": "fl_abc123",
    "from_address": "sender@external.com",
    "original_to": "info@yourdomain.com",
    "forwarded_to": "alice@gmail.com",
    "subject": "Partnership inquiry",
    "message_id": "<abc123@external.com>",
    "size_bytes": 4521,
    "created_at": "2026-04-06T14:30:00Z"
  }
]

Count forwarded emails

GET /v1/forwards/logs/count

Returns the total number of forwarded emails, optionally filtered by forwarding rule.

Query parameters:

ParameterTypeDefaultDescription
forward_idstring (UUID)--Filter count by a specific forwarding rule.

cURL:

curl "https://govconnect.ke/v1/forwards/logs/count?forward_id=fwd_abc123" \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Response:

{
  "count": 347
}

Forwarding stats

GET /v1/forwards/stats

Returns forwarding statistics for the last 30 days. per_rule is an object keyed by forwarding rule ID, with the forwarded-email count as the value.

cURL:

curl https://govconnect.ke/v1/forwards/stats \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Python:

import requests
 
response = requests.get(
    "https://govconnect.ke/v1/forwards/stats",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
)
print(response.json())

Node.js:

const response = await fetch("https://govconnect.ke/v1/forwards/stats", {
  headers: { Authorization: "Bearer tfm_k_YOUR_API_KEY" },
});
const data = await response.json();

Response:

{
  "total_this_month": 1250,
  "per_rule": {
    "fwd_abc123": 890,
    "fwd_def456": 360
  }
}

Errors

StatusCause
400 Bad RequestInvalid email format or missing required fields.
401 UnauthorizedMissing or invalid authentication token.
403 ForbiddenPlan does not support this feature, or domain is not owned by your account.
404 Not FoundForward ID or domain ID does not exist.
409 ConflictA forwarding rule for this source email already exists.
422 Unprocessable EntityDomain is not verified, or request body validation failed.

Previous

Suppressions API

Next

Inbound API

On this page