How it works

​

Architecture overview

​

Component responsibilities

​

Chrome extension

• Detects Gmail compose dialogs using MutationObserver
• Extracts recipient and sender email from compose UI
• Requests tracking data from background worker
• Injects 1x1 transparent pixel into message body
• Renders inbox badges showing open counts
• Scans thread images for sender suppression

• Generates stable user_id (stored in chrome.storage)
• Creates unique email_id (UUID) for each message
• Encodes tracking token with email metadata
• Fetches dashboard data and caches results
• Sends POST /mark-suppress-next signals

• Configuration interface for tracker URL and dashboard token
• Debug view showing recent tracked emails
• Quick links to dashboard

​

Node.js server

import express from "express";
import { initDb } from "./db/sqlite.js";
import { dashboardRouter } from "./routes/dashboard.js";
import { trackRouter } from "./routes/track.js";

const app = express();
const port = Number(process.env.PORT ?? 8080);

app.set("trust proxy", true);
app.use(express.json({ limit: "16kb" }));
initDb();

app.get("/health", (_req, res) => {
  res.json({ ok: true });
});

app.use(dashboardRouter);
app.use(trackRouter);

app.listen(port, () => {
  console.log(`Tracker server listening on :${port}`);
});

• GET /t/:token.gif - Serves transparent pixel and records open
• POST /mark-suppress-next - Receives sender suppression signals
• GET /metrics/gmail-proxy-latency - Returns latency statistics
• GET /metrics/suppress-signals - Debug endpoint for suppression events

• GET /dashboard - Serves dashboard HTML UI
• GET /dashboard/api/emails - Returns tracked emails with open counts
• GET /dashboard/api/open-events - Returns detailed open event history
• All dashboard APIs require X-Tracker-Token header matching DASHBOARD_TOKEN

​

SQLite database

CREATE TABLE IF NOT EXISTS tracked_emails (
  email_id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  recipient TEXT NOT NULL,
  sender_email TEXT,
  sent_at TEXT NOT NULL,
  open_count INTEGER NOT NULL DEFAULT 0,
  created_at TEXT NOT NULL DEFAULT (datetime('now'))
);

CREATE TABLE IF NOT EXISTS open_events (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email_id TEXT NOT NULL,
  user_id TEXT NOT NULL,
  recipient TEXT NOT NULL,
  opened_at TEXT NOT NULL DEFAULT (datetime('now')),
  ip_address TEXT,
  user_agent TEXT,
  geo_country TEXT,
  geo_region TEXT,
  geo_city TEXT,
  latitude REAL,
  longitude REAL,
  device_type TEXT NOT NULL DEFAULT 'other',
  is_duplicate INTEGER NOT NULL DEFAULT 0,
  is_sender_suppressed INTEGER NOT NULL DEFAULT 0,
  suppression_reason TEXT,
  FOREIGN KEY (email_id) REFERENCES tracked_emails(email_id)
);

​

End-to-end lifecycle

​

1. Install and configure

• Operator installs dependencies and builds workspaces:
  npm install
  npm --workspace=shared run build
  npm --workspace=server run build
  
• Operator starts server with environment variables:
  PORT=8090 DASHBOARD_TOKEN=secret npm --workspace=server run start
  
• Operator loads extension in Chrome and configures popup with tracker URL and token

​

2. Sender composes and sends

• Gmail content script detects compose dialogs using document.querySelectorAll('div[role="dialog"]')
• On send intent (click, keyboard shortcut), content script extracts recipient and sender
• Content script sends message to background worker:
  const response = await chrome.runtime.sendMessage({
    type: "tracker:getComposeTrackingData",
    recipient,
    senderEmail
  });
  
• Background worker generates token and returns pixel URL
• Content script injects hidden pixel (extension/src/content/gmailCompose.js:280-286):
  const img = document.createElement("img");
  img.src = response.pixelUrl;  // https://your-domain/t/token.gif
  img.width = 1;
  img.height = 1;
  img.alt = "";
  img.style.cssText = "width:1px;height:1px;opacity:0;display:block;border:0;";
  body.appendChild(img);
  

​

3. Message arrives in recipient mailbox

• Recipient’s email client renders the HTML message
• When pixel URL is in viewport (or pre-fetched), client makes GET /t/token.gif request
• Some clients (Gmail, Outlook) use image proxy servers that pre-fetch images

​

4. Server processes pixel request

const payload = decodeTrackingToken(token);
const ipAddress = getRequestIp(req);
const userAgent = req.get("user-agent") || null;
const emailId = payload.email_id;

const pendingSuppression = suppressionMap.get(emailId);
const wasSuppressedBySignal = Boolean(pendingSuppression);

if (pendingSuppression) {
  suppressionMap.delete(emailId);  // consume-once semantics
  pushSuppressionDebugEvent({
    event: "suppression_consumed",
    email_id: emailId,
    at_ms: nowMs,
    delta_ms: nowMs - pendingSuppression.createdAtMs
  });
}

const result = recordOpenEvent({
  payload,
  ipAddress,
  userAgent,
  openedAtIso,
  forceSenderSuppressed: wasSuppressedBySignal,
  suppressionReason: wasSuppressedBySignal ? "mark_suppress_next" : null
});

• Queries open_events for recent opens with same email_id, ip_address, and user_agent
• If found within DEDUP_WINDOW_MS (default 30 seconds), marks as duplicate
• Duplicate events don’t increment tracked_emails.open_count
• All events are stored in open_events table with flags

res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate");
res.setHeader("Content-Type", "image/gif");
res.status(200).send(TRANSPARENT_PIXEL_GIF);

​

5. Dashboard and extension read analytics

• Dashboard UI polls GET /dashboard/api/emails with X-Tracker-Token header
• Extension background worker fetches inbox badge data every 10 seconds
• Content script renders badges in Gmail inbox rows
• Badge click opens dashboard with pre-filtered view for that email

​

Unique suppression model

​

Why identity-based?

• Sent folder vs Inbox detection is brittle with SPAs
• URL patterns change frequently
• Tab and thread navigation uses history API

​

How suppression works

function scanAndMarkSuppressNext() {
  const currentEmail = getCurrentLoggedInEmail();
  const images = document.querySelectorAll("img[src]");
  
  images.forEach((imgNode) => {
    const token = extractTokenFromTrackingSrc(imgNode.src);
    const payload = decodeTrackingPayloadFromToken(token);
    
    // Identity-based suppression: sender viewing own message
    if (payload.senderEmail !== currentEmail) {
      return;  // Different user, don't suppress
    }
    
    // Send suppression signal to server
    chrome.runtime.sendMessage({
      type: "tracker:markSuppressNext",
      emailId: payload.emailId
    });
  });
}

• Background worker receives message from content script
• Makes POST /mark-suppress-next request to server with email_id
• Server stores entry in in-memory map with timestamp

trackRouter.post("/mark-suppress-next", (req, res) => {
  const emailId = String(req.body?.email_id || "").trim();
  const nowMs = Date.now();
  
  suppressionMap.set(emailId, { createdAtMs: nowMs });
  
  res.json({ ok: true, email_id: emailId, recorded_at_ms: nowMs });
});

const pendingSuppression = suppressionMap.get(emailId);

if (pendingSuppression) {
  suppressionMap.delete(emailId);  // consume-once
  const deltaMs = nowMs - pendingSuppression.createdAtMs;
  // Event is recorded with is_sender_suppressed=1
}

​

Key characteristics

• Each suppression signal is consumed by the first pixel hit
• Subsequent opens (e.g., recipient opens) are counted normally
• Prevents over-suppression from multiple Gmail tabs

• Entries expire after 10 seconds if not consumed
• This is cleanup logic, not core suppression behavior
• Normal flow: signal → pixel → consume (< 1 second)

• Gmail pre-fetches images through proxy servers
• Server detects proxy requests by User-Agent and IP prefix
• Measures time delta between signal and proxy hit
• Stores latency samples for metrics endpoint

​

Configuration options

• Tracker Base URL - Your server URL (e.g., https://tracker.example.com)
• Dashboard Token - Must match server’s DASHBOARD_TOKEN

​

Data flow summary

┌─────────────┐
│   Extension │ Generates token, injects pixel
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Recipient   │ Email client loads pixel
│ Email Client│
└──────┬──────┘
       │ GET /t/token.gif
       ▼
┌─────────────┐
│   Server    │ Decode, dedupe, check suppression
│  (Express)  │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   SQLite    │ Store open_events, increment open_count
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Dashboard  │ Query emails and events via API
│     UI      │
└─────────────┘

​

Next steps