Anypostdocs
ChangelogStatus
Docs/Sending email

Open & click tracking

Tracking records when a recipient opens a message or clicks one of its links. Each event is reported through webhooks, the same way a delivery or a bounce is.

The tracking field

tracking is an optional object on POST /v1/email with two boolean fields, opens and clicks:

curl https://api.anypost.com/v1/email \
  -H "Authorization: Bearer $ANYPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Your weekly digest",
    "html": "<p>Read more on <a href=\"https://example.com/digest\">the site</a>.</p>",
    "tracking": { "opens": true, "clicks": true }
  }'

Each domain carries its own default for open and click tracking. The tracking field overrides that default for one message: set opens or clicks to turn a feature on or off for this send only. Omit tracking, or omit one of its fields, and the domain default applies.

What each feature does

  • Open tracking adds a small invisible image to the HTML body. When a mail client loads that image, Anypost emits an email.opened event.
  • Click tracking rewrites the links in the HTML body to pass through Anypost first. A recipient who clicks is redirected to the original destination, and Anypost emits an email.clicked event.

Both features operate on the HTML body. A message with only a text body has no image to load and no links to rewrite, so it cannot be tracked.

The tracking domain requirement

Tracking links and the open image are served from a tracking domain: a branded subdomain, such as track.example.com, that you verify separately from your sending domain.

Until that tracking domain is verified, tracking is off. This is a hard requirement: a message with tracking: { opens: true } is still sent without an open image if the tracking domain is not verified. The mail is delivered normally; only the tracking is skipped. See Tracking domains for the setup.

The events

A tracked interaction arrives as an event on your registered webhooks:

EventEmitted whenCarries
email.openedThe recipient's mail client loads the open image.The recipient's IP address and user agent.
email.clickedThe recipient clicks a rewritten link.The destination URL, plus the IP address and user agent.

Each event also carries the message's email_ ID and its tags, topic, and campaign, so an open or a click can be tied back to the send. See Webhooks for the delivery mechanism and payload shape.

Automated opens and clicks

An open or click is not always a person. Mail scanners, security proxies, and link prefetchers load images and follow links on a recipient's behalf, often within seconds of delivery.

Anypost classifies this traffic. Interactions that look like a link prefetch or an automation script are dropped: they never become an email.opened or email.clicked event, so they cannot inflate your engagement numbers.

One class of automated traffic does still reach you. A mailbox-provider image proxy, such as the one Gmail uses, loads the open image as a side effect of showing the message to a real person, so an event from a proxy is genuine signal. That event arrives with a bot object naming the source and a kind of proxy. An event with no bot came directly from the recipient's client. If you want only unproxied interactions, filter out the events that carry a bot object.

In a batch and over SMTP

In a batch send, a tracking object in defaults applies to every entry that does not set its own.

An SMTP submission has no request body, so it carries the same two toggles as the X-Anypost-Track-Opens and X-Anypost-Track-Clicks headers; see Sending over SMTP.

Where to go next