The dashboard's engine,
exposed as an HTTP API.

# GET /campaigns · campaigns:read
  status        draft | active | paused | completed | archived
  search        name contains
  sort          newest | oldest | name_asc | sent_desc | reply_rate_desc
  page          1, 2, 3 …
→ data[]: id, name, status, totalLeads, totalSent, totalOpened,
          totalClicked, totalReplied, startedAt, createdAt
  pagination: page, pageSize, totalPages, total

# POST /campaigns · campaigns:write · 201
  name          string    required
  mailboxIds    uuid[]    required, one or more of your mailboxes
  seqSteps      step[]    required, one or more
    delayDays   number    required
    delayHours  number    default 0
    variants    array     required: subject, body, variantGroup?, weight?
                          for an A/B test give two or more variants, each with
                          its own variantGroup ("a", "b", ...); left out, the
                          step is not split and only one variant sends. Use
                          the same letters on every step: a lead keeps one
                          letter for the whole sequence
  leads         lead[]    optional: email, firstName, lastName, company,
                          title, website, tags, customFields
  trackOpens    boolean   default true
  trackClicks   boolean   default false
  stopOnReply   boolean   default true
  scheduleJson  object    optional: sendWindowStart, sendWindowEnd, timezone,
                          skipWeekends and the other campaign options
  launchNow     boolean   default false; true also needs campaigns:execute
→ data: { id }

# GET /campaigns/:id · campaigns:read
→ data: { campaign, stats, sequence, dailyVolume,
          replyClassifications, recentActivity }

# POST /campaigns/:id/start | /pause | /resume · campaigns:execute
→ { "ok": true }
  start:  a draft with a step, a subject on step 1 and an active or warming mailbox
  pause:  an active campaign, and it still works on a paused workspace
  resume: a paused campaign

# GET /leads · leads:read
  status        active | unsubscribed | bounced | suppressed
  search        email, name or company contains
  sort          newest | oldest | name_asc | name_desc | company_asc
  page          1, 2, 3 …
→ data[]: id, email, firstName, lastName, company, title,
          source, status, customFields, createdAt
  pagination: page, pageSize, totalPages, total

# POST /leads · leads:write · 201
  email         string    required
  firstName     string    optional, and so are lastName, company, title
  status        string    default active
→ data: the lead · 409 conflict when the address is already a lead

# GET /leads/:id · leads:read
→ data: { lead, enrollments, stats, timeline }

# PATCH /leads/:id · leads:write
  status        string    unsubscribed or suppressed also stops its sends
  customFields  object    replaces the stored object
→ data: the lead

# POST /leads/:id/enroll · leads:write · 201
  campaignId    uuid      required; the lead and the campaign must be active
→ data: { campaignLeadId } · 409 conflict when already enrolled

# POST /leads/import · leads:write · 201
  rows          lead[]    required: email, firstName, lastName, company,
                          title, tags (string[]), customFields (object)
  globalTags    string[]  optional, added to every row
→ data: { inserted, skipped }   skipped = duplicates, in the batch or already stored

# GET /mailboxes · mailboxes:read · Gmail, Microsoft 365 and SMTP, not paged
  status        pending | active | warming | paused | error | disconnected
  provider      gmail | m365 | smtp
  tier          healthy | watch | risk | unscored
  email         one exact address, to check before you push it
  sort          reputation_desc | reputation_asc | sent_today_desc |
                connected_newest | email_asc
→ data: { mailboxes: [{ id, email, displayName, provider, status,
            dailyLimit, dailySentCount, warmupEnabled, warmupDailyTarget,
            reputationScore, connectedAt }], summary }

# POST /mailboxes · mailboxes:write · snake_case body
  email           string   required, on a business domain
  smtp_host       string   required
  smtp_port       number   required
  smtp_password   string   required
  smtp_username   string   default: the email
  imap_host       string   default: smtp_host with smtp. swapped for imap.
  imap_port       number   default 993
  imap_username   string   default: the SMTP username
  imap_password   string   default: the SMTP password
  first_name      string   optional, and so is last_name
  daily_limit     number   1 to 500, default 30
  warmup_enabled  boolean  optional
  warmup_daily_target  number  1 to 200
→ 200 data: { id, email, created }   created false = credentials refreshed
  SMTP and IMAP are tested right after the response
  409 conflict when Google or Microsoft already holds the address

# GET /threads · threads:read · real replies, newest first
  status          active (default) | archived | snoozed | all
  classification  positive | negative | question | ooo | unsubscribe |
                  forward | bounce | other
  mailboxId       uuid
  campaignId      uuid
  search          subject, sender or reply text contains
  warmup          only, for the warmup pool's threads instead
  page            1, 2, 3 …
→ data[]: id, subject, fromEmail, fromName, latestClassification,
          latestMessageAt, messageCount, status, preview, mailboxEmail,
          campaignName, hasAiDraft, hasUnread
  pagination: page, pageSize, totalPages, total

# GET /threads/:id · threads:read
→ data: { id, subject, status, latestClassification, isWarmup,
          messages[], lead, campaignLead,
          aiDraft: { body, inboundMessageId } or null }
  aiDraft.body is plain text with line breaks, not HTML

# POST /threads/:id/reply · threads:reply
  to            string    required, the address you are answering
  bodyHtml      string    required
→ data: { providerMessageId }
  sent as "Re: subject" from the thread's mailbox, threaded on the last reply;
  a reply sent this way retires the AI draft

# Every refusal has the same body
{
  "error":   "validation_error",
  "message": "mailboxIds: mailboxIds must name at least one mailbox",
  "field":   "mailboxIds"
}

400  invalid_json · validation_error · invalid_request
401  unauthorized          missing, malformed, revoked or expired key
403  forbidden             the key lacks the scope ("Missing scope: leads:write"),
                            or the workspace is at its mailbox cap
403  workspace_inactive    a write on a paused workspace; reads and pause still work
403  limit_reached         the plan's lead cap
404  not_found             no such id in this key's workspace
409  conflict              already a lead, already enrolled, or an OAuth mailbox
500  internal_error        an error on our side