Tracking and analytics

Open and click tracking, per-domain opt-out and the analytics API.

How tracking works

Tracking is on by default for HTML email. Right before an email is handed to a provider, the worker changes its HTML in two ways:

  • Every http and https link in an <a href> is replaced by a link to your MailForge server, which records the click and redirects to the original address.
  • A 1×1 pixel image is added at the end of the body. Loading it records an open.

The tracking links are signed, so they cannot be changed to redirect somewhere else. Text-only email is never changed and therefore not tracked.

Exclude a link

Add data-mf-no-track to a link to leave it untouched. Use it for unsubscribe links and one-time login links. mailto:, tel: and anchor links are never rewritten.

HTML
<a data-mf-no-track href="https://acme.com/unsubscribe">Unsubscribe</a>

What is counted

  • Requests from known scanners and bots are answered but not counted.
  • A click also counts as an open when the pixel was blocked.
  • MailForge stores the user agent of an open or click, but no IP address.

Tracking per domain

Opens and clicks can be switched off separately for each sending domain.

GET/api/v1/domains/{id}/trackingRequires domains:read
PATCH/api/v1/domains/{id}/trackingRequires domains:write
curl -X PATCH https://mail.example.com/api/v1/domains/436461cd-ecd1-4f6c-b5d1-604491f694d4/tracking \
  -H "Authorization: Bearer $MAILFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "openTracking": true,
    "clickTracking": false
  }'
Body parameters
openTrackingboolean
Add the open pixel to email from this domain.
clickTrackingboolean
Rewrite links in email from this domain.
Response
{
  "data": {
    "domainId": "436461cd-ecd1-4f6c-b5d1-604491f694d4",
    "domain": "acme.com",
    "openTracking": true,
    "clickTracking": false
  }
}

At least one of the two fields is required.

Analytics

GET/api/v1/analyticsRequires emails:read

Returns totals with rates, a time series for charts and the ten most clicked links of your workspace.

curl "https://mail.example.com/api/v1/analytics?days=7&tz=Europe/Berlin" \
  -H "Authorization: Bearer $MAILFORGE_API_KEY"
Query parameters
daysinteger
Rolling window that ends now. 1 to 366, default 30.
from, toISO 8601
Explicit range instead of days. to is exclusive and defaults to now.
domainstring
Only email sent from this domain.
interval"hour" | "day"
Bucket size of the time series. Defaults to hour for ranges up to 2 days, otherwise day. Hourly buckets are limited to 31 days.
tzstring
IANA time zone for the bucket boundaries, such as Europe/Berlin. Default UTC.

Response

Response
{
  "data": {
    "range": {
      "from": "2026-11-13T19:37:39.436Z",
      "to": "2026-11-20T19:37:39.436Z",
      "interval": "day",
      "timeZone": "Europe/Berlin",
      "domain": null
    },
    "summary": {
      "total": 4,
      "pending": 0,
      "sent": 4,
      "delivered": 0,
      "bounced": 0,
      "complained": 0,
      "failed": 0,
      "accepted": 4,
      "openTracked": 2,
      "uniqueOpens": 1,
      "totalOpens": 1,
      "clickTracked": 2,
      "uniqueClicks": 1,
      "totalClicks": 2,
      "deliveryRate": 1,
      "bounceRate": 0,
      "complaintRate": 0,
      "openRate": 0.5,
      "clickRate": 0.5,
      "clickToOpenRate": 1
    },
    "timeseries": [
      {
        "bucket": "2026-11-19T23:00:00.000Z",
        "total": 4,
        "accepted": 4,
        "delivered": 0,
        "bounced": 0,
        "complained": 0,
        "failed": 0,
        "opens": 1,
        "clicks": 2
      }
    ],
    "topLinks": [
      {
        "url": "https://acme.com/start",
        "clicks": 2,
        "uniqueEmails": 1,
        "lastClickedAt": "2026-11-20T19:37:39.403Z"
      }
    ]
  }
}

Rates are fractions between 0 and 1, or null when there is nothing to divide by.

FieldHow it is calculated
acceptedEmails a provider accepted: sent + delivered + complained.
deliveryRateaccepted / (accepted + bounced + failed)
openRateEmails opened at least once / accepted emails that carried the pixel
clickRateEmails clicked at least once / accepted emails with rewritten links
clickToOpenRateEmails clicked / emails opened

In timeseries, the status counts group emails by the time they were created, while opens and clicks are events that happened in that bucket.

Analytics by domain

GET/api/v1/analytics/domainsRequires emails:read

One entry per sender domain with the same numbers as summary, plus the domain's verification status and tracking switches. Domains without traffic are included. Takes days, from, to and domain.

curl https://mail.example.com/api/v1/analytics/domains \
  -H "Authorization: Bearer $MAILFORGE_API_KEY"
Response
{
  "data": [
    {
      "domain": "acme.com",
      "domainId": "436461cd-ecd1-4f6c-b5d1-604491f694d4",
      "status": "verified",
      "openTracking": true,
      "clickTracking": true,
      "lastSentAt": "2026-11-20T19:37:27.136Z",
      "total": 4,
      "pending": 0,
      "sent": 4,
      "delivered": 0,
      "bounced": 0,
      "complained": 0,
      "failed": 0,
      "accepted": 4,
      "openTracked": 2,
      "uniqueOpens": 1,
      "totalOpens": 1,
      "clickTracked": 2,
      "uniqueClicks": 1,
      "totalClicks": 2,
      "deliveryRate": 1,
      "bounceRate": 0,
      "complaintRate": 0,
      "openRate": 0.5,
      "clickRate": 0.5,
      "clickToOpenRate": 1
    }
  ],
  "range": {
    "from": "2026-10-21T19:37:39.482Z",
    "to": "2026-11-20T19:37:39.482Z",
    "domain": null
  }
}

One email

GET/api/v1/analytics/emails/{id}Requires emails:read

Open and click counters of one email and its event timeline, newest first. The sent event shows which provider accepted the message and every attempt that was made.

curl https://mail.example.com/api/v1/analytics/emails/d0bc24eb-c2d4-4a51-8e80-76e4f1cde444 \
  -H "Authorization: Bearer $MAILFORGE_API_KEY"
Response
{
  "data": {
    "id": "d0bc24eb-c2d4-4a51-8e80-76e4f1cde444",
    "status": "sent",
    "senderDomain": "acme.com",
    "openTracked": true,
    "clickTracked": true,
    "openCount": 1,
    "clickCount": 2,
    "firstOpenedAt": "2026-11-20T19:37:39.392Z",
    "lastOpenedAt": "2026-11-20T19:37:52.381Z",
    "firstClickedAt": "2026-11-20T19:37:39.392Z",
    "lastClickedAt": "2026-11-20T19:37:39.403Z",
    "events": [
      {
        "id": "5fd2fc87-d666-450a-8e62-32b3c3077fb1",
        "type": "clicked",
        "occurredAt": "2026-11-20T19:37:39.403Z",
        "payload": {
          "url": "https://acme.com/start",
          "automated": false,
          "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Safari/605.1.15"
        }
      },
      {
        "id": "7d368bc1-0f97-403b-85d5-4179c014423d",
        "type": "sent",
        "occurredAt": "2026-11-20T19:37:27.106Z",
        "payload": {
          "attempts": [
            {
              "ok": true,
              "providerId": "5ae2a853-a4b2-49e7-9cf2-7116f8e2450e"
            }
          ],
          "providerId": "5ae2a853-a4b2-49e7-9cf2-7116f8e2450e",
          "providerMessageId": "<06d53fde-9354-8df9-dfd7@acme.com>"
        }
      }
    ]
  }
}

Server setup

VariableUsed byPurpose
MAILFORGE_TRACKING_BASE_URLWorkerPublic address of your MailForge web app, for example https://mail.example.com. Required in production. Without it email is sent untracked.
TRACKING_HMAC_SECRETWeb, workerSigns tracking links. At least 16 characters and identical in both services. Falls back to SESSION_HMAC_SECRET.
MAILFORGE_TRACKING_DISABLEDWorkerSet to true to switch tracking off for the whole server.