# API Evolution

## Current endpoints (v0)

| Method | Path |
|--------|------|
| GET | `/health` |
| POST/GET/PATCH/DELETE | `/api/inboxes` |
| POST | `/api/inboxes/:id/test` |
| GET | `/api/logs` |
| GET/PATCH | `/api/settings` |

## Target REST API (v1)

### Mailboxes

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/mailboxes` | Create (role: primary \| satellite) |
| GET | `/api/mailboxes` | List with filters |
| GET | `/api/mailboxes/:id` | Detail |
| PATCH | `/api/mailboxes/:id` | Update |
| DELETE | `/api/mailboxes/:id` | Remove |
| POST | `/api/mailboxes/:id/test` | SMTP + IMAP test |
| POST | `/api/mailboxes/:id/dns-check` | SPF/DKIM/DMARC (future) |

### Campaigns

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/campaigns` | Create warmup campaign |
| GET | `/api/campaigns` | List |
| GET | `/api/campaigns/:id` | Detail + stats summary |
| PATCH | `/api/campaigns/:id` | Update recipe/limits |
| POST | `/api/campaigns/:id/start` | Activate |
| POST | `/api/campaigns/:id/pause` | Pause |
| POST | `/api/campaigns/:id/complete` | End campaign |
| DELETE | `/api/campaigns/:id` | Delete draft only |

### Campaign satellites

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/campaigns/:id/satellites` | List assigned |
| POST | `/api/campaigns/:id/satellites` | Assign `{ mailboxId }` |
| DELETE | `/api/campaigns/:id/satellites/:mailboxId` | Unassign |

### Statistics

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/campaigns/:id/stats/today` | Today's metrics |
| GET | `/api/campaigns/:id/stats/daily` | Time series |
| GET | `/api/campaigns/:id/stats` | Summary + range |
| GET | `/api/workspace/overview` | All primaries at a glance |

### Logs

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/logs` | Paginated (existing, add campaignId filter) |

### Recipes

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/recipes/preview` | Preview schedule without saving |
| GET | `/api/recipes/templates` | Default params per recipe type |

### Jobs (operator)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/jobs/dispatcher/run` | Manual trigger (dev) |
| POST | `/api/jobs/rescuer/run` | Manual trigger (dev) |

### Settings

| Method | Path | Description |
|--------|------|-------------|
| GET/PATCH | `/api/settings` | Global + AI config |

## Create campaign example

```json
POST /api/campaigns
{
  "primaryMailboxId": "clx...",
  "name": "FillCare hello@",
  "recipe": "grow",
  "durationDays": 30,
  "minEmailsPerDay": 1,
  "maxEmailsPerDay": 40,
  "replyRatePercent": 30,
  "satelliteMailboxIds": ["clx...", "clx...", "clx..."],
  "timezone": "America/Vancouver",
  "sendWindowStart": "08:00",
  "sendWindowEnd": "18:00"
}
```

## Backward compatibility

- Keep `/api/inboxes` as alias to `/api/mailboxes` for one release
- Deprecation header on v0 routes

## Error format

```json
{
  "error": "Human message",
  "code": "CAMPAIGN_SATELLITE_MIN",
  "details": { "minRequired": 2 }
}
```

## Auth evolution

| Phase | Auth |
|-------|------|
| Self-hosted | Optional `x-api-key` |
| SaaS | JWT + workspace header |