> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/email-tracking.md).

# Email tracking

Track email opens with a pixel and clicks with a tracking URL.

## Your goal

Record that a user opened one of your emails, and that they clicked a link inside it, so those interactions appear on their timeline alongside everything else.

## Expected outcome

`$email_view` and `$email_click` events arriving with the user identified - ideally by an email hash you supply rather than by a cookie you hope is readable.

## How it works

There are two distinct mechanisms, one per action:

| To track                             | You must                                         |
| ------------------------------------ | ------------------------------------------------ |
| The **opening** of an email          | Include a **pixel**.                             |
| The **clicks** on links in the email | Replace each link with a **click tracking URL**. |

For each event, the datamart identifies the user:

* **Recommended:** by the user's **email hash**, which you include in the pixel or tracking URL.
* Otherwise by reading their cookies, which works reliably for clicks but only sometimes for opens, depending on the email client.

{% hint style="info" %}
Activities tracked this way have `$type` set to `EMAIL` and `$session_status` set to `NO_SESSION`. See [the UserActivity object](/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time.md#the-useractivity-object).
{% endhint %}

## Tracking opens with a pixel

Calls to this URL generate events:

```
https://events.mediarithmics.com/v1/touches/pixel?
  $ev=$email_view&
  $dat_token=<DATAMART_TOKEN>&
  $email_hash=78b04074e616166938cf672f70f41b4d&
  <any custom properties>
```

Using the `$uids` field instead of a single identifier:

```
https://events.mediarithmics.com/v1/touches/pixel?
  $ev=$email_view&
  $dat_token=<DATAMART_TOKEN>&
  $uids=jso-[{"$tpe":"EM","$eh":"78b04074e616166938cf672f70f41b4d"}]&
  <any custom properties>
```

With a custom domain:

```
https://analytics.custom-domain.com/v1/touches/pixel?
  $ev=$email_view&
  $dat_token=<DATAMART_TOKEN>&
  $email_hash=78b04074e616166938cf672f70f41b4d&
  <any custom properties>
```

## Tracking clicks

Calls to this URL generate click events and redirect the user:

```
https://events.mediarithmics.com/v1/touches/click?
  $ev=$email_click&
  $dat_token=<DATAMART_TOKEN>&
  $email_hash=78b04074e616166938cf672f70f41b4d&
  <any custom properties>&
  $redirect=<CLICK_URL>
```

{% hint style="warning" %}
`$redirect` must be **URL-encoded** (RFC 3986) and **placed at the end of the URL**. Any parameter placed after `$redirect` is not saved.
{% endhint %}

## Parameters

The same parameters apply to both URLs, apart from `$redirect`, which is specific to clicks.

| Field                 | Type                     | Description                                                         |
| --------------------- | ------------------------ | ------------------------------------------------------------------- |
| `$ev`                 | String                   | The event name: `$email_view` for opens, `$email_click` for clicks. |
| `$dat_token`          | String                   | The token of the audience datamart.                                 |
| `$redirect`           | String                   | **Clicks only.** The redirect URL, URL-encoded, placed last.        |
| `$cuid`               | String, optional         | The user account ID.                                                |
| `$email`              | String, optional         | The user's email.                                                   |
| `$email_hash`         | String, optional         | The user's email hash.                                              |
| `$cb`                 | String, optional         | The cache buster - a random string.                                 |
| `$uids`               | JSON as string, optional | The list of user identifiers.                                       |
| *any custom property* | Any                      | A custom property.                                                  |

{% hint style="info" %}
Include `$cb` with a random value on pixels. Without a cache buster, an email client that caches images can prevent the open from being recorded.
{% endhint %}

## Consistency with the rest of your data

The email hash you put in these URLs is the same identifier used everywhere else, so it must use **the same hash function as the rest of your datamart** - otherwise email interactions land on a different UserPoint from the rest of the user's history. See [User Email](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/user-identifiers/user-email.md).

## Verify

* `$email_view` and `$email_click` events appear on the timeline of a test user.
* The activities carry `$type` `EMAIL`.
* Clicks redirect to the intended destination, with the parameters after `$redirect` - if any - knowingly discarded.
* Interactions land on the same UserPoint as the user's site activity, which confirms the hash matches.

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>User Email</strong></td><td>The hash that identifies the user.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/user-identifiers/user-email.md">User Email</a></td></tr><tr><td><strong>Ads exposure tracking</strong></td><td>The same pixel mechanics for display.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/ads-exposure-tracking.md">Ads exposure tracking</a></td></tr><tr><td><strong>Standard events</strong></td><td>Where <code>$email_view</code> and <code>$email_click</code> sit in the catalogue.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/standard-events.md">Standard events</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/email-tracking.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.