07 · MailMarco API

Tracking

Opens and clicks are served from your own tracking hostname and arrive as ordinary webhook events.

How tracking works#

Tracking is applied when a message is rendered for delivery, not when you call the API:

1. Every href="http…" in the HTML body is stored as a link row and rewritten to a signed redirect URL on your tracking host. Non-HTTP hrefs — mailto:, tel:, in-page anchors — are left alone.
2. A 1×1 transparent GIF is injected just before </body> (or appended if there is no body tag).
3. Fetching either URL records the event and publishes email.opened or email.clicked to your webhooks.

Both URLs carry a signed opaque token that binds the organization, message and recipient. Nothing identifying appears in the path.

https://track.example.com/t/o/<token>    open pixel
https://track.example.com/t/c/<token>    click redirect

The tracking domain#

The host comes from the TRACKING CNAME generated when you added the sending domain — track.<your domain> pointing at track.mailmarco.com. See Domains.

Open tracking#

• The pixel endpoint always returns a 200 with a GIF, whatever the token says. An invalid, expired or forged token is indistinguishable from a valid one, so the endpoint cannot be used to probe whether a message exists.
• It is served no-store, no-cache, must-revalidate, private so an intermediate cache does not swallow later opens.
• An open is recorded once per recipient per message. The first insert wins; subsequent fetches are silently ignored and emit no second event. Your handler will therefore see email.opened at most once for a given recipient — there is no open count.

Click tracking#

• The destination is read from the stored link row, never from the request, and the row must belong to the same message and organization as the token. There is no open-redirect surface: you cannot craft a URL that redirects anywhere MailMarco did not already store.
• Only http(s) destinations are redirected to. Anything else is refused even if it somehow reached the database.
• A valid click answers 302 to the original URL. An invalid token answers 400 invalid tracking link — unlike opens, clicks fail loudly, because silently swallowing a click would strand the recipient.
• Every click is recorded. Unlike opens, repeat clicks are not de-duplicated, so email.clicked can fire multiple times for one recipient. The event data carries recipient_id, url and link_id.

{
  "message_id": "b1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "recipient_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "url": "https://example.com/pricing",
  "link_id": "6f5e4d3c-2b1a-4098-8f7e-6d5c4b3a2019"
}

Per-message toggles#

Rendering honours two independent flags, trackOpens and trackClicks. With both off the HTML is passed through completely untouched — no pixel, no rewritten links.

Privacy and accuracy#

• Open tracking measures image loads. Mail clients that block remote images under-report, and privacy proxies that pre-fetch images over-report. Treat opens as a weak signal and clicks as a strong one.
• Because opens are de-duplicated per recipient, a pre-fetching proxy inflates your unique open rate by exactly one event and no more.
• Tokens are signed, so a recipient cannot forge an open or click for another message, and the tracking host is yours — recipients never see a third-party domain in a link.
• If you need to send without any tracking, send a message with no HTML body: a text-only message has nothing to rewrite and no pixel to inject.