SDKs and Libraries

Official Taifa Mail client libraries for nine languages, all covering the same API surface.

Taifa Mail ships official, open-source client libraries for nine languages. Every SDK wraps the same REST API and exposes the same resources (emails, domains, contacts, suppressions, templates, and webhooks), so the concepts you learn in one carry over to the rest. Each one handles authentication, JSON encoding, retries on 429 and 5xx, and maps API errors to a typed TaifaMailError you can catch.

All libraries are MIT licensed.

Install

Language	Install	Package	Registry
TypeScript / JavaScript	`npm install @taifamail/sdk`	`@taifamail/sdk`	npm
Python	`pip install taifa-mail`	`taifa-mail`	PyPI
Go	`go get github.com/GovConnectKenya/taifa-mail-go`	`taifa-mail-go`	Go modules
PHP	`composer require taifamail/sdk`	`taifamail/sdk`	Packagist
Ruby	`gem install taifa-mail`	`taifa-mail`	RubyGems
Rust	`cargo add taifa-mail`	`taifa-mail`	crates.io
Java	`implementation("ke.govconnect:taifa-mail-sdk:0.1.0")`	`ke.govconnect:taifa-mail-sdk`	Maven Central
.NET (C#)	`dotnet add package TaifaMail.Sdk`	`TaifaMail.Sdk`	NuGet
Swift	SwiftPM (see the Swift guide)	`TaifaMail`	SwiftPM

Get an API key from the dashboard at govconnect.ke under Settings -> API Keys. Keys start with tfm_k_ and are passed as a bearer token, which every SDK does for you.

Send your first email

The same call in every language. The sender must be a registered sender address on a verified domain.

import { Taifa Mail } from '@taifamail/sdk';
 
const taifamail = new TaifaMail({ apiKey: process.env.TAIFA_MAIL_API_KEY! });
 
const { id } = await taifamail.emails.send({
  from: 'hello@yourdomain.com',
  to: 'customer@example.com',
  subject: 'Your receipt',
  html: '<p>Thanks for your order.</p>',
});
 
console.log(id);

What every SDK gives you

Typed client built from one API key, with sensible defaults (base URL https://govconnect.ke, 3 retries, 30s timeout) you can override.
All six core resources: emails, domains, contacts, suppressions, templates, webhooks.
Automatic retries on 429 and 5xx with backoff that honours Retry-After. 4xx responses are never retried.
Typed errors: failures raise an TaifaMailError carrying the HTTP status, an optional machine-readable code, and a message.
Address shorthand: anywhere a sender or recipient is expected, a bare string like "hello@yourdomain.com" works, or pass a name with it.

Conventions

A few rules hold across the whole API and every SDK:

Pagination is zero-based: page=0 is the first page.
List endpoints return a plain array; paginated endpoints (suppressions, webhook deliveries) return an envelope with items, total, page, and limit.
The sender field is sent on the wire as from_, but every SDK exposes a clean from and maps it for you.

Next steps

Pick your language above for a full guide with every resource and method.
Browse the API reference for the raw HTTP endpoints behind each SDK call.
Read the Quickstart to set up a domain and sender before your first send.