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
httpandhttpslink 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.
<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.
/api/v1/domains/{id}/trackingRequires domains:read/api/v1/domains/{id}/trackingRequires domains:writecurl -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
}'openTrackingboolean- Add the open pixel to email from this domain.
clickTrackingboolean- Rewrite links in email from this domain.
{
"data": {
"domainId": "436461cd-ecd1-4f6c-b5d1-604491f694d4",
"domain": "acme.com",
"openTracking": true,
"clickTracking": false
}
}At least one of the two fields is required.
Analytics
/api/v1/analyticsRequires emails:readReturns 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"daysinteger- Rolling window that ends now. 1 to 366, default 30.
from, toISO 8601- Explicit range instead of
days.tois 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
{
"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.
| Field | How it is calculated |
|---|---|
accepted | Emails a provider accepted: sent + delivered + complained. |
deliveryRate | accepted / (accepted + bounced + failed) |
openRate | Emails opened at least once / accepted emails that carried the pixel |
clickRate | Emails clicked at least once / accepted emails with rewritten links |
clickToOpenRate | Emails 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
/api/v1/analytics/domainsRequires emails:readOne 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"{
"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
/api/v1/analytics/emails/{id}Requires emails:readOpen 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"{
"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
| Variable | Used by | Purpose |
|---|---|---|
MAILFORGE_TRACKING_BASE_URL | Worker | Public address of your MailForge web app, for example https://mail.example.com. Required in production. Without it email is sent untracked. |
TRACKING_HMAC_SECRET | Web, worker | Signs tracking links. At least 16 characters and identical in both services. Falls back to SESSION_HMAC_SECRET. |
MAILFORGE_TRACKING_DISABLED | Worker | Set to true to switch tracking off for the whole server. |