> ## 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.

# API overview

> Introduction to the Email Tracker Server API, including base URL configuration and authentication

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:

```bash theme={null}
PORT=3000 npm start
```

The base URL will be:

```
http://localhost:8080
```

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:

```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>
  If `DASHBOARD_TOKEN` is not set, all dashboard API requests will be rejected with a 401 Unauthorized response.
</Warning>

### 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:

```bash theme={null}
curl http://localhost:8080/health
```

Response:

```json theme={null}
{
  "ok": true
}
```

## Error responses

API errors return JSON responses with the following structure:

```json theme={null}
{
  "ok": false,
  "error": "Error message description"
}
```

Common HTTP status codes:

* `200` - Success
* `400` - Bad request (missing or invalid parameters)
* `401` - Unauthorized (missing or invalid authentication token)
* `500` - Internal server error