> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/shlokjain2031/email-tracker-extension/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Self-hosted Gmail pixel tracking with Chrome extension, Node.js server, and SQLite storage

## 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

<Info>
  Email Tracker uses identity-based suppression to prevent counting your own opens when you view sent messages in Gmail.
</Info>

## 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

## Quick links

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get up and running in 5 minutes with local development setup
  </Card>

  <Card title="Installation" icon="download" href="/installation">
    Complete installation guide for production deployment
  </Card>

  <Card title="How it works" icon="diagram-project" href="/how-it-works">
    Understanding the architecture and data flow
  </Card>

  <Card title="API reference" icon="code" href="/api/overview">
    Complete API documentation for all endpoints
  </Card>
</CardGroup>

## 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)
```

<Note>
  The extension uses Manifest V3, which is required for all new Chrome extensions.
</Note>

## 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

<CardGroup cols={2}>
  <Card title="Set up locally" icon="laptop-code" href="/quickstart">
    Start the server and load the extension in under 5 minutes
  </Card>

  <Card title="Deploy to production" icon="server" href="/installation">
    Configure HTTPS, reverse proxy, and production environment
  </Card>
</CardGroup>