Inbound API

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

All endpoints require authentication via API Key or JWT cookie.

These endpoints read and manage messages captured by the Inbox. For a domain to receive mail, its MX record must point to mx1.govconnect.ke.

Mail intake itself is handled by Taifa Mail's mail servers, not by an API call. There is no public "create inbound message" endpoint.

List inbox messages

GET /v1/inbound

Query parameters:

Parameter	Type	Default	Description
`view`	string	`inbox`	One of `inbox`, `archived`, `snoozed`.
`page`	integer	0	Page number (zero-indexed).
`limit`	integer	50	Results per page (1-200).

curl "https://govconnect.ke/v1/inbound?view=inbox" \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Response:

{
  "items": [
    {
      "id": "inb_abc123",
      "recipient": "hello@yourdomain.com",
      "from_address": "sender@external.com",
      "from_name": "Jane Doe",
      "subject": "Partnership inquiry",
      "received_at": "2026-04-06T14:30:00Z",
      "authentication": {},
      "has_attachments": false,
      "archived_at": null,
      "snooze_until": null,
      "read_at": null
    }
  ],
  "page": 0,
  "limit": 50
}

Get a message

GET /v1/inbound/{message_id}

Returns the full message: headers, parsed text and HTML bodies, authentication results, spam score, attachment list, and routing log.

Response:

{
  "id": "inb_abc123",
  "type": "email.inbound",
  "received_at": "2026-04-06T14:30:00Z",
  "recipient": "hello@yourdomain.com",
  "from": { "address": "sender@external.com", "name": "Jane Doe" },
  "reply_to": null,
  "cc": [],
  "bcc": [],
  "subject": "Partnership inquiry",
  "text": "Hi there...",
  "html": "<p>Hi there...</p>",
  "authentication": {},
  "spam_score": 0.1,
  "message_id": "<abc123@external.com>",
  "in_reply_to": null,
  "headers": {},
  "size_bytes": 4521,
  "routing_log": [],
  "attachments": [
    {
      "filename": "deck.pdf",
      "content_type": "application/pdf",
      "size_bytes": 20481,
      "sha256": "...",
      "url": "/v1/inbound/inb_abc123/attachments/0"
    }
  ]
}

Manage a message

POST /v1/inbound/{message_id}/read
POST /v1/inbound/{message_id}/archive
POST /v1/inbound/{message_id}/unarchive
POST /v1/inbound/{message_id}/unsnooze

read marks the message read (idempotent, sets read_at once).
archive hides the message from the inbox; unarchive returns it.
unsnooze clears a snooze and returns the message to the inbox now.

Each returns a small JSON object with the affected timestamp, for example:

curl -X POST https://govconnect.ke/v1/inbound/inb_abc123/archive \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

{ "id": "inb_abc123", "archived_at": "2026-04-06T15:00:00Z" }

Snooze a message

POST /v1/inbound/{message_id}/snooze

Request body:

{ "until": "2026-04-08T09:00:00Z" }

The until field is required and must be an ISO 8601 datetime in the future. The message leaves the inbox and returns automatically once that time passes.

Replay a message

POST /v1/inbound/{message_id}/replay

Re-evaluates forward routing for the stored message against your current forwarding rules. Useful after adding a rule. Returns 422 if no active forward rule matches the recipient.

{
  "replayed": true,
  "rule_id": "fwd_abc123",
  "email_destinations": ["alice@gmail.com"],
  "url_destinations": []
}

Download an attachment

GET /v1/inbound/{message_id}/attachments/{index}

Returns the raw attachment bytes with the original content type.

Errors

Status	Cause
`400 Bad Request`	Missing or invalid `until` value on snooze, or a snooze time in the past.
`401 Unauthorized`	Missing or invalid authentication.
`404 Not Found`	Message ID or attachment index does not exist.
`422 Unprocessable Entity`	Replay found no active forward rule for the recipient.