Skip to content
MailPush Docs

Track opens and clicks

MailPush adds an invisible image and rewrites the links of each email, so you learn when a recipient opens it and which links they click.

Prerequisites

Section titled “Prerequisites”
  • A verified domain and a live API key. Emails sent with a test key are never tracked.
  • An HTML body. The text version is never changed, so its links are not tracked.
  • For the SDK examples, mailpush 0.4.0 or later.

1. Choose what to track for a domain

Section titled “1. Choose what to track for a domain”

Opens and clicks are tracked for every domain until you turn them off. In the dashboard, open Domaines (domains), click the domain, and go to Suivi des ouvertures et des clics (open and click tracking). Two checkboxes apply to every email sent from the domain:

Checkbox What MailPush does
Suivre les ouvertures (track opens) Adds a 1 × 1 px transparent image at the end of the body, with an address unique to each recipient.
Suivre les clics (track clicks) Points each http and https link at t.mailpush.app, which redirects at once to the original address.

For marketing emails, the French data protection authority asks for the recipient’s consent before you track opens (CNIL recommendation of March 12, 2026). You collect that consent. Turn tracking off for recipients who did not give it.

2. Override the domain for one email

Section titled “2. Override the domain for one email”

Pass tracking with the email. A field you leave out follows the domain.

Terminal window
curl https://api.mailpush.app/v1/emails \
  -H "Authorization: Bearer $MAILPUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <news@example.com>",
    "to": "customer@example.org",
    "subject": "Our autumn collection",
    "html": "<p>Hello, <a href=\"https://example.com/autumn\">see the collection</a>.</p>",
    "tracking": { "opens": false, "clicks": true }
  }'
await mailpush.emails.send({
  from: "Acme <news@example.com>",
  to: "customer@example.org",
  subject: "Our autumn collection",
  html: '<p>Hello, <a href="https://example.com/autumn">see the collection</a>.</p>',
  tracking: { opens: false, clicks: true },
});
Section titled “3. Keep a link out of tracking”

Add data-mp-notrack to the link. MailPush leaves its address as it is and removes the attribute before sending.

<a href="https://example.com/account/reset?token=abc" data-mp-notrack>Choose a new password</a>

mailto:, tel: and # links are never rewritten. An email tracks its first 200 links. An HTML body larger than 1 MB is sent without tracking.

4. Read opens and clicks

Section titled “4. Read opens and clicks”

Each recipient gets its own pixel and its own links, so opens and clicks are counted per recipient.

  • The dashboard. On the email’s page, each recipient shows Ouvert le (opened on), Cliqué le (clicked on), and every open and click in its history.
  • The API. GET /v1/emails/:id returns opened_at and clicked_at for each recipient: the first open and the first click made by a person.
  • Webhooks. Subscribe to email.opened and email.clicked.
  • Statistics. The dashboard adds them up by day and by template, see step 5.

A click by a person also counts as an open, because they read the email to click. That covers recipients whose images are blocked.

MailPush records an open at most once an hour per recipient, and a click at most once a minute per link.

Opens and clicks made by machines

Section titled “Opens and clicks made by machines”

Some opens and clicks come from software, not from the recipient. MailPush still records them and sends their webhooks, with machine set to true and the reason in machine_reason. They never set opened_at or clicked_at.

machine_reason What happened
apple_privacy Apple Mail fetched the image when the email arrived, from Apple’s network (17.0.0.0/8), whether or not the recipient reads it.
scanner A security gateway or a robot followed the link: a HEAD request, an empty user agent, or one of known scanners and HTTP libraries.
too_fast The link was followed less than 5 seconds after the recipient’s server accepted the email.
burst Another link of the same email was followed by the same recipient within 1 second.

Gmail and Yahoo load images through their own proxies when the recipient opens the email, so those opens count as made by a person.

5. Read the statistics

Section titled “5. Read the statistics”

In the dashboard, open Statistiques (statistics). Choose the last 7, 30 or 90 days. In Par template (by template), click a template to see its emails alone. Every member of the account can open this page, whatever their role.

Each email counts on the day it was sent, in Paris time, with everything that happened to it since. The numbers of a day keep moving while its recipients open and click. Emails sent with a test key never count.

Number What it counts Rate out of
Envoyés (sent) Recipients of the emails sent during the period.
Délivrés (delivered) Recipients whose server accepted the email. Sent
Ouvertures estimées (estimated opens) Recipients who opened the email, machines left out. Delivered recipients whose opens were tracked
Raw opens (brutes) Recipients who opened the email, machines included. Delivered recipients whose opens were tracked
Clics uniques (unique clicks) Recipients who clicked at least once, machines left out. Delivered recipients whose clicks were tracked
Clicks (clics en tout) Every click made by a person.
Clics après ouverture (CTOR) (click to open rate) Recipients who clicked, among those who opened, on emails that tracked both. Recipients who opened
Rebonds (bounces) Recipients whose server refused the email. Sent, minus the addresses blocked before sending
Plaintes (complaints) Recipients who reported the email as spam. Delivered

Recipients of emails sent with tracking off stay out of the open and click rates, and the page says how many they are. A rate shows Non mesuré (not measured) when nothing was tracked.

Next steps

Section titled “Next steps”