Mailboxes API

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

Mailbox management endpoints live under /v1/mailboxes. Reading and sending mail for a hosted mailbox uses the separate /v1/inbox API and webmail.

All endpoints require authentication via API Key or JWT cookie. Creating mailboxes also requires ICTA to have approved your institution's mailbox allocation.

List mailboxes

GET /v1/mailboxes

Returns all mailboxes in the active workspace. Optional domain_id query parameter filters to one domain.

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

List sendable mailboxes

GET /v1/mailboxes/sendable

Mailboxes the caller may send from (used by compose and API send flows).

List my mailboxes

GET /v1/mailboxes/mine

Mailboxes assigned to the current user (Officer role path).

Create a mailbox

POST /v1/mailboxes

Request body (JSON):

Returns a MailboxCreateResponse: the created mailbox record, a one-time app_password for webmail and IMAP (shown once), and a client_settings object with IMAP/SMTP/POP host and port. Creation fails with 403 when the org is at its ICTA allowance cap (allocation_required or allocation_exhausted).

Get a mailbox

GET /v1/mailboxes/{mailbox_id}

Storage

GET /v1/mailboxes/{mailbox_id}/storage
GET /v1/mailboxes/storage-report

Quota and usage breakdown for one mailbox or the whole org.

Credentials and client settings

GET  /v1/mailboxes/{mailbox_id}/credentials
POST /v1/mailboxes/{mailbox_id}/credentials      # mint app password
POST /v1/mailboxes/{mailbox_id}/password           # rotate primary password
GET  /v1/mailboxes/{mailbox_id}/client-settings    # IMAP/SMTP host ports for mail clients

Assignments

Officers access mailboxes through assignments:

GET  /v1/mailboxes/{mailbox_id}/assignments
POST /v1/mailboxes/{mailbox_id}/assignments
DELETE /v1/mailboxes/{mailbox_id}/assignments/{user_id}

Suspend and activate

POST /v1/mailboxes/{mailbox_id}/suspend
POST /v1/mailboxes/{mailbox_id}/activate

Suspended mailboxes cannot send or receive until reactivated.

Bulk create

POST /v1/mailboxes/bulk

Create many mailboxes on one domain in a single request (subject to allowance).

Errors