Email Events

Every email sent through Taifa Mail moves through a series of events from the moment it is queued to the moment a recipient interacts with it. Events are recorded in real time via Postfix callbacks and are available in both the dashboard and the API.

Event types

Each event has an event_type. The values you can see are:

Viewing events in the dashboard

1. Go to Email Logs in the sidebar.
2. Click any email row to open its detail view.
3. Select the Events timeline tab.

Each event shows the timestamp, event type, and any additional metadata (for example, the clicked URL or the user agent recorded on an open).

Retrieving events via API

curl https://govconnect.ke/v1/emails/{id}/events \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Each event has an id, event_type, an optional metadata object, and a created_at timestamp.

Response:

[
  {
    "id": "a1b2c3d4-0000-0000-0000-000000000001",
    "event_type": "queued",
    "metadata": null,
    "created_at": "2026-04-06T10:00:00Z"
  },
  {
    "id": "a1b2c3d4-0000-0000-0000-000000000002",
    "event_type": "sent",
    "metadata": null,
    "created_at": "2026-04-06T10:00:01Z"
  },
  {
    "id": "a1b2c3d4-0000-0000-0000-000000000003",
    "event_type": "delivered",
    "metadata": null,
    "created_at": "2026-04-06T10:00:03Z"
  },
  {
    "id": "a1b2c3d4-0000-0000-0000-000000000004",
    "event_type": "open",
    "metadata": {
      "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)"
    },
    "created_at": "2026-04-06T10:02:15Z"
  }
]

The metadata object varies by event type. An open event carries the requesting user agent under ua. A click event carries the destination url and ua.

How tracking works

Open tracking embeds a transparent 1x1 pixel image in the HTML body of your email. When the recipient's email client loads the image, Taifa Mail records an open event.

Click tracking rewrites each link in your HTML email to route through an Taifa Mail redirect URL. When the recipient clicks a link, Taifa Mail records a click event and redirects them to the original destination. The visitor is always redirected, even if recording the event fails.

Filtering scanner traffic

Mail providers and security gateways (Gmail's image proxy, Microsoft Defender, Proofpoint, Mimecast and similar) prefetch tracking pixels and follow links automatically, seconds after delivery. Taifa Mail filters this so counts reflect real human activity:

• Opens and clicks from known scanner user agents are logged but do not increment the counters.
• Any open or click within a few seconds of the send time is treated as a prefetch.
• Repeat opens, or repeat clicks on the same URL, within a short window are coalesced.

Because a scanner can warm a mail client's image cache, a genuine open may never reach our pixel. When that happens a confirmed click back-fills the open, so engagement is not undercounted.