# API Reference

## Tracking Endpoints

### Track Email Open

```http
GET /api/track/pixel/<tracking_id>
```

Returns a 1x1 transparent PNG and logs the email open event.

**Response**: Image (image/png)

### Track Link Click

```http
GET /api/track/click/<tracking_id>
```

Logs the click event and redirects to the original article URL.

**Response**: 302 Redirect

## Analytics Endpoints

### Get Newsletter Metrics

```http
GET /api/analytics/newsletter/<newsletter_id>
```

Returns comprehensive metrics for a specific newsletter.

**Response**:
```json
{
  "newsletter_id": "2024-01-15",
  "total_sent": 100,
  "total_opened": 75,
  "open_rate": 75.0,
  "unique_openers": 70,
  "total_clicks": 45,
  "unique_clickers": 30,
  "click_through_rate": 30.0
}
```

### Get Article Performance

```http
GET /api/analytics/article/<article_url>
```

Returns performance metrics for a specific article.

**Response**:
```json
{
  "article_url": "https://example.com/article",
  "total_sent": 100,
  "total_clicks": 25,
  "click_rate": 25.0,
  "unique_clickers": 20,
  "newsletters": ["2024-01-15", "2024-01-16"]
}
```

### Get Subscriber Activity

```http
GET /api/analytics/subscriber/<email>
```

Returns activity status and engagement metrics for a subscriber.

**Response**:
```json
{
  "email": "user@example.com",
  "status": "active",
  "last_opened_at": "2024-01-15T10:30:00",
  "last_clicked_at": "2024-01-15T10:35:00",
  "total_opens": 45,
  "total_clicks": 20,
  "newsletters_received": 50,
  "newsletters_opened": 45
}
```

## Privacy Endpoints

### Delete Subscriber Data

```http
DELETE /api/tracking/subscriber/<email>
```

Deletes all tracking data for a subscriber (GDPR compliance).

**Response**:
```json
{
  "success": true,
  "message": "All tracking data deleted for user@example.com",
  "deleted_counts": {
    "newsletter_sends": 50,
    "link_clicks": 25,
    "subscriber_activity": 1
  }
}
```

### Anonymize Old Data

```http
POST /api/tracking/anonymize
```

Anonymizes tracking data older than the retention period.

**Request Body** (optional):
```json
{
  "retention_days": 90
}
```

**Response**:
```json
{
  "success": true,
  "message": "Anonymized tracking data older than 90 days",
  "anonymized_counts": {
    "newsletter_sends": 1250,
    "link_clicks": 650
  }
}
```

### Opt Out of Tracking

```http
POST /api/tracking/subscriber/<email>/opt-out
```

Disables tracking for a subscriber.

**Response**:
```json
{
  "success": true,
  "message": "Subscriber user@example.com has opted out of tracking"
}
```

### Opt In to Tracking

```http
POST /api/tracking/subscriber/<email>/opt-in
```

Re-enables tracking for a subscriber.

**Response**:
```json
{
  "success": true,
  "message": "Subscriber user@example.com has opted in to tracking"
}
```

## Examples

### Using curl

```bash
# Get newsletter metrics
curl http://localhost:5001/api/analytics/newsletter/2024-01-15

# Delete subscriber data
curl -X DELETE http://localhost:5001/api/tracking/subscriber/user@example.com

# Anonymize old data
curl -X POST http://localhost:5001/api/tracking/anonymize \
  -H "Content-Type: application/json" \
  -d '{"retention_days": 90}'

# Opt out of tracking
curl -X POST http://localhost:5001/api/tracking/subscriber/user@example.com/opt-out
```

### Using Python

```python
import requests

# Get newsletter metrics
response = requests.get('http://localhost:5001/api/analytics/newsletter/2024-01-15')
metrics = response.json()
print(f"Open rate: {metrics['open_rate']}%")

# Delete subscriber data
response = requests.delete('http://localhost:5001/api/tracking/subscriber/user@example.com')
result = response.json()
print(result['message'])
```

## Error Responses

All endpoints return standard error responses:

```json
{
  "success": false,
  "error": "Error message here"
}
```

HTTP Status Codes:
- `200` - Success
- `404` - Not found
- `500` - Server error