224 lines
3.8 KiB
Markdown
224 lines
3.8 KiB
Markdown
# 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
|