Email Verification API

API reference for verifying email addresses using syntax checks, MX lookups, and SMTP validation in Taifa Mail.

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

All endpoints require authentication via API Key or JWT cookie.

Verify an email address

POST /v1/verify

Verify whether an email address is deliverable. The verification process checks syntax, resolves MX records, and performs an SMTP RCPT TO probe against the destination mail server.

The verification flow runs three checks in order: a syntax check, an MX record lookup, and an SMTP RCPT TO probe. It never sends an email.

Request body:

{
  "email": "jane@example.com"
}

Field	Type	Required	Description
`email`	string	Yes	The email address to verify.

cURL:

curl -X POST https://govconnect.ke/v1/verify \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com"}'

Python:

import requests
 
response = requests.post(
    "https://govconnect.ke/v1/verify",
    headers={
        "Authorization": "Bearer tfm_k_YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"email": "jane@example.com"},
)
result = response.json()
print(f"{result['email']}: {result['result']} - {result['reason']}")

Node.js:

const response = await fetch("https://govconnect.ke/v1/verify", {
  method: "POST",
  headers: {
    Authorization: "Bearer tfm_k_YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "jane@example.com" }),
});
const result = await response.json();
console.log(`${result.email}: ${result.result} - ${result.reason}`);

Response:

{
  "email": "jane@example.com",
  "result": "valid",
  "reason": "Email address exists and accepts mail",
  "mx_found": true,
  "mx_host": "aspmx.l.google.com"
}

Field	Type	Description
`email`	string	The email address that was checked.
`result`	string	Verification result. One of: `valid`, `invalid`, `risky`, `unknown`.
`reason`	string	Human-readable explanation of the result.
`mx_found`	boolean	Whether MX records were found for the domain.
`mx_host`	string or null	The primary MX host, or `null` if no MX records exist.

Result values

Result	Meaning
`valid`	The mailbox exists and accepts mail. Safe to send.
`invalid`	The syntax is malformed, the domain has no MX records, or the mail server rejected the address. Do not send.
`risky`	The mail server returned a temporary error (greylisting or similar). The address may or may not exist.
`unknown`	Verification could not be completed. The mail server may be unreachable, timing out, or blocking SMTP probes.

Example responses

Valid email:

{
  "email": "jane@example.com",
  "result": "valid",
  "reason": "Email address exists and accepts mail",
  "mx_found": true,
  "mx_host": "aspmx.l.google.com"
}

Invalid email (mailbox rejected):

{
  "email": "nonexistent@example.com",
  "result": "invalid",
  "reason": "Email address rejected by mail server",
  "mx_found": true,
  "mx_host": "aspmx.l.google.com"
}

Invalid email (bad domain):

{
  "email": "user@notarealdomain.xyz",
  "result": "invalid",
  "reason": "No MX records found for notarealdomain.xyz",
  "mx_found": false,
  "mx_host": null
}

Risky email (temporary error):

{
  "email": "anything@greylisted-domain.com",
  "result": "risky",
  "reason": "Mail server responded with temporary error - address may or may not exist",
  "mx_found": true,
  "mx_host": "mail.greylisted-domain.com"
}

Unknown (no clear response):

{
  "email": "user@slow-server.com",
  "result": "unknown",
  "reason": "Could not determine validity - mail server did not provide a clear response",
  "mx_found": true,
  "mx_host": "mail.slow-server.com"
}

Best practices

Verify addresses at the point of collection (signup forms, import flows) to prevent bounces.
Treat invalid results as hard failures and do not attempt delivery.
Treat risky results with caution. Consider sending but monitoring bounce rates.
Cache verification results for 24-48 hours. Email addresses do not change status frequently.
Do not use verification to enumerate mailboxes on a domain.

Errors

Status	Cause
`401 Unauthorized`	Missing or invalid authentication token.
`422 Unprocessable Entity`	Request body validation failed (missing `email` field).