Munich-news/docs/API.md

API Reference

Tracking Endpoints

Track Email Open

GET /api/track/pixel/<tracking_id>

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

Response: Image (image/png)

Track Link Click

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

GET /api/analytics/newsletter/<newsletter_id>

Returns comprehensive metrics for a specific newsletter.

Response:

{
  "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

GET /api/analytics/article/<article_url>

Returns performance metrics for a specific article.

Response:

{
  "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

GET /api/analytics/subscriber/<email>

Returns activity status and engagement metrics for a subscriber.

Response:

{
  "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

DELETE /api/tracking/subscriber/<email>

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

Response:

{
  "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

POST /api/tracking/anonymize

Anonymizes tracking data older than the retention period.

Request Body (optional):

{
  "retention_days": 90
}

Response:

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

Opt Out of Tracking

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

Disables tracking for a subscriber.

Response:

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

Opt In to Tracking

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

Re-enables tracking for a subscriber.

Response:

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

Examples

Using curl

# 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

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:

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

HTTP Status Codes:

• 200 - Success
• 404 - Not found
• 500 - Server error