How can we track marketing email openings thanks to Piano Analytics SDK?

You can measure marketing email openings with Piano Analytics by embedding a raw event in your emails using an <img> tag (a tracking pixel). When the email is opened and images are allowed to load, the pixel is requested and Piano Analytics receives an open event.

This implementation relies on the Collection API (not an SDK running inside the email client).

Principle: send an offsite event with a tracking pixel

To track email opens, you must use the offsite event:

Event name: email.display.offsite

Place an invisible pixel at the top of your email HTML so it loads as soon as the email is opened.

Example pixel (recommended: URL-encoded events parameter)

CODE

<img
  src="https://<collection-domain>/event?s=<site-id>&events=%5B%7B%22name%22%3A%22email.display.offsite%22%2C%22data%22%3A%7B%22src_medium%22%3A%22email%22%2C%22src_campaign%22%3A%22email%20campaign%22%7D%7D%5D"
  width="1"
  height="1"
  style="display:none;"
  alt=""
/>

You must adapt the src attribute with:

<collection-domain>: your Piano Analytics data collection domain
<site-id>: your site ID

These values are available in your Piano Analytics interface (Data collection dashboard).

You can modify the values of src_medium and src_campaign according to your needs.

Required properties and Data Model

At minimum, include these properties in the event payload to identify the source:

src_medium (for example: email)
src_campaign (your campaign name)

If you use custom properties (including additional src_* properties such as src_email_id), make sure they are declared in your Data Model, otherwise they may not be available for reporting.

Tracking unique opens (deduplication)

Email open pixels can be loaded multiple times (re-opens, forwarded emails, some clients prefetching images). If you want to estimate unique opens, add a unique identifier per recipient (or per send) and deduplicate in reporting, for example:

src_email_id: a unique ID for the recipient/message

Example (JSON shown for readability—ensure proper URL encoding when used in the src URL):

CODE

<img
  src='https://<collection-domain>/event?s=<site-id>&events=[{"name":"email.display.offsite","data":{"src_medium":"email","src_campaign":"your_campaign_name","src_email_id":"unique_id"}}]'
  width="1"
  height="1"
  style="display:none;"
  alt=""
/>

Important limitations of email open measurement

Image blocking: Many email clients block images by default. If images do not load, the pixel will not fire, and the open will not be tracked.
Not tied to onsite identity/visits: *.offsite events are collected outside of your site/app context. They are generally not associated with standard onsite identifiers (such as visit_id / visitor_id) and are best used as counters and for campaign-level analysis.
HTTPS required: Use https:// to avoid mixed-content/security warnings and improve deliverability.

More information on email open tagging can be found at: Email Open Measurement.