warmbox/docs/13-api-evolution.md

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

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

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

Auth evolution

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