122 lines
3.2 KiB
Markdown
122 lines
3.2 KiB
Markdown
# 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 |
|