Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Pixelita Tracker

Tiny Flask app for email open and click tracking.

Endpoints

Open tracking pixel:

<img src="https://YOUR-PIXELITA-DOMAIN/open.png?job=mcd-relo-other-side&email=other-side-email-1&event=open" width="1" height="1" alt="">

Open tracking pixel with the client's hashed contact ID:

<img src="https://YOUR-PIXELITA-DOMAIN/open.png?job=mcd-relo-other-side&email=other-side-email-1&event=open&CTID={{CLIENT_HASHED_ID_TOKEN}}" width="1" height="1" alt="">

Click tracking redirect:

<a href="https://YOUR-PIXELITA-DOMAIN/click?job=mcd-relo-other-side&email=other-side-email-1&link=smart-moves-guide&redirect=https%3A%2F%2Fexample.com%2Fguide">
  Read Smart Moves guide
</a>

Click tracking redirect with the client's hashed contact ID:

<a href="https://YOUR-PIXELITA-DOMAIN/click?job=mcd-relo-other-side&email=other-side-email-1&link=smart-moves-guide&CTID={{CLIENT_HASHED_ID_TOKEN}}&redirect=https%3A%2F%2Fexample.com%2Fguide">
  Read Smart Moves guide
</a>

Report:

https://YOUR-PIXELITA-DOMAIN/report?token=YOUR_REPORT_TOKEN

The browser report shows newest events first.

CSV download:

https://YOUR-PIXELITA-DOMAIN/report.csv?token=YOUR_REPORT_TOKEN

Logged fields

Pixelita logs to pixel_log.csv:

  • timestamp
  • event
  • job
  • email
  • link
  • pid
  • redirect
  • ip
  • user_agent
  • referer
  • extra

pid is optional. Pixelita accepts pid, rid, CTID, or ctid as the per-contact value and stores it in the pid report column. If you do not include one of those values, reporting is campaign/email/link level only.

Local run

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
REPORT_TOKEN=choose-a-secret-token python app.py

Then test:

http://127.0.0.1:5000/open.png?job=test&email=test-email&event=open
http://127.0.0.1:5000/open.png?job=test&email=test-email&event=open&CTID=test-hashed-id
http://127.0.0.1:5000/click?job=test&email=test-email&link=test-link&redirect=https%3A%2F%2Fexample.com
http://127.0.0.1:5000/click?job=test&email=test-email&link=test-link&CTID=test-hashed-id&redirect=https%3A%2F%2Fexample.com
http://127.0.0.1:5000/report?token=choose-a-secret-token

Production notes

The app needs a writable filesystem for pixel_log.csv. If the host has an ephemeral filesystem, use a persistent disk or database before using it for a real send.

Railway setup

This folder is ready to deploy as a Railway web service.

Deploy source

Use this folder as the Railway service root:

emails/pixel-tracker/pixelita-tracker-main

Note: Railway deploys need to be followed with a check on the log to make sure it's tracking.

Test link:

https://joyful-wonder-production-fd27.up.railway.app/open.png?job=diagnostic&email=ctid-final-check&event=open&CTID=ctid-final-123

Railway will use Dockerfile via railway.json.

Variables

Set this variable in Railway:

REPORT_TOKEN=choose-a-long-random-secret

You do not need to set PIXELITA_LOG_FILE if you attach a Railway Volume. Pixelita automatically uses RAILWAY_VOLUME_MOUNT_PATH/pixel_log.csv.

Volume

Add a Railway Volume to the Pixelita service.

Recommended mount path:

/data

Railway makes this available to the app as RAILWAY_VOLUME_MOUNT_PATH, and Pixelita writes the log to:

/data/pixel_log.csv

Domain

In the Railway service, generate a public domain. After deployment, test:

https://YOUR-RAILWAY-DOMAIN/health
https://YOUR-RAILWAY-DOMAIN/open.png?job=test&email=test-email&event=open
https://YOUR-RAILWAY-DOMAIN/open.png?job=test&email=test-email&event=open&CTID=test-hashed-id
https://YOUR-RAILWAY-DOMAIN/click?job=test&email=test-email&link=main-cta&redirect=https%3A%2F%2Fexample.com
https://YOUR-RAILWAY-DOMAIN/click?job=test&email=test-email&link=main-cta&CTID=test-hashed-id&redirect=https%3A%2F%2Fexample.com
https://YOUR-RAILWAY-DOMAIN/report?token=YOUR_REPORT_TOKEN
https://YOUR-RAILWAY-DOMAIN/report.csv?token=YOUR_REPORT_TOKEN

/pixel_log.csv is intentionally not public. Use the protected /report.csv URL or the Railway volume path instead.

Email replacements

For open tracking, use:

<img src="https://YOUR-RAILWAY-DOMAIN/open.png?job=mcd-relo-other-side&email=other-side-email-1&event=open" width="1" height="1" alt="">

For per-contact tracking, ask the client to append their hashed ID token as CTID. Pixelita will store that value in the existing pid report column:

<img src="https://YOUR-RAILWAY-DOMAIN/open.png?job=mcd-relo-other-side&email=other-side-email-1&event=open&CTID={{CLIENT_HASHED_ID_TOKEN}}" width="1" height="1" alt="">
<a href="https://YOUR-RAILWAY-DOMAIN/click?job=mcd-relo-other-side&email=other-side-email-1&link=smart-moves-guide&CTID={{CLIENT_HASHED_ID_TOKEN}}&redirect=https%3A%2F%2Fwww.mcdonalds.com%2Fus%2Fen-us%2Fus-franchising%2Frelocation.html">
  Read Smart Moves guide
</a>

For all tracking, replace {{PIXELITA_BASE_URL}} with your Railway app URL:

https://YOUR-RAILWAY-DOMAIN

The generated emails already add /open.png for opens and /click for the main CTA links. Leave normal footer, privacy, unsubscribe, and email links as direct links.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages