update

docs/API.md

@@ -0,0 +1,223 @@
+# 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