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

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