Sender Addresses API

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

All endpoints require authentication via API Key or JWT cookie.

Create a sender address

POST /v1/sender-addresses/

Registers a new sender address on a verified domain. You can then use this address as the from_ field when sending emails.

Request body:

{
  "email": "hello@yourdomain.com",
  "display_name": "Your Company",
  "domain_id": "dom_abc123"
}

Field	Type	Required	Description
`email`	string (email)	Yes	The email address to send from. Must be on a verified domain.
`display_name`	string	No	The display name shown to recipients (e.g. "Your Company").
`domain_id`	UUID	Yes	The ID of the verified domain this address belongs to.

The domain associated with domain_id must have a verified status. Use the Domains API to verify your domain first.

Response (201 Created):

{
  "id": "sa_abc123",
  "email": "hello@yourdomain.com",
  "display_name": "Your Company",
  "domain_id": "dom_abc123",
  "is_active": true,
  "created_at": "2026-04-10T08:00:00Z"
}

cURL

curl -X POST https://govconnect.ke/v1/sender-addresses/ \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "hello@yourdomain.com",
    "display_name": "Your Company",
    "domain_id": "dom_abc123"
  }'

Python

import requests
 
response = requests.post(
    "https://govconnect.ke/v1/sender-addresses/",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
    json={
        "email": "hello@yourdomain.com",
        "display_name": "Your Company",
        "domain_id": "dom_abc123"
    }
)
 
print(response.json())

Node.js

const response = await fetch("https://govconnect.ke/v1/sender-addresses/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tfm_k_YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "hello@yourdomain.com",
    display_name: "Your Company",
    domain_id: "dom_abc123",
  }),
});
 
const data = await response.json();
console.log(data);

List sender addresses

GET /v1/sender-addresses/

Returns all sender addresses registered to your account.

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

Response:

[
  {
    "id": "sa_abc123",
    "email": "hello@yourdomain.com",
    "display_name": "Your Company",
    "domain_id": "dom_abc123",
    "is_active": true,
    "created_at": "2026-04-10T08:00:00Z"
  },
  {
    "id": "sa_def456",
    "email": "support@yourdomain.com",
    "display_name": "Support Team",
    "domain_id": "dom_abc123",
    "is_active": true,
    "created_at": "2026-04-09T14:00:00Z"
  }
]

Only active sender addresses are returned.

Python

import requests
 
response = requests.get(
    "https://govconnect.ke/v1/sender-addresses/",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"}
)
 
for addr in response.json():
    print(f"{addr['display_name']} <{addr['email']}>")

Node.js

const response = await fetch("https://govconnect.ke/v1/sender-addresses/", {
  headers: { "Authorization": "Bearer tfm_k_YOUR_API_KEY" },
});
 
const data = await response.json();
data.forEach((addr) => {
  console.log(`${addr.display_name} <${addr.email}>`);
});

Check a sender address

GET /v1/sender-addresses/check/{email}

Checks whether a specific email address exists as a sender address and whether it can currently send emails. This is useful for validating a sender address before attempting to send.

Parameter	Type	Description
`email`	string (path)	The email address to check.

curl https://govconnect.ke/v1/sender-addresses/check/hello@yourdomain.com \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Response:

{
  "exists": true,
  "active": true,
  "domain_verified": true,
  "email": "hello@yourdomain.com",
  "display_name": "Your Company",
  "domain": "yourdomain.com",
  "can_send": true
}

The can_send field is true only when all of the following are met:

The sender address exists (exists: true)
The sender address is active (active: true)
The associated domain is verified (domain_verified: true)

Response when address does not exist:

{
  "exists": false,
  "active": false,
  "domain_verified": false,
  "email": "unknown@yourdomain.com",
  "display_name": null,
  "domain": "yourdomain.com",
  "can_send": false
}

Python

import requests
 
response = requests.get(
    "https://govconnect.ke/v1/sender-addresses/check/hello@yourdomain.com",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"}
)
 
result = response.json()
if result["can_send"]:
    print("Ready to send")
else:
    print("Cannot send from this address")

Node.js

const email = "hello@yourdomain.com";
const response = await fetch(
  `https://govconnect.ke/v1/sender-addresses/check/${email}`,
  { headers: { "Authorization": "Bearer tfm_k_YOUR_API_KEY" } }
);
 
const result = await response.json();
if (result.can_send) {
  console.log("Ready to send");
} else {
  console.log("Cannot send from this address");
}

Delete a sender address

DELETE /v1/sender-addresses/{address_id}

Permanently removes a sender address. Emails can no longer be sent from this address.

Parameter	Type	Description
`address_id`	UUID (path)	The ID of the sender address to delete.

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

Node.js

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

Deleting a sender address is permanent. Any scheduled emails or automations using this address will fail if they have not yet been sent. Update your sending configuration before deleting an address.

Errors

Status	Description
`400 Bad Request`	The associated domain is not verified, or the email's domain does not match the domain record.
`401 Unauthorized`	Missing or invalid authentication.
`403 Forbidden`	You have reached the sender address limit for your plan.
`404 Not Found`	The specified domain or sender address ID does not exist or does not belong to your account.
`409 Conflict`	A sender address with this email already exists.

Sender Addresses API

On this page