update

2025-11-11 17:40:29 +01:00
parent 901e8166cd
commit 75a6973a49
11 changed files with 1028 additions and 21 deletions
--- a/NEWSLETTER_API_UPDATE.md
+++ b/NEWSLETTER_API_UPDATE.md
@@ -0,0 +1,205 @@
+# Newsletter API Update
+
+## Summary
+
+Added a new API endpoint to send newsletters to all active subscribers instead of requiring a specific email address.
+
+## New Endpoint
+
+### Send Newsletter to All Subscribers
+
+```http
+POST /api/admin/send-newsletter
+```
+
+**Request Body** (optional):
+```json
+{
+  "max_articles": 10
+}
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "message": "Newsletter sent successfully to 45 subscribers",
+  "subscriber_count": 45,
+  "max_articles": 10,
+  "output": "... sender output ...",
+  "errors": ""
+}
+```
+
+## Usage Examples
+
+### Send Newsletter to All Subscribers
+
+```bash
+# Send with default settings (10 articles)
+curl -X POST http://localhost:5001/api/admin/send-newsletter \
+  -H "Content-Type: application/json"
+
+# Send with custom article count
+curl -X POST http://localhost:5001/api/admin/send-newsletter \
+  -H "Content-Type: application/json" \
+  -d '{"max_articles": 15}'
+```
+
+### Complete Workflow
+
+```bash
+# 1. Check subscriber count
+curl http://localhost:5001/api/admin/stats | jq '.subscribers'
+
+# 2. Crawl fresh articles
+curl -X POST http://localhost:5001/api/admin/trigger-crawl \
+  -H "Content-Type: application/json" \
+  -d '{"max_articles": 10}'
+
+# 3. Wait for crawl to complete
+sleep 60
+
+# 4. Send newsletter to all active subscribers
+curl -X POST http://localhost:5001/api/admin/send-newsletter \
+  -H "Content-Type: application/json" \
+  -d '{"max_articles": 10}'
+```
+
+## Comparison with Test Email
+
+### Send Test Email (Existing)
+- Sends to **one specific email address**
+- Useful for testing newsletter content
+- No tracking recorded in database
+- Fast (single email)
+
+```bash
+curl -X POST http://localhost:5001/api/admin/send-test-email \
+  -H "Content-Type: application/json" \
+  -d '{"email": "test@example.com"}'
+```
+
+### Send Newsletter (New)
+- Sends to **all active subscribers**
+- Production newsletter sending
+- Full tracking (opens, clicks)
+- May take time for large lists
+
+```bash
+curl -X POST http://localhost:5001/api/admin/send-newsletter \
+  -H "Content-Type: application/json"
+```
+
+## Features
+
+### Subscriber Filtering
+- Only sends to subscribers with `status: 'active'`
+- Skips inactive, unsubscribed, or bounced subscribers
+- Returns error if no active subscribers found
+
+### Tracking
+- Includes tracking pixel for open tracking
+- Includes click tracking for all article links
+- Records send time and newsletter ID
+- Stores in `newsletter_sends` collection
+
+### Error Handling
+- Validates subscriber count before sending
+- Returns detailed error messages
+- Includes sender output and errors in response
+- 5-minute timeout for large lists
+
+## Testing
+
+### Interactive Test Script
+
+```bash
+./test-newsletter-api.sh
+```
+
+This script will:
+1. Show current subscriber stats
+2. Optionally send test email to your address
+3. Optionally send newsletter to all subscribers
+
+### Manual Testing
+
+```bash
+# 1. Check subscribers
+curl http://localhost:5001/api/admin/stats
+
+# 2. Send newsletter
+curl -X POST http://localhost:5001/api/admin/send-newsletter \
+  -H "Content-Type: application/json" \
+  -d '{"max_articles": 2}'
+
+# 3. Check results
+curl http://localhost:5001/api/admin/stats
+```
+
+## Security Considerations
+
+⚠️ **Important**: This endpoint sends emails to real subscribers!
+
+### Recommendations
+
+1. **Add Authentication**
+   ```python
+   @require_api_key
+   def send_newsletter():
+       # ...
+   ```
+
+2. **Rate Limiting**
+   - Prevent accidental multiple sends
+   - Limit to once per hour/day
+
+3. **Confirmation Required**
+   - Add confirmation step in UI
+   - Log all newsletter sends
+
+4. **Dry Run Mode**
+   ```json
+   {
+     "max_articles": 10,
+     "dry_run": true  // Preview without sending
+   }
+   ```
+
+5. **Audit Logging**
+   - Log who triggered the send
+   - Log timestamp and parameters
+   - Track success/failure
+
+## Files Modified
+
+- ✅ `backend/routes/admin_routes.py` - Added new endpoint
+- ✅ `docs/ADMIN_API.md` - Updated documentation
+- ✅ `test-newsletter-api.sh` - Created test script
+
+## API Endpoints Summary
+
+| Endpoint | Purpose | Recipient |
+|----------|---------|-----------|
+| `/api/admin/send-test-email` | Test newsletter | Single email (specified) |
+| `/api/admin/send-newsletter` | Production send | All active subscribers |
+| `/api/admin/trigger-crawl` | Fetch articles | N/A |
+| `/api/admin/stats` | System stats | N/A |
+
+## Next Steps
+
+1. **Test the endpoint:**
+   ```bash
+   ./test-newsletter-api.sh
+   ```
+
+2. **Add authentication** (recommended for production)
+
+3. **Set up monitoring** for newsletter sends
+
+4. **Create UI** for easier newsletter management
+
+## Documentation
+
+See [docs/ADMIN_API.md](docs/ADMIN_API.md) for complete API documentation.