Skip to main content

​
Overview

Email Tracker is a self-hosted email tracking solution that lets you monitor when recipients open your Gmail messages. Unlike third-party tracking services, you control your own data and infrastructure. The system consists of three components:
  • Chrome extension - Injects tracking pixels when you send Gmail messages
  • Node.js server - Records open events and serves the analytics dashboard
  • SQLite database - Stores email metadata and open events locally
Email Tracker uses identity-based suppression to prevent counting your own opens when you view sent messages in Gmail.

​
Key features

Privacy-focused tracking
  • Self-hosted on your own infrastructure
  • All data stored in your local SQLite database
  • No third-party services involved
  • Full control over tracking data retention
Intelligent suppression
  • Identity-based sender suppression prevents counting self-opens
  • Event-driven architecture with consume-once semantics
  • Deduplication within configurable time window (default 30 seconds)
  • Google Image Proxy detection and latency measurement
Real-time analytics
  • Live dashboard showing tracked emails and open events
  • Inbox badges displaying open counts directly in Gmail
  • IP address, user agent, and GeoIP location enrichment
  • Device type detection (phone, computer, other)
Production-ready
  • HTTPS support with sample reverse proxy configs
  • Authenticated dashboard API with token-based access
  • Health check endpoint for monitoring
  • Metrics and debug endpoints for troubleshooting

Quickstart

Get up and running in 5 minutes with local development setup

Installation

Complete installation guide for production deployment

How it works

Understanding the architecture and data flow

API reference

Complete API documentation for all endpoints

​
What makes this unique

Most email tracking solutions rely on folder names or UI heuristics to detect when you’re viewing your own sent messages. Email Tracker uses a more reliable approach:
  1. The extension scans visible thread images and decodes tracking tokens
  2. It compares the sender email from the token with your logged-in Gmail account
  3. If they match, it sends a suppression signal to the server
  4. The next pixel request for that email is marked as sender-suppressed
  5. Suppressed events are stored for audit but don’t increment open counts
This identity-based approach works reliably in Gmail’s single-page application environment without brittle folder detection.

​
System requirements

Server
  • Node.js 18 or higher
  • 512 MB RAM minimum
  • Linux, macOS, or Windows
  • Domain with HTTPS for production (email clients block HTTP images)
Browser
  • Chrome or Chromium-based browser
  • Gmail account
  • Developer mode enabled for extension installation

​
Repository structure

The project is organized as a monorepo with separate workspaces: 
email-tracker/
├── extension/          # Chrome extension (Manifest V3)
│   ├── src/content/    # Gmail content scripts
│   ├── src/background/ # Background service worker
│   └── src/popup/      # Extension popup UI
├── server/             # Express server + SQLite
│   ├── src/routes/     # API routes
│   ├── src/services/   # Business logic
│   └── src/db/         # Database schema
├── shared/             # Shared types and utilities
└── deploy/             # Sample configs (Caddy/Nginx)
The extension uses Manifest V3, which is required for all new Chrome extensions.

​
Privacy considerations

Email tracking is a sensitive topic. Here’s what data this system collects: Tracked data
  • Email ID (UUID generated by extension)
  • Sender and recipient email addresses
  • Timestamp of each open event
  • IP address and User-Agent string
  • GeoIP-enriched location (country, region, city, lat/long)
  • Device type classification
Not tracked
  • Email content or subject (optional metadata only)
  • Recipient names or contact information beyond email
  • Browsing behavior outside of tracked emails
You should inform recipients if you’re tracking email opens, especially in business contexts or jurisdictions with privacy regulations.

​
Next steps

Set up locally

Start the server and load the extension in under 5 minutes

Deploy to production

Configure HTTPS, reverse proxy, and production environment