Domains API

API reference for managing sending domains, DNS verification, and domain health in Taifa Mail.

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

All endpoints require authentication via API Key or JWT cookie. API keys are passed as Authorization: Bearer tfm_k_....

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

List domains

GET /v1/domains/

Returns all domains visible to the authenticated account.

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

Response:

[
  {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "name": "notifications.yourapp.com",
    "status": "verified",
    "created_at": "2026-03-15T08:00:00Z",
    "platform_warning": null
  }
]

Domain statuses

Status	Meaning
`pending`	Domain added but DNS records not yet verified.
`verified`	All required DNS records are correctly configured.
`failed`	Verification ran but one or more records are missing or incorrect.

Create a domain

POST /v1/domains/

Registers a new sending domain. Taifa Mail generates DKIM keys and the DNS records you must publish.

Request body:

{ "name": "notifications.yourapp.com" }

Field	Type	Required	Description
`name`	string	Yes	The domain name. A pasted URL has its scheme, path, and port stripped automatically.

curl -X POST https://govconnect.ke/v1/domains/ \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "notifications.yourapp.com" }'

Response (201 Created):

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "name": "notifications.yourapp.com",
  "status": "pending",
  "dkim_selector": "taifamail",
  "verified_at": null,
  "created_at": "2026-04-06T10:00:00Z",
  "platform_warning": null,
  "dns_records": [
    {
      "id": "d1e2f3a4-...",
      "record_type": "TXT",
      "purpose": "spf",
      "host": "notifications.yourapp.com",
      "value": "v=spf1 include:mail.govconnect.ke ~all",
      "is_verified": false,
      "last_checked_at": null
    },
    {
      "id": "d2e3f4a5-...",
      "record_type": "TXT",
      "purpose": "dkim",
      "host": "taifa._domainkey.notifications.yourapp.com",
      "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBA...",
      "is_verified": false,
      "last_checked_at": null
    }
  ]
}

Each DNS record carries a purpose (verification, spf, dkim, dmarc, return_path) and an is_verified flag.

DNS propagation can take up to 48 hours, though most records propagate within minutes. You can trigger verification multiple times while waiting.

Check domain availability

GET /v1/domains/check-availability

Checks whether a domain is free to claim on this account by inspecting public taifa-verify TXT records.

Query parameters:

Parameter	Type	Required	Description
`name`	string	Yes	The domain name to check.

Response:

{
  "available": true,
  "reason": null,
  "detail": null,
  "stale_tokens": null
}

When available is false, reason is one of already_on_this_account, in_use_by_other_account, or stale_records_detected.

Check a domain by name

GET /v1/domains/check/{domain_name}

Quick lookup of whether a domain is registered and verified on this account.

Response:

{
  "exists": true,
  "verified": true,
  "status": "verified",
  "domain": "notifications.yourapp.com",
  "id": "a1b2c3d4-..."
}

If the domain is not registered, the response is { "exists": false, "verified": false, "domain": "..." }.

Get domain details

GET /v1/domains/{domain_id}

Returns domain details including all DNS records and their verification state. The response shape matches the create response.

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

Verify a domain

POST /v1/domains/{domain_id}/verify

Triggers DNS record verification. Taifa Mail checks all required records and updates each is_verified flag. The domain status becomes verified only when all records pass.

curl -X POST https://govconnect.ke/v1/domains/a1b2c3d4-.../verify \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Response: the full domain object (same shape as create), with updated status and per-record is_verified flags.

If verification fails, inspect the is_verified field on each dns_records entry to find the record that needs attention. Common issues include trailing dots, extra spaces, or conflicting existing records.

Rotate DKIM keys

POST /v1/domains/{domain_id}/rotate-dkim

Generates a new DKIM key pair and returns the new DNS record value to publish.

curl -X POST https://govconnect.ke/v1/domains/a1b2c3d4-.../rotate-dkim \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Response:

{
  "dkim_record_host": "taifa._domainkey.notifications.yourapp.com",
  "dkim_record_value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3...",
  "domain": { "id": "a1b2c3d4-...", "name": "notifications.yourapp.com", "status": "verified" }
}

Diagnose DNS issues

GET /v1/domains/{domain_id}/diagnose

Detects DNS problems and returns actionable diagnostics plus a health score.

Response:

{
  "domain": "notifications.yourapp.com",
  "issues": ["DKIM record not found"],
  "health_score": 70
}

Domain health

GET /v1/domains/{domain_id}/health

Returns a consolidated verdict for each DNS check (DKIM, SPF, DMARC, bounce routing, MX) with a plain-language recommendation.

Response:

{
  "domain": "notifications.yourapp.com",
  "checks": [
    {
      "key": "dkim",
      "label": "DKIM signature",
      "status": "ok",
      "detail": "Your mail is cryptographically signed.",
      "recommendation": null,
      "record": null
    }
  ],
  "summary": { "ok": 3, "warn": 1, "error": 1, "info": 0 }
}

Each check status is one of ok, warn, error, or info.

MX status

GET /v1/domains/{domain_id}/mx-status

Checks the domain's MX records, used for inbound email forwarding.

Response:

{
  "domain": "notifications.yourapp.com",
  "mx_records": ["10 govconnect.ke"],
  "has_taifa_mx": true,
  "current_provider": "Taifa Mail"
}

Detect DNS provider

GET /v1/domains/{domain_id}/ns-provider

Detects the domain's DNS provider via an NS record lookup.

Response:

{ "domain": "notifications.yourapp.com", "provider": "Cloudflare" }

Domain Connect URL

GET /v1/domains/{domain_id}/domain-connect

Returns a signed Domain Connect apply URL. Redirect the user to this URL; their registrar shows a summary of the DNS records to be added and an Authorize button.

Response:

{ "url": "https://domainconnect.example-registrar.com/v2/..." }

Returns 400 if the domain has no DNS records, or 503 if Domain Connect is not configured.

Delete a domain

DELETE /v1/domains/{domain_id}

Removes a domain from the account. Returns 204 No Content with no body.

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

Deleting a domain immediately prevents sending from any address on that domain. This action cannot be undone.

Transfer a domain

To move a domain to another account or workspace instead of deleting it, use the Domain Transfers API. A transfer carries the domain's senders, forwards and inbox routing to the new owner after a two-sided handshake and a 24-hour safety window.

Domains API

On this page