Engagement Tracking

See when recipients open your emails and click the links inside them — per sending domain, and separately for marketing and transactional mail. Off by default for every domain. Turn on clicks without opens, opens without clicks, or neither — and choose independently per category, e.g. track marketing link clicks while leaving transactional mail (password resets, magic-link sign-ins, receipts) untouched, since those often carry one-time links you may not want click data retained for.

What the data can and can't tell you

•Clicks are a reliable signal — a real request hit our redirect endpoint.
•Opens are approximate. Apple Mail Privacy Protection and the Gmail/Yahoo image proxies fetch the tracking pixel without a human looking; security scanners sometimes fetch or click too.
•Plain-text emails can't be tracked at all — there's no HTML to inject a pixel or rewrite a link into.
•You're responsible for disclosing tracking to your recipients where your local law requires it.

Turn tracking on for a domain

Toggle from the Settings → Tracking page in the dashboard, or via the API:

PATCH/v1/user/settings/tracking/domains/:domain

curl -X PATCH "https://api.altermail-console.com.ng/v1/user/settings/tracking/domains/yourdomain.com" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_API_KEY" \
  -d '{
    "category": "marketing",
    "opens": true,
    "clicks": true
  }'

category is marketing or transactional — the request updates only that category for the domain; the other category's setting is left untouched. Use PATCH /v1/user/settings/tracking/domains (same body, no :domain) to apply one category's setting to every verified domain on your account at once.

View current settings

GET/v1/user/settings/tracking

{
  "domains": [
    {
      "domain": "yourdomain.com",
      "tracking": {
        "marketing": { "opens": true, "clicks": true },
        "transactional": { "opens": false, "clicks": false }
      },
      "trackingUpdatedAt": 1792285425030,
      "disabledByAdmin": false
    }
  ]
}

Seeing the results

GET /v1/user/email/events includes openCount / clickCount per message once tracking is on, plus opened/clicked query filters (?opened=true) and platform-wide opened/clicked totals in the response's counts. The dashboard's Delivery Events page shows this inline and lets you open any message's full engagement timeline.

GET/v1/user/email/events/:messageId/engagement

{
  "messageId": "71688732-3522-48fe-a86a-b3bdd19540ae",
  "openCount": 2,
  "clickCount": 1,
  "firstOpenedAt": "2026-10-18T01:06:02.265Z",
  "firstClickedAt": "2026-10-18T01:16:24.209Z",
  "timeline": [
    { "type": "clicked", "at": "2026-10-18T01:16:24.209Z", "url": "https://yourdomain.com/offer", "linkIndex": 0, "likelyBot": false },
    { "type": "opened",  "at": "2026-10-18T01:06:02.265Z", "likelyMachineOpen": true }
  ]
}

likelyBot / likelyMachineOpen flag events that match known scanner/proxy patterns or arrived implausibly fast after delivery — still counted, just marked, since this data is reporting-only and never affects your billing, quota, or account standing.

Webhooks

Add opened and clicked to a domain's webhookEvents to receive email.opened / email.clicked callbacks — same configuration and signature verification as every other webhook event. See Webhooks for the full payload shapes and signing details.

Admins can only disable, never enable

•Altermail support can disable tracking for a specific domain, your whole account, or platform-wide (e.g. during an incident) — never turn it on for you.
•Links keep redirecting correctly even if tracking is later turned off or a kill switch is active — only new event recording stops, nothing ever breaks for your recipients.