SMTP Credentials API

API reference for creating and managing SMTP credentials for relay-based email sending in Taifa Mail.

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

All endpoints require authentication via API Key or JWT cookie.

Create SMTP credentials

POST /v1/smtp-credentials/

Creates a new set of SMTP credentials for a verified domain. The password is returned only once in the response. Store it securely.

Request body:

{
  "domain_id": "dom_abc123"
}

Field	Type	Required	Description
`domain_id`	UUID	Yes	The ID of a verified domain to associate these credentials with.

The domain must have a verified status before you can create SMTP credentials. Use the Domains API to register and verify your domain first.

Response (201 Created):

{
  "id": "cred_abc123",
  "username": "a1b2c3d4@yourdomain.com",
  "password": "xYz789AbC012DeF345GhI678JkL901",
  "smtp_host": "mail.govconnect.ke",
  "smtp_port": 587,
  "created_at": "2026-04-10T08:00:00Z"
}

The username is derived automatically as the first 8 characters of your account ID followed by @ and the domain name. There is one SMTP credential per domain.

The password field is only returned when the credential is created. It cannot be retrieved again. If you lose it, deactivate the credential and create a new one.

SMTP connection details

Setting	Value
Host	`mail.govconnect.ke`
Port	`587`
Encryption	STARTTLS
Authentication	Username + password from the create response

cURL

curl -X POST https://govconnect.ke/v1/smtp-credentials/ \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_id": "dom_abc123"
  }'

Python

import requests
 
response = requests.post(
    "https://govconnect.ke/v1/smtp-credentials/",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
    json={"domain_id": "dom_abc123"}
)
 
cred = response.json()
print(f"Host: {cred['smtp_host']}")
print(f"Port: {cred['smtp_port']}")
print(f"Username: {cred['username']}")
print(f"Password: {cred['password']}")  # Store securely

Node.js

const response = await fetch("https://govconnect.ke/v1/smtp-credentials/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tfm_k_YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ domain_id: "dom_abc123" }),
});
 
const cred = await response.json();
console.log(`Host: ${cred.smtp_host}`);
console.log(`Port: ${cred.smtp_port}`);
console.log(`Username: ${cred.username}`);
console.log(`Password: ${cred.password}`); // Store securely

List SMTP credentials

GET /v1/smtp-credentials/

Returns an array of active SMTP credentials for the authenticated account. Passwords are never returned in list responses.

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

Response:

[
  {
    "id": "cred_abc123",
    "username": "a1b2c3d4@yourdomain.com",
    "domain_id": "dom_abc123",
    "is_active": true,
    "created_at": "2026-04-10T08:00:00Z"
  },
  {
    "id": "cred_def456",
    "username": "a1b2c3d4@another.com",
    "domain_id": "dom_def456",
    "is_active": true,
    "created_at": "2026-04-08T12:00:00Z"
  }
]

Python

import requests
 
response = requests.get(
    "https://govconnect.ke/v1/smtp-credentials/",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"}
)
 
for cred in response.json():
    print(f"{cred['username']} - active: {cred['is_active']}")

Node.js

const response = await fetch("https://govconnect.ke/v1/smtp-credentials/", {
  headers: { "Authorization": "Bearer tfm_k_YOUR_API_KEY" },
});
 
const data = await response.json();
data.forEach((cred) => {
  console.log(`${cred.username} - active: ${cred.is_active}`);
});

Deactivate SMTP credentials

DELETE /v1/smtp-credentials/{credential_id}

Permanently deactivates an SMTP credential. Any SMTP connections using this credential will be rejected after deactivation.

Parameter	Type	Description
`credential_id`	UUID (path)	The ID of the SMTP credential to deactivate.

curl -X DELETE https://govconnect.ke/v1/smtp-credentials/cred_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/smtp-credentials/cred_abc123",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"}
)
 
assert response.status_code == 204

Node.js

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

Deactivating credentials is irreversible. Any application or mail client using these credentials will lose the ability to send email immediately. Deactivated credentials still appear in the list response with is_active: false.

Using SMTP credentials

Once you have your credentials, you can send email from any application or library that supports SMTP. Here are examples for common setups.

Python (smtplib)

import smtplib
from email.mime.text import MIMEText
 
msg = MIMEText("Hello from Taifa Mail!")
msg["Subject"] = "Test email"
msg["From"] = "hello@yourdomain.com"
msg["To"] = "recipient@example.com"
 
with smtplib.SMTP("mail.govconnect.ke", 587) as server:
    server.starttls()
    server.login("a1b2c3d4@yourdomain.com", "xYz789AbC012DeF345GhI678JkL901")
    server.send_message(msg)

Node.js (nodemailer)

import nodemailer from "nodemailer";
 
const transporter = nodemailer.createTransport({
  host: "mail.govconnect.ke",
  port: 587,
  secure: false, // STARTTLS
  auth: {
    user: "a1b2c3d4@yourdomain.com",
    pass: "xYz789AbC012DeF345GhI678JkL901",
  },
});
 
await transporter.sendMail({
  from: "hello@yourdomain.com",
  to: "recipient@example.com",
  subject: "Test email",
  text: "Hello from Taifa Mail!",
});

Errors

Status	Description
`400 Bad Request`	The specified domain has not been verified yet.
`401 Unauthorized`	Missing or invalid authentication.
`403 Forbidden`	You have reached the SMTP credential limit for your plan.
`404 Not Found`	The specified domain or credential ID does not exist or does not belong to your account.
`409 Conflict`	An active SMTP credential already exists for this domain. Delete it before creating a new one.

SMTP Credentials API

On this page