Templates API

API reference for creating, managing, and duplicating reusable email templates in Taifa Mail.

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

All endpoints require authentication via API Key or JWT cookie.

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

All template endpoints require the Starter plan or above. Free plan users will receive a 403 Forbidden error.

Create a template

POST /v1/templates/

Creates a new reusable email template. Template variables using the {{variable}} syntax in html_body and text_body are automatically extracted and stored with the template.

Request body:

{
  "name": "Welcome email",
  "subject": "Welcome to {{company}}, {{name}}!",
  "html_body": "<h1>Hello {{name}}</h1><p>Welcome to {{company}}. We are glad to have you.</p>",
  "text_body": "Hello {{name}}, welcome to {{company}}. We are glad to have you.",
  "blocks_json": null
}

Field	Type	Required	Description
`name`	string	Yes	A descriptive name for the template.
`subject`	string	No	Default subject line. Supports `{{variable}}` syntax.
`html_body`	string	No	HTML email body. Supports `{{variable}}` syntax.
`text_body`	string	No	Plain-text email body. Supports `{{variable}}` syntax.
`blocks_json`	object	No	Structured block data from the drag-and-drop editor. Used by the dashboard UI.

Response (201 Created):

{
  "id": "tmpl_abc123",
  "name": "Welcome email",
  "subject": "Welcome to {{company}}, {{name}}!",
  "html_body": "<h1>Hello {{name}}</h1><p>Welcome to {{company}}. We are glad to have you.</p>",
  "text_body": "Hello {{name}}, welcome to {{company}}. We are glad to have you.",
  "blocks_json": null,
  "variables": ["name", "company"],
  "created_at": "2026-04-10T08:00:00Z",
  "updated_at": "2026-04-10T08:00:00Z"
}

The variables field is auto-extracted from the html_body and text_body fields. You do not need to specify them manually.

curl -X POST https://govconnect.ke/v1/templates/ \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome email",
    "subject": "Welcome to {{company}}, {{name}}!",
    "html_body": "<h1>Hello {{name}}</h1><p>Welcome to {{company}}.</p>",
    "text_body": "Hello {{name}}, welcome to {{company}}."
  }'

List templates

GET /v1/templates/

Returns all templates for the authenticated workspace as a JSON array, ordered by most recently updated.

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

Response:

[
  {
    "id": "tmpl_abc123",
    "name": "Welcome email",
    "subject": "Welcome to {{company}}, {{name}}!",
    "html_body": "<h1>Hello {{name}}</h1><p>Welcome to {{company}}.</p>",
    "text_body": "Hello {{name}}, welcome to {{company}}.",
    "blocks_json": null,
    "variables": ["name", "company"],
    "created_at": "2026-04-10T08:00:00Z",
    "updated_at": "2026-04-10T08:00:00Z"
  },
  {
    "id": "tmpl_def456",
    "name": "Password reset",
    "subject": "Reset your password",
    "html_body": "<p>Click <a href=\"{{reset_link}}\">here</a> to reset.</p>",
    "text_body": "Reset your password: {{reset_link}}",
    "blocks_json": null,
    "variables": ["reset_link"],
    "created_at": "2026-04-09T14:00:00Z",
    "updated_at": "2026-04-09T14:00:00Z"
  }
]

Python

import requests
 
response = requests.get(
    "https://govconnect.ke/v1/templates/",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"}
)
 
for tmpl in response.json():
    print(f"{tmpl['name']} - variables: {tmpl['variables']}")

Node.js

const response = await fetch("https://govconnect.ke/v1/templates/", {
  headers: { "Authorization": "Bearer tfm_k_YOUR_API_KEY" },
});
 
const templates = await response.json();
templates.forEach((tmpl) => {
  console.log(`${tmpl.name} - variables: ${tmpl.variables}`);
});

Get a template

GET /v1/templates/{template_id}

Returns full details for a single template.

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

Response:

{
  "id": "tmpl_abc123",
  "name": "Welcome email",
  "subject": "Welcome to {{company}}, {{name}}!",
  "html_body": "<h1>Hello {{name}}</h1><p>Welcome to {{company}}. We are glad to have you.</p>",
  "text_body": "Hello {{name}}, welcome to {{company}}. We are glad to have you.",
  "blocks_json": null,
  "variables": ["name", "company"],
  "created_at": "2026-04-10T08:00:00Z",
  "updated_at": "2026-04-10T08:00:00Z"
}

Update a template

PATCH /v1/templates/{template_id}

Updates a template. Only include the fields you want to change. The variables field is re-extracted automatically from html_body and text_body on every update.

Request body:

{
  "name": "Welcome email v2",
  "html_body": "<h1>Welcome, {{name}}!</h1><p>Your account at {{company}} is ready.</p>"
}

Field	Type	Required	Description
`name`	string	No	New name for the template.
`subject`	string	No	New subject line.
`html_body`	string	No	New HTML body.
`text_body`	string	No	New plain-text body.
`blocks_json`	object	No	New block data from the drag-and-drop editor.

cURL

curl -X PATCH https://govconnect.ke/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome email v2",
    "html_body": "<h1>Welcome, {{name}}!</h1><p>Your account at {{company}} is ready.</p>"
  }'

Python

import requests
 
response = requests.patch(
    "https://govconnect.ke/v1/templates/tmpl_abc123",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
    json={
        "name": "Welcome email v2",
        "html_body": "<h1>Welcome, {{name}}!</h1><p>Your account at {{company}} is ready.</p>"
    }
)
 
print(response.json())

Node.js

const response = await fetch(
  "https://govconnect.ke/v1/templates/tmpl_abc123",
  {
    method: "PATCH",
    headers: {
      "Authorization": "Bearer tfm_k_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Welcome email v2",
      html_body: "<h1>Welcome, {{name}}!</h1><p>Your account at {{company}} is ready.</p>",
    }),
  }
);
 
const data = await response.json();
console.log(data);

Delete a template

DELETE /v1/templates/{template_id}

Permanently deletes a template.

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

Response (204 No Content):

No response body.

Python

import requests
 
response = requests.delete(
    "https://govconnect.ke/v1/templates/tmpl_abc123",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"}
)
 
assert response.status_code == 204

Node.js

const response = await fetch(
  "https://govconnect.ke/v1/templates/tmpl_abc123",
  {
    method: "DELETE",
    headers: { "Authorization": "Bearer tfm_k_YOUR_API_KEY" },
  }
);
 
console.log(response.status); // 204

Deleting a template is permanent. Any automations referencing this template will need to be updated to use a different template.

Duplicate a template

POST /v1/templates/{template_id}/duplicate

Creates a copy of an existing template. The new template's name is set to the original name with " (copy)" appended.

curl -X POST https://govconnect.ke/v1/templates/tmpl_abc123/duplicate \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Response (201 Created):

{
  "id": "tmpl_ghi789",
  "name": "Welcome email (copy)",
  "subject": "Welcome to {{company}}, {{name}}!",
  "html_body": "<h1>Hello {{name}}</h1><p>Welcome to {{company}}. We are glad to have you.</p>",
  "text_body": "Hello {{name}}, welcome to {{company}}. We are glad to have you.",
  "blocks_json": null,
  "variables": ["name", "company"],
  "created_at": "2026-04-10T12:00:00Z",
  "updated_at": "2026-04-10T12:00:00Z"
}

Python

import requests
 
response = requests.post(
    "https://govconnect.ke/v1/templates/tmpl_abc123/duplicate",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"}
)
 
copy = response.json()
print(f"Copy ID: {copy['id']}")
print(f"Copy name: {copy['name']}")

Node.js

const response = await fetch(
  "https://govconnect.ke/v1/templates/tmpl_abc123/duplicate",
  {
    method: "POST",
    headers: { "Authorization": "Bearer tfm_k_YOUR_API_KEY" },
  }
);
 
const copy = await response.json();
console.log(`Copy ID: ${copy.id}`);
console.log(`Copy name: ${copy.name}`);

Errors

Status	Description
`401 Unauthorized`	Missing or invalid authentication.
`403 Forbidden`	Templates require the Starter plan or above, or the plan template limit was reached.
`404 Not Found`	The template ID does not exist or is not visible to your workspace.
`422 Unprocessable Entity`	Request body validation failed.

Templates API

On this page