Skip to main content
This guide will help you set up Email Tracker and send your first tracked email.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js installed (v18 or higher recommended)
  • Chrome browser
  • A Gmail account
  • Git installed

​
Setup steps

1

Clone and install dependencies

Clone the repository and install all dependencies:
git clone <your-fork-or-repo-url>
cd email-tracker
npm install
2

Build workspaces

Build the shared library and server packages:
npm --workspace=shared run build
npm --workspace=server run build
3

Start the server

Start the tracking server with environment variables:
PORT=8090 DASHBOARD_TOKEN=change-me npm --workspace=server run start
Replace change-me with a strong, random token. This token is required to access your dashboard.
Verify the server is running:
curl http://localhost:8090/health
4

Load the Chrome extension

Install the extension in Chrome:
  1. Open Chrome and navigate to chrome://extensions
  2. Enable Developer mode using the toggle in the top right
  3. Click Load unpacked
  4. Select the extension/ folder from your cloned repository
The extension icon should now appear in your Chrome toolbar.
5

Configure the extension

Open the extension popup and configure:
  1. Click the Email Tracker extension icon in your toolbar
  2. Set Tracker Base URL to http://localhost:8090 (for local development)
  3. Set Dashboard Token to match your DASHBOARD_TOKEN from Step 3
  4. Save your settings
Both values must match what you configured when starting the server, or tracking will not work.
6

Send your first tracked email

Test the complete tracking flow:
  1. Go to Gmail
  2. Compose a new email message
  3. Enable tracking (the extension will inject the tracking pixel automatically)
  4. Send the email to yourself or another account
  5. Open the email you just sent
  6. Check the dashboard at http://localhost:8090/dashboard to see the tracking event
Opens by the sender (you) are automatically suppressed and won’t increment the open count, but will still appear in the dashboard for debugging.

​
Next steps

Now that you have Email Tracker running:

Build docs developers (and LLMs) love

Get started for freeTalk to us