Tracking Pixel API

Tracking pixels (also called a beacon, 1×1 gif, or clear gif) allow for tracking email opens, advertising impressions, and checkout pages where JavaScript and POST requests are disallowed, but where you can embed an image.

Follow Segment's HTTP Tracking API to use the /pixel API endpoint, which accepts a base64 encoded URL ?data parameter and returns a 1×1 transparent gif.

Pixel API endpoint signature

https://api.segment.io/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>

(information)

base64 encoding optional

The base64 encoding is optional, however it prevents special character interpretation or muxing by browsers, or other tools that might interpret URLs. For example, the URL https://www.example.com/ might be altered to http%3A%2F%2Fwww.example.com when appended to another URL, but the base64 version, aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20, remains unchanged.

Pixel Routes

1/v1/pixel/identify
2/v1/pixel/group
3/v1/pixel/alias
4/v1/pixel/page
5/v1/pixel/screen
6/v1/pixel/track

Each endpoint always responds with a 200 <empty-gif>, even if an error occurs.

Example Email Opened event

Create the payload

Email Opened event payload

1{
2  "writeKey": "YOUR_WRITE_KEY",
3  "userId": "user_123",
4  "event": "Email Opened",
5  "properties": {
6    "subject": "The Electric Daily",
7    "email": "jane.kim@example.com"
8  }
9}

Note: you must include either a userId or anonymousId with every API call.

Encode it using base64 and make sure it's URL safe

You can accomplish this with WindowBase64 methods:

base64-encoded payload

eyJ3cml0ZUtleSI6ICJZT1VSX1dSSVRFX0tFWSIsICJ1c2VySWQiOiAiMDI1cGlrYWNodTAyNSIsICJldmVudCI6ICJFbWFpbCBPcGVuZWQiLCAicHJvcGVydGllcyI6IHsgICAic3ViamVjdCI6ICJUaGUgRWxlY3RyaWMgRGFpbHkiLCAgICJlbWFpbCI6ICJwZWVrQXRNZUBlbWFpbC5wb2tlIiB9fQ

If you choose not to encode your payload, send it like this instead

Unencoded pixel request

https://api.segment.io/v1/pixel/track?userId=user_123&event=Email Opened&properties.subject=The Electric Daily&properties.email=jane.kim@example.com&writeKey=<YOUR_WRITE_KEY>

Tracking pixel image tag

<img src="https://api.segment.io/v1/pixel/track?data=eyJ3cml0ZUtleSI6ICJZT1VSX1dSSVRFX0tFWSIsICJ1c2VySWQiOiAiMDI1cGlrYWNodTAyNSIsICJldmVudCI6ICJFbWFpbCBPcGVuZWQiLCAicHJvcGVydGllcyI6IHsgICAic3ViamVjdCI6ICJUaGUgRWxlY3RyaWMgRGFpbHkiLCAgICJlbWFpbCI6ICJwZWVrQXRNZUBlbWFpbC5wb2tlIiB9fQ">

Tracking Pixel API

Pixel API endpoint signature

Pixel API endpoint signature

base64 encoding optional

Pixel Routes

Example Email Opened event

Create the payload

Email Opened event payload

Encode it using base64 and make sure it's URL safe

base64-encoded payload

If you choose not to encode your payload, send it like this instead

Unencoded pixel request

Add an image tag to your email newsletter with src pointing to a Pixel API route

Tracking pixel image tag

Add an image tag to your email newsletter with `src` pointing to a Pixel API route