Munich-news/NEWSLETTER_API_UPDATE.md

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

POST /api/admin/send-newsletter

Request Body (optional):

{
  "max_articles": 10
}

Response:

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

# 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

# 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)

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

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

./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

# 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

   @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

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

   ./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 for complete API documentation.