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:
https://tracker.yourdomain.com
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:
curl -H "X-Tracker-Token: your-secret-token" \
http://localhost:8080/dashboard/api/emails
DASHBOARD_TOKEN environment variable:
DASHBOARD_TOKEN=your-secret-token npm start
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:
curl http://localhost:8080/health
Error responses
API errors return JSON responses with the following structure:
{
"ok": false,
"error": "Error message description"
}
200 - Success400 - Bad request (missing or invalid parameters)401 - Unauthorized (missing or invalid authentication token)500 - Internal server error