> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Email Tracking

> Record when contacts open your emails and click their links, and let each contact agree to or refuse that tracking.

## Overview

Notifuse can record two things about the emails it sends:

- **Opens**: an invisible image (a tracking pixel) is added to the email, and it records when the email is opened.
- **Clicks**: links go through a redirect that records each click before sending the contact on to the page.

Each one is turned on separately in the workspace settings, and each contact can agree to or refuse each one. Links keep their [UTM parameters](https://www.notifuse.com/docs/features/broadcast-campaigns.md#utm-tracking) whatever the tracking choice.

## Workspace settings

In **Settings → General**, panel **Email tracking**:

- **Opens** and **Clicks** turn each kind of tracking on or off for the whole workspace. When one is off, no email carries it, whatever the contacts chose.
- **Contacts without recorded consent** decides what happens for a contact who never made a choice: **Track** (the default) or **Don't track**.

A contact's own choice always wins over this setting. Some regulators, such as the Italian Garante and the French CNIL, expect open and click tracking to require consent: if that applies to you, choose **Don't track**, and only contacts who agreed are tracked.

## The contact's choice

Each contact has four fields:

| Field                         | Description                                                                                                     |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `tracking_opens_consent`      | `granted`, `denied`, or `null` when unknown                                                                     |
| `tracking_clicks_consent`     | `granted`, `denied`, or `null` when unknown                                                                     |
| `tracking_consent_updated_at` | When a choice last changed. Set by Notifuse when a value changes, unless you send it                            |
| `tracking_consent_source`     | Where the change came from: `api`, `console`, `import`, `notification_center`, `email_link` or `subscribe_form` |

An email to a contact is tracked for opens when the workspace tracks opens and the contact's choice allows it: `granted`, or unknown with **Track** selected. Clicks follow the same rule.

The choice can be set:

- **With the API**: `contacts.upsert`, `contacts.import`, the transactional API's `contact`, and the subscribe endpoint. Without a `tracking_consent_source`, a change made with an API key records `api` and an import records `import`; a subscription form posted without an API key always records `subscribe_form`.
- **In the console**: on the contact's page, when creating or editing a contact, and in CSV imports (columns mapped to _Opens Tracking Consent_ and _Clicks Tracking Consent_, values `granted` or `denied`).
- **By the contact**, in the [notification center](https://www.notifuse.com/docs/features/notification-center.md#email-tracking).

Send `null` to set a choice back to unknown. A request that leaves the fields out keeps the stored choice.

### Using the choice

- **Contacts list**: filter by each choice, `unknown` included, and show a _Tracking consent_ column. CSV exports include the four fields.
- **Segments**: the four fields are contact fields; use _is not set_ for an unknown choice.
- **Automations**: a _contact updated_ trigger can be limited to a change of either choice.
- **Webhooks**: contact payloads carry the four fields, and a change is recorded on the contact timeline.

## When a contact changes their mind

The choice is applied when an email is sent, and checked again when an open or a click comes in. A contact who refuses tracking after an email was sent is not recorded opening or clicking it: the link still takes them to the page.

## Link clicks

Each email records which of its links were clicked. The first time a contact clicks each link of an email, the
contact timeline gets an `email.link_clicked` entry with the link's address, next to the `email.clicked` entry of the
email's first click. This entry can [start an automation](https://www.notifuse.com/docs/features/automations.md#link-click-triggers), and it brings
segments that filter on a clicked link up to date at once. It does not count toward the monthly event usage.

No entry is written for:

- a click on a link already clicked in that email (a link clicked before the upgrade to 44.0 gets its entry on its
  next click);
- a link Notifuse cannot verify: links in emails sent before version 42.2, and links whose signature does not match;
- a link whose address is longer than 2,048 characters, or a link beyond the first 50 different links clicked in an
  email;
- links that are not `http` or `https`, such as `mailto:` and `tel:`, and links to your Notifuse instance itself, such
  as the unsubscribe, notification center and web version links. Notifuse recognizes them by your API endpoint, your
  workspace's custom domain, or the host the click reached, including one a reverse proxy forwards, on any port.
  Two kinds of links fall in this case too: links to your blog when it is served on your custom domain, and links to
  another site served on the same host name as your Notifuse instance, even on another port.

Opens and clicks on an email whose contact was deleted are not recorded; the link still takes the reader to the page.

## Statistics

Open and click rates are counted over the emails that were tracked, not over all emails sent. Where some emails were not tracked, the tooltip of the rate says how many were (_of 1,200 tracked_), and a rate with no tracked email shows `-`. This applies to broadcast statistics, A/B test results, per-link click rates and the analytics dashboard.

Emails sent before version 43 count as tracked, so their rates do not change.

## A/B tests

The automatic winner is chosen on the open or click rate over the tracked recipients of each variation. A variation with no tracked recipient cannot win, and when none has any, you pick the winner yourself.

When the workspace does not track contacts without recorded consent, only the contacts who agreed count in the results: the variations table warns in orange when fewer than half of a variation's recipients were tracked, and the tooltip of each rate gives the number of tracked recipients.

## Turning tracking off for one email

- **Broadcasts**: check **Don't track opens and clicks for this broadcast** in the _Web Analytics_ step (`tracking_mode: "no_tracking"` in the API). UTM parameters are kept. The winner of an A/B test then has to be picked by hand.
- **Transactional notifications**: choose **No open or click tracking, keep UTM parameters** (`no_tracking`), or **Disabled for this notification** (`disabled`), which also leaves links untouched, without UTM parameters, for links that must not change such as sign-in links.

## Template links

Two variables let contacts make their choice from an email:

- `{{ tracking_preferences_url }}` opens the email tracking dialog of the notification center.
- `{{ tracking_optout_url }}` asks the contact to confirm, then refuses both open and click tracking (source `email_link`). Nothing is recorded until the contact confirms, because email security scanners open links on their own.

```html
<a href="{{ tracking_preferences_url }}">Choose what we track</a>
```

Both links are never rewritten for tracking.
