BIMI API

API reference for managing Brand Indicators for Message Identification (BIMI) logos and DNS configuration in Taifa Mail.

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

All endpoints require authentication via API Key or JWT cookie unless noted otherwise.

BIMI features require the Pro plan or above. Requests from Free or Starter accounts will receive a 403 error.

Check BIMI readiness

GET /v1/domains/{domain_id}/bimi/status

Returns the current BIMI configuration status for a domain, including whether the domain is verified, whether a logo has been uploaded, and the DNS records needed to enable BIMI.

cURL:

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

Python:

import requests
 
response = requests.get(
    "https://govconnect.ke/v1/domains/dom_abc123/bimi/status",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
)
status = response.json()
print(f"BIMI enabled: {status['bimi_enabled']}")
print(f"DNS record: {status['bimi_dns_record']}")

Node.js:

const response = await fetch(
  "https://govconnect.ke/v1/domains/dom_abc123/bimi/status",
  {
    headers: { Authorization: "Bearer tfm_k_YOUR_API_KEY" },
  }
);
const status = await response.json();
console.log(`BIMI enabled: ${status.bimi_enabled}`);
console.log(`DNS record: ${status.bimi_dns_record}`);

Response:

{
  "domain": "yourdomain.com",
  "domain_verified": true,
  "bimi_svg_url": "https://govconnect.ke/v1/bimi/dom_abc123/logo.svg",
  "bimi_vmc_url": null,
  "bimi_enabled": false,
  "bimi_dns_record": "v=BIMI1; l=https://govconnect.ke/v1/bimi/dom_abc123/logo.svg",
  "bimi_dns_host": "default._bimi.yourdomain.com",
  "dmarc_upgrade_record": "v=DMARC1; p=quarantine; rua=mailto:dmarc@mail.govconnect.ke"
}

Field	Type	Description
`domain`	string	The domain name.
`domain_verified`	boolean	Whether the domain has passed DNS verification.
`bimi_svg_url`	string or null	URL of the uploaded BIMI logo, or `null` if no logo is uploaded.
`bimi_vmc_url`	string or null	URL of the Verified Mark Certificate, or `null` if not configured.
`bimi_enabled`	boolean	Whether BIMI is currently enabled for this domain.
`bimi_dns_record`	string	The TXT record value to add at `bimi_dns_host`.
`bimi_dns_host`	string	The DNS hostname where the BIMI TXT record should be published.
`dmarc_upgrade_record`	string or null	A suggested DMARC record if your current policy is `none`. BIMI requires `quarantine` or `reject`. `null` if your DMARC policy already meets the requirement.

Upload BIMI logo

POST /v1/domains/{domain_id}/bimi/logo

Upload an SVG logo for BIMI.

Request: multipart/form-data with a file field containing the SVG.

File requirements enforced by the API:

The filename must end in .svg
The file must contain an <svg element
The file size must not exceed 100 KB

For inbox providers to render your logo, the SVG should also conform to the BIMI specification's SVG Tiny Portable/Secure (P/S) profile and be square. The API does not enforce these, so validate them with a BIMI tool before publishing.

cURL:

curl -X POST https://govconnect.ke/v1/domains/dom_abc123/bimi/logo \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -F "file=@logo.svg"

Python:

import requests
 
with open("logo.svg", "rb") as f:
    response = requests.post(
        "https://govconnect.ke/v1/domains/dom_abc123/bimi/logo",
        headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
        files={"file": ("logo.svg", f, "image/svg+xml")},
    )
print(response.json())

Node.js:

const fs = require("fs");
const FormData = require("form-data");
 
const form = new FormData();
form.append("file", fs.createReadStream("logo.svg"));
 
const response = await fetch(
  "https://govconnect.ke/v1/domains/dom_abc123/bimi/logo",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer tfm_k_YOUR_API_KEY",
      ...form.getHeaders(),
    },
    body: form,
  }
);
const data = await response.json();

Response:

{
  "url": "https://govconnect.ke/v1/bimi/dom_abc123/logo.svg",
  "size": 8432,
  "bimi_dns_record": "v=BIMI1; l=https://govconnect.ke/v1/bimi/dom_abc123/logo.svg",
  "bimi_dns_host": "default._bimi.yourdomain.com"
}

Field	Type	Description
`url`	string	The public URL where the logo is served.
`size`	integer	File size in bytes.
`bimi_dns_record`	string	The TXT record value to publish at `bimi_dns_host`.
`bimi_dns_host`	string	The DNS hostname for the BIMI TXT record.

After uploading the logo, add the BIMI TXT record to your DNS, then call the enable endpoint. You can verify the DNS record is live using dig TXT default._bimi.yourdomain.com.

Enable BIMI

POST /v1/domains/{domain_id}/bimi/enable

Enable BIMI for a domain. This endpoint validates that all prerequisites are met before enabling.

Prerequisites:

The domain must be verified in Taifa Mail.
A BIMI SVG logo must be uploaded.
The domain's DMARC policy must be set to quarantine or reject (not none).

cURL:

curl -X POST https://govconnect.ke/v1/domains/dom_abc123/bimi/enable \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Python:

import requests
 
response = requests.post(
    "https://govconnect.ke/v1/domains/dom_abc123/bimi/enable",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
)
print(response.json())

Node.js:

const response = await fetch(
  "https://govconnect.ke/v1/domains/dom_abc123/bimi/enable",
  {
    method: "POST",
    headers: { Authorization: "Bearer tfm_k_YOUR_API_KEY" },
  }
);
const data = await response.json();

Response:

{
  "detail": "BIMI enabled",
  "bimi_dns_record": "v=BIMI1; l=https://govconnect.ke/v1/bimi/dom_abc123/logo.svg"
}

Field	Type	Description
`detail`	string	Confirmation message.
`bimi_dns_record`	string	The BIMI TXT record to publish in DNS (if not already published).

Serve BIMI logo (public)

GET /v1/bimi/{domain_id}/logo.svg

Serves the uploaded BIMI SVG logo for a domain. This is a public endpoint and does not require authentication. Mail clients fetch this URL when rendering BIMI logos in the inbox.

The response is cached with a 24-hour Cache-Control header.

cURL:

curl https://govconnect.ke/v1/bimi/dom_abc123/logo.svg -o logo.svg

Python:

import requests
 
response = requests.get(
    "https://govconnect.ke/v1/bimi/dom_abc123/logo.svg"
)
with open("logo.svg", "wb") as f:
    f.write(response.content)

Node.js:

const response = await fetch(
  "https://govconnect.ke/v1/bimi/dom_abc123/logo.svg"
);
const svg = await response.text();

Response headers:

Content-Type: image/svg+xml
Cache-Control: public, max-age=86400
Access-Control-Allow-Origin: *

Response body: The raw SVG file content.

This endpoint returns 404 Not Found if no logo has been uploaded for the domain, or if the domain does not exist.

Errors

Status	Cause
`400 Bad Request`	Uploaded file is not an `.svg`, does not contain an `<svg>` element, or exceeds 100 KB. Also returned by the enable endpoint when no logo is uploaded or the DMARC policy is not `quarantine` or `reject`.
`401 Unauthorized`	Missing or invalid authentication token (does not apply to the public logo endpoint).
`403 Forbidden`	Account is on the Free or Starter plan. BIMI requires Pro or above.
`404 Not Found`	Domain ID does not exist, or no logo has been uploaded (logo endpoint only).

BIMI API

Check BIMI readiness

Upload BIMI logo

Enable BIMI

Serve BIMI logo (public)

Errors

On this page