Skip to main content
The Email Tracker Server provides a REST API for tracking email opens and managing tracking data.

​
Base URL

The server runs on port 8080 by default. You can configure the port using the PORT environment variable:
The base URL will be:
For production deployments, use your server’s domain:

​
Authentication

The Email Tracker API uses two authentication methods depending on the endpoint:

​
Dashboard API authentication

Dashboard endpoints require the X-Tracker-Token header for authentication:
Set the expected token using the DASHBOARD_TOKEN environment variable:
If DASHBOARD_TOKEN is not set, all dashboard API requests will be rejected with a 401 Unauthorized response.

​
Tracking pixel authentication

The tracking pixel endpoint (/t/:token.gif) uses signed tokens embedded in the URL. These tokens are generated by the encodeTrackingToken() function from @email-tracker/shared and include:
  • Email ID
  • User ID
  • Recipient email
  • Sender email
  • Sent timestamp
No additional authentication headers are required for pixel tracking.

​
API endpoints

The Email Tracker Server provides the following endpoint categories:
  • Tracking: Pixel endpoint for recording email opens
  • Dashboard: Retrieve tracked emails and open events
  • Suppression: Control sender suppression for Gmail proxy handling
  • Metrics: Debug endpoints for monitoring suppression signals and latency

​
Health check

The server includes a basic health check endpoint:
Response:

​
Error responses

API errors return JSON responses with the following structure:
Common HTTP status codes:
  • 200 - Success
  • 400 - Bad request (missing or invalid parameters)
  • 401 - Unauthorized (missing or invalid authentication token)
  • 500 - Internal server error