Dashboard endpoints

Retrieve tracked emails and open events from the Email Tracker API

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": "[e-mail]",
      "sender_email": "[e-mail]",
      "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": "[e-mail]",
      "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