sasa-maillist/api/README.md

Mailing List API Documentation

REST API for managing mailing lists and members with token-based authentication.

Overview

This FastAPI-based REST API provides programmatic access to the mailing list system. It's designed for:

• Automation: Scripts and integrations that need to manage lists/members
• Web Interface: Powers the frontend at http://localhost:3000
• Third-party Apps: Any application that needs mailing list management

For most users, the web interface (http://localhost:3000) is more convenient. Use this API when you need programmatic access or automation.

Base URL

http://localhost:8000

Authentication

All endpoints (except / and /health) require Bearer token authentication.

Add the token to request headers:

Authorization: Bearer your_api_token_here

Set your API token in .env:

API_TOKEN=your_secure_token_here

Endpoints

Health Check

GET /health

• No authentication required
• Returns API and database status

curl http://localhost:8000/health

Mailing Lists

GET /lists

• Get all mailing lists

curl -H "Authorization: Bearer your_token" http://localhost:8000/lists

GET /lists/{list_id}

• Get a specific mailing list

curl -H "Authorization: Bearer your_token" http://localhost:8000/lists/1

POST /lists

• Create a new mailing list

curl -X POST http://localhost:8000/lists \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "list_name": "Developers",
    "list_email": "dev@lists.sasalliance.org",
    "description": "Developer discussions",
    "active": true
  }'

PATCH /lists/{list_id}

• Update a mailing list

curl -X PATCH http://localhost:8000/lists/1 \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "active": false
  }'

DELETE /lists/{list_id}

• Delete a mailing list

curl -X DELETE http://localhost:8000/lists/1 \
  -H "Authorization: Bearer your_token"

Members

GET /members

• Get all members

curl -H "Authorization: Bearer your_token" http://localhost:8000/members

GET /members/{member_id}

• Get a specific member

curl -H "Authorization: Bearer your_token" http://localhost:8000/members/1

POST /members

• Create a new member

curl -X POST http://localhost:8000/members \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john.doe@example.com",
    "active": true
  }'

PATCH /members/{member_id}

• Update a member

curl -X PATCH http://localhost:8000/members/1 \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Q. Doe",
    "active": true
  }'

DELETE /members/{member_id}

• Delete a member

curl -X DELETE http://localhost:8000/members/1 \
  -H "Authorization: Bearer your_token"

Subscriptions

GET /lists/{list_id}/members

• Get all members of a specific list

curl -H "Authorization: Bearer your_token" http://localhost:8000/lists/1/members

POST /subscriptions

• Subscribe a member to a list

curl -X POST http://localhost:8000/subscriptions \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "list_email": "community@lists.sasalliance.org",
    "member_email": "john.doe@example.com",
    "active": true
  }'

DELETE /subscriptions?list_email=X&member_email=Y

• Unsubscribe a member from a list

curl -X DELETE "http://localhost:8000/subscriptions?list_email=community@lists.sasalliance.org&member_email=john.doe@example.com" \
  -H "Authorization: Bearer your_token"

Interactive Documentation

Once the API is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

These provide interactive API documentation where you can test endpoints directly in your browser.

Example Workflow

1. Create a new member:

curl -X POST http://localhost:8000/members \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Smith", "email": "jane@example.com", "active": true}'

2. Create a new mailing list:

curl -X POST http://localhost:8000/lists \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"list_name": "Marketing", "list_email": "marketing@lists.sasalliance.org", "active": true}'

3. Subscribe the member to the list:

curl -X POST http://localhost:8000/subscriptions \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"list_email": "marketing@lists.sasalliance.org", "member_email": "jane@example.com"}'

4. Verify the subscription:

curl -H "Authorization: Bearer your_token" http://localhost:8000/lists/1/members

Error Responses

• 401 Unauthorized - Invalid or missing authentication token
• 404 Not Found - Resource not found
• 400 Bad Request - Invalid request data
• 500 Internal Server Error - Database or server error

Notes

• All changes take effect immediately in Postfix (no reload needed)
• Email validation is enforced on all email fields
• Deleting a list or member also removes associated subscriptions (CASCADE)