> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/shlokjain2031/email-tracker-extension/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Note>
  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.
</Note>

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:

```bash theme={null}
curl -H "X-Tracker-Token: your-secret-token" \
  http://localhost:8080/dashboard/api/emails
```

Set the expected token using the `DASHBOARD_TOKEN` environment variable:

```bash theme={null}
DASHBOARD_TOKEN=your-secret-token npm start
```

<Warning>
  Requests without a valid token will receive a 401 Unauthorized response.
</Warning>

## List tracked emails

```
GET /dashboard/api/emails
```

Retrieve all tracked emails with aggregated open statistics.

### Request headers

<ParamField header="X-Tracker-Token" type="string" required>
  Authentication token matching the `DASHBOARD_TOKEN` environment variable
</ParamField>

### Response

<ResponseField name="ok" type="boolean" required>
  Indicates whether the request was successful
</ResponseField>

<ResponseField name="items" type="array" required>
  Array of tracked email objects

  <ResponseField name="email_id" type="string">
    Unique identifier for the email
  </ResponseField>

  <ResponseField name="user_id" type="string">
    User who sent the email
  </ResponseField>

  <ResponseField name="recipient" type="string">
    Recipient email address
  </ResponseField>

  <ResponseField name="sender_email" type="string | null">
    Sender email address
  </ResponseField>

  <ResponseField name="sent_at" type="string">
    ISO 8601 timestamp when the email was sent
  </ResponseField>

  <ResponseField name="unique_open_count" type="number">
    Number of unique opens (excluding duplicates and suppressed opens)
  </ResponseField>

  <ResponseField name="total_open_events" type="number">
    Total number of open events (excluding duplicates and suppressed opens)
  </ResponseField>

  <ResponseField name="raw_open_events" type="number">
    Total number of raw open events (including duplicates and suppressed opens)
  </ResponseField>

  <ResponseField name="last_opened_at" type="string | null">
    ISO 8601 timestamp of the most recent open (excluding duplicates and suppressed opens)
  </ResponseField>

  <ResponseField name="opened" type="boolean">
    Whether the email has been opened at least once
  </ResponseField>

  <ResponseField name="created_at" type="string">
    ISO 8601 timestamp when the tracking record was created
  </ResponseField>
</ResponseField>

### Example request

```bash theme={null}
curl -H "X-Tracker-Token: secret123" \
  http://localhost:8080/dashboard/api/emails
```

### Example response

```json theme={null}
{
  "ok": true,
  "items": [
    {
      "email_id": "email_123",
      "user_id": "user_456",
      "recipient": "recipient@example.com",
      "sender_email": "sender@example.com",
      "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

```json theme={null}
{
  "ok": false,
  "error": "Unauthorized"
}
```

## List open events

```
GET /dashboard/api/open-events
```

Retrieve all open events, optionally filtered by email ID.

### Request headers

<ParamField header="X-Tracker-Token" type="string" required>
  Authentication token matching the `DASHBOARD_TOKEN` environment variable
</ParamField>

### Query parameters

<ParamField query="email_id" type="string">
  Optional. Filter open events for a specific email ID
</ParamField>

### Response

<ResponseField name="ok" type="boolean" required>
  Indicates whether the request was successful
</ResponseField>

<ResponseField name="items" type="array" required>
  Array of open event objects (excludes duplicates and sender-suppressed events)

  <ResponseField name="id" type="number">
    Unique identifier for the open event
  </ResponseField>

  <ResponseField name="email_id" type="string">
    Email identifier this event belongs to
  </ResponseField>

  <ResponseField name="user_id" type="string">
    User who sent the email
  </ResponseField>

  <ResponseField name="recipient" type="string">
    Recipient email address
  </ResponseField>

  <ResponseField name="opened_at" type="string">
    ISO 8601 timestamp when the email was opened
  </ResponseField>

  <ResponseField name="ip_address" type="string | null">
    IP address of the client that opened the email
  </ResponseField>

  <ResponseField name="user_agent" type="string | null">
    User agent string from the client
  </ResponseField>

  <ResponseField name="geo_country" type="string | null">
    Country code from IP geolocation (if available)
  </ResponseField>

  <ResponseField name="geo_region" type="string | null">
    Region/state from IP geolocation (if available)
  </ResponseField>

  <ResponseField name="geo_city" type="string | null">
    City from IP geolocation (if available)
  </ResponseField>

  <ResponseField name="latitude" type="number | null">
    Latitude from IP geolocation (if available)
  </ResponseField>

  <ResponseField name="longitude" type="number | null">
    Longitude from IP geolocation (if available)
  </ResponseField>

  <ResponseField name="device_type" type="string">
    Device type detected from user agent
  </ResponseField>

  <ResponseField name="is_duplicate" type="number">
    Whether this event was flagged as a duplicate (0 or 1)
  </ResponseField>

  <ResponseField name="is_sender_suppressed" type="number">
    Whether this event was suppressed by sender (0 or 1)
  </ResponseField>

  <ResponseField name="suppression_reason" type="string | null">
    Reason for suppression (e.g., "mark\_suppress\_next")
  </ResponseField>
</ResponseField>

### Example request (all events)

```bash theme={null}
curl -H "X-Tracker-Token: secret123" \
  http://localhost:8080/dashboard/api/open-events
```

### Example request (filtered by email)

```bash theme={null}
curl -H "X-Tracker-Token: secret123" \
  "http://localhost:8080/dashboard/api/open-events?email_id=email_123"
```

### Example response

```json theme={null}
{
  "ok": true,
  "items": [
    {
      "id": 1,
      "email_id": "email_123",
      "user_id": "user_456",
      "recipient": "recipient@example.com",
      "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

```json theme={null}
{
  "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