Skip to main content
The dashboard endpoints provide access to tracked email data and open events. The HTML dashboard is publicly accessible, while API endpoints require authentication.

​
Dashboard UI

GET /dashboard serves the dashboard HTML interface. This endpoint does not require authentication. Access control should be handled at the reverse proxy level if needed.
Access the dashboard in your browser at http://localhost:8080/dashboard (development) or https://your-domain.com/dashboard (production). The dashboard provides a web interface for viewing tracked emails and analytics without needing to make API calls directly.

​
Authentication

All dashboard endpoints require the X-Tracker-Token header: 
curl -H "X-Tracker-Token: your-secret-token" \
  http://localhost:8080/dashboard/api/emails
Set the expected token using the DASHBOARD_TOKEN environment variable: 
DASHBOARD_TOKEN=your-secret-token npm start
Requests without a valid token will receive a 401 Unauthorized response.

​
List tracked emails

GET /dashboard/api/emails
Retrieve all tracked emails with aggregated open statistics.

​
Request headers

​
X-Tracker-Token
string
required
Authentication token matching the DASHBOARD_TOKEN environment variable

​
Response

​
ok
boolean
required
Indicates whether the request was successful
​
items
array
required
Array of tracked email objects
​
email_id
string
Unique identifier for the email
​
user_id
string
User who sent the email
​
recipient
string
Recipient email address
​
sender_email
string | null
Sender email address
​
sent_at
string
ISO 8601 timestamp when the email was sent
​
unique_open_count
number
Number of unique opens (excluding duplicates and suppressed opens)
​
total_open_events
number
Total number of open events (excluding duplicates and suppressed opens)
​
raw_open_events
number
Total number of raw open events (including duplicates and suppressed opens)
​
last_opened_at
string | null
ISO 8601 timestamp of the most recent open (excluding duplicates and suppressed opens)
​
opened
boolean
Whether the email has been opened at least once
​
created_at
string
ISO 8601 timestamp when the tracking record was created

​
Example request

curl -H "X-Tracker-Token: secret123" \
  http://localhost:8080/dashboard/api/emails

​
Example response

{
  "ok": true,
  "items": [
    {
      "email_id": "email_123",
      "user_id": "user_456",
      "recipient": "[email protected]",
      "sender_email": "[email protected]",
      "sent_at": "2026-03-03T10:30:00.000Z",
      "unique_open_count": 1,
      "total_open_events": 3,
      "raw_open_events": 5,
      "last_opened_at": "2026-03-03T10:35:42.000Z",
      "opened": true,
      "created_at": "2026-03-03T10:30:00.000Z"
    }
  ]
}

​
Error response

{
  "ok": false,
  "error": "Unauthorized"
}

​
List open events

GET /dashboard/api/open-events
Retrieve all open events, optionally filtered by email ID.

​
Request headers

​
X-Tracker-Token
string
required
Authentication token matching the DASHBOARD_TOKEN environment variable

​
Query parameters

​
email_id
string
Optional. Filter open events for a specific email ID

​
Response

​
ok
boolean
required
Indicates whether the request was successful
​
items
array
required
Array of open event objects (excludes duplicates and sender-suppressed events)
​
id
number
Unique identifier for the open event
​
email_id
string
Email identifier this event belongs to
​
user_id
string
User who sent the email
​
recipient
string
Recipient email address
​
opened_at
string
ISO 8601 timestamp when the email was opened
​
ip_address
string | null
IP address of the client that opened the email
​
user_agent
string | null
User agent string from the client
​
geo_country
string | null
Country code from IP geolocation (if available)
​
geo_region
string | null
Region/state from IP geolocation (if available)
​
geo_city
string | null
City from IP geolocation (if available)
​
latitude
number | null
Latitude from IP geolocation (if available)
​
longitude
number | null
Longitude from IP geolocation (if available)
​
device_type
string
Device type detected from user agent
​
is_duplicate
number
Whether this event was flagged as a duplicate (0 or 1)
​
is_sender_suppressed
number
Whether this event was suppressed by sender (0 or 1)
​
suppression_reason
string | null
Reason for suppression (e.g., “mark_suppress_next”)

​
Example request (all events)

curl -H "X-Tracker-Token: secret123" \
  http://localhost:8080/dashboard/api/open-events

​
Example request (filtered by email)

curl -H "X-Tracker-Token: secret123" \
  "http://localhost:8080/dashboard/api/open-events?email_id=email_123"

​
Example response

{
  "ok": true,
  "items": [
    {
      "id": 1,
      "email_id": "email_123",
      "user_id": "user_456",
      "recipient": "[email protected]",
      "opened_at": "2026-03-03T10:35:42.000Z",
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X)",
      "geo_country": "US",
      "geo_region": "California",
      "geo_city": "San Francisco",
      "latitude": 37.7749,
      "longitude": -122.4194,
      "device_type": "mobile",
      "is_duplicate": 0,
      "is_sender_suppressed": 0,
      "suppression_reason": null
    }
  ]
}

​
Error response

{
  "ok": false,
  "error": "Unauthorized"
}

​
Notes

  • Results are ordered by creation date (descending)
  • Open events query excludes duplicate and sender-suppressed events by default
  • All timestamps are in ISO 8601 format
  • Geolocation data is optional and depends on your IP geolocation setup

Build docs developers (and LLMs) love

Get started for freeTalk to us