Inbound & Inbox API

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

Mail intake itself is handled by Taifa Mail's mail servers (Postfix/Dovecot), not by a public "upload message" endpoint. For a domain to receive mail, its MX record must point to mx1.govconnect.ke.

Webmail inbox API

Hosted mailboxes are accessed at /v1/inbox/{mailbox_id}/…. Every endpoint authorises the caller against that mailbox first:

• User session (OAuth JWT or API key): the caller must belong to the mailbox's organisation and be assigned to the mailbox, or be an org owner/admin (audit-logged as opened as).
• Mailbox session (mailbox_access token from mail.govconnect.ke login): may act on only that mailbox.

All endpoints require authentication via API key or JWT cookie.

List folders

GET /v1/inbox/{mailbox_id}/folders

Returns IMAP folders with unseen/total counts.

List messages

GET /v1/inbox/{mailbox_id}/messages

Query parameters:

Full-text search is a separate endpoint:

GET /v1/inbox/{mailbox_id}/search

Query parameters: q (string, required), plus folder, limit, and offset as above.

Get a message

GET /v1/inbox/{mailbox_id}/messages/{uid}

Returns the full parsed message for the given IMAP UID in the message's folder.

Message actions

POST /v1/inbox/{mailbox_id}/messages/{uid}/flags   # seen, flagged, answered
POST /v1/inbox/{mailbox_id}/messages/{uid}/move      # move to another folder
POST /v1/inbox/{mailbox_id}/messages/{uid}/spam      # move to Spam
POST /v1/inbox/{mailbox_id}/messages/{uid}/not-spam    # restore from Spam
DELETE /v1/inbox/{mailbox_id}/messages/{uid}         # move to Trash / expunge

Send mail

POST /v1/inbox/{mailbox_id}/send

Request body (JSON):

{
  "to": ["citizen@example.com"],
  "cc": [],
  "bcc": [],
  "subject": "Re: Your inquiry",
  "text": "Thank you for writing.",
  "html": null,
  "file_ids": []
}

Provide at least one of text or html. Plain text is auto-wrapped in HTML when only text is supplied.

Attachments

GET /v1/inbox/{mailbox_id}/attachments/{uid}/{part_id}

Returns raw attachment bytes.

Labels, scheduled send, quota

GET  /v1/inbox/{mailbox_id}/labels
POST /v1/inbox/{mailbox_id}/labels
GET  /v1/inbox/{mailbox_id}/scheduled
GET  /v1/inbox/{mailbox_id}/quota
GET  /v1/inbox/{mailbox_id}/storage-sections

See the webmail UI at mail.govconnect.ke for the full feature set these endpoints back.

Admin inbound log

ICT administrators can inspect how an inbound message was routed (received → parsed → forwarding rules) from the unified email log.

GET /v1/emails/inbound/{message_id}

Requires the domains:view permission. Returns metadata, a text preview, attachment count, and an events array (the message's routing log). This is read-only; it does not replace webmail for reading officer mailboxes.

Example response (abbreviated):

{
  "id": "8f1d2c3a-0000-0000-0000-000000000001",
  "direction": "inbound",
  "from_address": "sender@external.com",
  "from_name": "Jane Doe",
  "recipient": "info@health.go.ke",
  "subject": "Partnership inquiry",
  "received_at": "2026-04-06T14:30:00Z",
  "authentication": {},
  "attachment_count": 0,
  "text_preview": "Hi there...",
  "events": []
}

Inbound messages also appear in the merged Developer → Email Logs list when you filter for received mail.

Errors