Munich-news/docs/API.md

API Reference

Complete API documentation for Munich News Daily.

---

Admin API

Base URL: http://localhost:5001

Trigger Crawler

Manually fetch new articles.

POST /api/admin/trigger-crawl
Content-Type: application/json

{
  "max_articles": 10
}

Example:

curl -X POST http://localhost:5001/api/admin/trigger-crawl \
  -H "Content-Type: application/json" \
  -d '{"max_articles": 5}'

---

Send Test Email

Send newsletter to specific email.

POST /api/admin/send-test-email
Content-Type: application/json

{
  "email": "test@example.com",
  "max_articles": 10
}

Example:

curl -X POST http://localhost:5001/api/admin/send-test-email \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.com"}'

---

Send Newsletter to All Subscribers

Send newsletter to all active subscribers.

POST /api/admin/send-newsletter
Content-Type: application/json

{
  "max_articles": 10
}

Response:

{
  "success": true,
  "message": "Newsletter sent successfully to 45 subscribers",
  "subscriber_count": 45,
  "max_articles": 10
}

Example:

curl -X POST http://localhost:5001/api/admin/send-newsletter \
  -H "Content-Type: application/json" \
  -d '{"max_articles": 10}'

---

Get System Stats

GET /api/admin/stats

Response:

{
  "articles": {
    "total": 150,
    "with_summary": 120,
    "today": 15
  },
  "subscribers": {
    "total": 50,
    "active": 45
  },
  "rss_feeds": {
    "total": 4,
    "active": 4
  },
  "tracking": {
    "total_sends": 200,
    "total_opens": 150,
    "total_clicks": 75
  }
}

Example:

curl http://localhost:5001/api/admin/stats

---

Public API

Subscribe

POST /api/subscribe
Content-Type: application/json

{
  "email": "user@example.com"
}

Example:

curl -X POST http://localhost:5001/api/subscribe \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

---

Unsubscribe

POST /api/unsubscribe
Content-Type: application/json

{
  "email": "user@example.com"
}

Example:

curl -X POST http://localhost:5001/api/unsubscribe \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

---

Subscriber Status System

Status Values

Status	Description	Receives Newsletters
active	Subscribed	✅ Yes
inactive	Unsubscribed	❌ No

Database Schema

{
  _id: ObjectId("..."),
  email: "user@example.com",
  subscribed_at: ISODate("2025-11-11T15:50:29.478Z"),
  status: "active"  // or "inactive"
}

How It Works

Subscribe:

• Creates subscriber with status: 'active'
• If already exists and inactive, reactivates

Unsubscribe:

• Updates status: 'inactive'
• Subscriber data preserved (soft delete)

Newsletter Sending:

• Only sends to status: 'active' subscribers
• Query: {status: 'active'}

Check Active Subscribers

curl http://localhost:5001/api/admin/stats | jq '.subscribers'
# Output: {"total": 10, "active": 8}

---

Workflows

Complete Newsletter Workflow

# 1. Check stats
curl http://localhost:5001/api/admin/stats

# 2. Crawl articles
curl -X POST http://localhost:5001/api/admin/trigger-crawl \
  -H "Content-Type: application/json" \
  -d '{"max_articles": 10}'

# 3. Wait for crawl
sleep 60

# 4. Send newsletter
curl -X POST http://localhost:5001/api/admin/send-newsletter \
  -H "Content-Type: application/json" \
  -d '{"max_articles": 10}'

Test Newsletter

# Send test to yourself
curl -X POST http://localhost:5001/api/admin/send-test-email \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.com", "max_articles": 3}'

---

Error Responses

All endpoints return standard error format:

{
  "success": false,
  "error": "Error message here"
}

HTTP Status Codes:

• 200 - Success
• 400 - Bad request
• 404 - Not found
• 500 - Server error

---

Security

⚠️ Production Recommendations:

1. Add Authentication

   @require_api_key
   def admin_endpoint():
       # ...
   

2. Rate Limiting

   • Prevent abuse
   • Limit newsletter sends

3. IP Whitelisting

   • Restrict admin endpoints
   • Use firewall rules

4. HTTPS Only

   • Use reverse proxy
   • SSL/TLS certificates

5. Audit Logging

   • Log all admin actions
   • Monitor for suspicious activity

---

Testing

Use the test script:

./test-newsletter-api.sh

Or test manually:

# Health check
curl http://localhost:5001/health

# Stats
curl http://localhost:5001/api/admin/stats

# Test email
curl -X POST http://localhost:5001/api/admin/send-test-email \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

---

See SETUP.md for configuration and SECURITY.md for security best practices.