sasa-maillist/api/README.md

# Mailing List API Documentation

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

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

```bash
curl http://localhost:8000/health
```

### Mailing Lists

**GET** `/lists`
- Get all mailing lists

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

**GET** `/lists/{list_id}`
- Get a specific mailing list

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

**POST** `/lists`
- Create a new mailing list

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

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

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

### Members

**GET** `/members`
- Get all members

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

**GET** `/members/{member_id}`
- Get a specific member

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

**POST** `/members`
- Create a new member

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

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

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

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

**POST** `/subscriptions`
- Subscribe a member to a list

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

```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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)