{ "components": { "securitySchemes": { "key": { "in": "header", "name": "X-API-Key", "type": "apiKey" } } }, "info": { "title": "Sales Sequencer API", "version": "1", "description": "Every Sales Sequencer action over HTTP. Each call runs as the API key's creator, with that user's role, in the key's workspace. Auth: X-API-Key header." }, "openapi": "3.0.3", "paths": { "/analytics": { "get": { "description": "Daily and hourly sends/replies plus breakdowns by campaign, mailbox and domain. Dates are IST days. 'from' and 'to' take effect only when BOTH are given, otherwise the range preset applies (default 14d). The range is capped at 365 days and the end at today. A bad date returns 400 {error}. Cached about 20 seconds.\n\n**Minimum role:** `view` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "spa_analytics", "parameters": [ { "description": "Preset: today, yesterday, 7d, 14d (default), 30d, 90d.", "in": "query", "name": "range", "required": false, "schema": { "type": "string" } }, { "description": "Start date YYYY-MM-DD (needs 'to').", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "End date YYYY-MM-DD (needs 'from').", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "Limit to one campaign id.", "in": "query", "name": "campaign", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "JSON {range:{preset, from, to, days}, campaign, totals:{sent, reached, failed, replies, positive, sent_per_day, reply_per_1k, emails_per_positive}, lifetime:{reached, bounced, pending, bounce_rate}, series, hours:[{hour,sent,replies}], stages, by_campaign, by_mailbox (top 200), by_domain, campaigns}." } }, "summary": "Analytics for a date range", "tags": [ "Analytics" ], "x-destructive": false, "x-min-role": "view" } }, "/campaigns/list": { "get": { "description": "All campaigns in the workspace, archived ones included (status \"archived\"), pinned first then newest first, with per-campaign counts and rates. Replies exclude automated/out-of-office. bounce_rate = bounced / reached (distinct leads sent to), the same number the web app shows; it counts real recipient bounces only. sender_bounced / sender_bounce_rate count leads whose delivery failed on our side (status sender_blocked) right now; sender_blocked_total / sender_blocked_total_rate count every our-side block ever (never decreases, survives re-queues), over the same reached. Pass pinned=1 for pinned campaigns only.\n\n**Minimum role:** `view` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "spa_campaigns", "parameters": [ { "description": "1 = only pinned campaigns.", "in": "query", "name": "pinned", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "JSON {campaigns:[{id, name, status, created_at, pinned, steps, mailboxes, leads, pending, reached, emails_sent, sent_today, replied, auto_replies, positive, bounced, reply_rate, bounce_rate, sender_bounced, sender_bounce_rate, sender_blocked_total, sender_blocked_total_rate, emails_per_positive, expected_additional_positive, progress}]}." } }, "summary": "List campaigns with stats", "tags": [ "Campaigns" ], "x-destructive": false, "x-min-role": "view" } }, "/campaigns/new": { "post": { "description": "Creates a draft campaign in the current workspace. Sends nothing. Refuses an empty name (flash 'Campaign name is required', no campaign created). A non-numeric or negative min_gap_minutes silently falls back to 15.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "campaigns_new_campaign", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "body": { "description": "First-email body (legacy single-email field).", "type": "string" }, "min_gap_minutes": { "description": "Minimum minutes between sends from one mailbox. Default 15.", "type": "integer" }, "name": { "description": "Campaign name.", "type": "string" }, "subject": { "description": "First-email subject (legacy single-email field).", "type": "string" } }, "required": [ "name" ], "type": "object" } } } }, "responses": { "200": { "description": "Redirect to the new campaign (status draft). The new campaign id is in the redirect URL." } }, "summary": "Create a campaign", "tags": [ "Campaigns" ], "x-destructive": false, "x-min-role": "edit" } }, "/campaigns/{campaign_id}/archive": { "post": { "description": "Sets status to archived: it never sends, cannot be launched, and the campaigns page lists it under Archived only. Leads, sends and replies are kept. Works from any status.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "campaigns_archive_campaign", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "redirect_to": { "description": "Send 'list' to redirect to the campaign list (UI only).", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Redirect; flash 'Campaign archived'." } }, "summary": "Archive a campaign", "tags": [ "Campaigns" ], "x-destructive": false, "x-min-role": "edit" } }, "/campaigns/{campaign_id}/backoff-exempt": { "post": { "description": "Sets exempt_from_backoff. When true, this campaign's contacts are left out of the warm-up bounce back-off (the 6-hourly check that rewinds a warming mailbox's ramp when its 14-day bounce rate is 5% or more over at least 10 sends): its bounces and its sends count in neither the rate nor the sample. Sends, contacts and statuses are not touched. Omitting the field or sending false stores false. New and cloned campaigns start at false. 404 if the campaign is not in the workspace.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "campaigns_set_backoff_exempt", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "exempt_from_backoff": { "description": "true to exempt this campaign, false to count its bounces again.", "type": "boolean" } }, "required": [ "exempt_from_backoff" ], "type": "object" } } } }, "responses": { "200": { "description": "Redirect; flash 'exempt_from_backoff = true' or 'exempt_from_backoff = false' (the value now stored)." } }, "summary": "Exempt a campaign from the bounce back-off", "tags": [ "Campaigns" ], "x-destructive": false, "x-min-role": "edit" } }, "/campaigns/{campaign_id}/clone": { "post": { "description": "Creates a draft copy named ' (copy)' with the same sequence, schedule, cc/bcc and mailbox assignment. Leads are NOT copied. Sends nothing.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "campaigns_clone_campaign", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Redirect to the new campaign's sequence tab (new id in the URL)." } }, "summary": "Clone a campaign", "tags": [ "Campaigns" ], "x-destructive": false, "x-min-role": "edit" } }, "/campaigns/{campaign_id}/detail": { "get": { "description": "Settings, sequence, stats, 30-day series, stage counts and assigned mailboxes. Cached up to 60 seconds per workspace (cache is dropped after campaign writes). 404 JSON if not in the workspace.\n\n**Minimum role:** `view` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "spa_campaign_detail", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "JSON {campaign:{id, name, status, created_at, settings:{min_gap_minutes, max_gap_minutes, send_hour_start, send_hour_end, send_tz_offset, send_tz_label, send_days, send_day_labels, cc, bcc}, sequence:[{wait, variants:[{subject, body}]}]}, stats:{total, sent, replied, bounced, failed, pending, positive, emails_sent, reached, reply_rate, bounce_rate, emails_per_positive, expected_additional_positive, sent_today, replied_status, auto_replies}, series:[{date, label, dow, sent, replies, positive}], stages:{: n}, mailboxes:{assigned, count, rows:[{id, email, status, enabled, daily_limit, sent_today, campaign_sent}]}}." } }, "summary": "Get one campaign in full", "tags": [ "Campaigns" ], "x-destructive": false, "x-min-role": "view" } }, "/campaigns/{campaign_id}/launch": { "post": { "description": "Sets status to active so the scheduler starts sending real email to the campaign's pending contacts. Refuses with flash 'Cannot launch: no pending contacts. Upload leads first.' when there are none (status unchanged).\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `true` (`x-destructive`).", "operationId": "campaigns_launch_campaign", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "redirect_to": { "description": "Send 'list' to redirect to the campaign list instead of the detail page (UI only).", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Redirect; flash 'Campaign launched' or the refusal message." } }, "summary": "Launch a campaign", "tags": [ "Campaigns" ], "x-destructive": true, "x-min-role": "edit" } }, "/campaigns/{campaign_id}/leads/csv": { "post": { "tags": [ "Leads" ], "summary": "Add leads from a CSV file", "operationId": "api_add_leads_csv", "description": "Bulk-adds leads to a campaign from a CSV: a multipart 'file' field, or raw CSV bytes as the body. The email column is found by its header (email, email_address or e-mail). Every other column becomes a personalization variable, header slugified, so a \"Company Name\" column becomes {{company_name}}. No dedupe. New leads start as pending. Returns a count, not ids. Errors are capped at 100; errors_truncated and total_errors appear when there were more. 404 if the campaign isn't in the workspace. Any valid key for the workspace can call this; there's no role check on it.\n\n**Minimum role:** `view` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The CSV file." } }, "required": [ "file" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "responses": { "201": { "description": "JSON {created, errors:[{row, email, error}], errors_truncated?, total_errors?}." } }, "x-min-role": "view", "x-destructive": false } }, "/campaigns/{campaign_id}/leads/list": { "get": { "description": "Paged, filterable lead list for one campaign. 404 JSON if the campaign is not in the workspace. (Prefixed with /list because POST /campaigns//leads already exists.)\n\n**Minimum role:** `view` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "spa_campaign_leads", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } }, { "description": "Contact status: pending, sent, replied, bounced, failed.", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "Reply stage key, or 'positive' for all positive stages. Stages: interested, meeting_request, not_interested, objection, pricing_question, more_info_needed, timing_issue, wrong_person, out_of_office, automated, unsubscribe, unclassified.", "in": "query", "name": "stage", "required": false, "schema": { "type": "string" } }, { "description": "Substring search on email and lead data.", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Page size, 10-200. Default 50.", "in": "query", "name": "size", "required": false, "schema": { "type": "integer" } }, { "description": "Page number, from 1. Default 1.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "JSON {leads:[{id, email, name, company, title, status, stage:{key,label,tone,positive}, seq_step, sent_at, next_at, mailbox, has_thread}], total, page, pages, size, counts:{: n}, all}." } }, "summary": "List a campaign's leads", "tags": [ "Leads" ], "x-destructive": false, "x-min-role": "view" } }, "/campaigns/{campaign_id}/leads/requeue-sender-blocked": { "post": { "description": "Every lead in the campaign with status sender_blocked (a failed delivery caused by our sending side: the provider refused to send, our SPF/DKIM/DMARC failed, or our IP/domain reputation was blocked) goes back to pending: one sequence step back so the failed step is sent again, due now, bounce fields and sender_originated cleared. Real recipient bounces (status bounced) are not touched. Does not launch or resume the campaign. 404 if the campaign is not in the workspace.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "campaigns_requeue_sender_blocked", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Redirect; flash 'requeued = N' (how many leads went back to pending)." } }, "summary": "Re-queue leads blocked on our side", "tags": [ "Leads" ], "x-destructive": false, "x-min-role": "edit" } }, "/campaigns/{campaign_id}/leads/{contact_id}/preview": { "get": { "description": "Returns JSON (not HTML). Renders the lead's next email (personalization, then spintax) for its current sequence step. A/B variants and spintax are chosen randomly, so repeat calls can differ. Read only. 404 if the campaign or lead is not in the workspace.\n\n**Minimum role:** `view` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "campaigns_preview_lead", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } }, { "in": "path", "name": "contact_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "JSON {contact:{email, status, data}, subject, body, step, total_steps, mailboxes:[{id, email}]} where mailboxes are the ones available to send a test from." } }, "summary": "Preview what a lead would receive next", "tags": [ "Leads" ], "x-destructive": false, "x-min-role": "view" } }, "/campaigns/{campaign_id}/leads/{contact_id}/test-send": { "post": { "description": "Sends the exact subject/body supplied to the given address from the chosen mailbox. Sends REAL email. Writes no SendLog row, does not touch mailbox counters or the lead's status. Errors (JSON): 400 missing/invalid mailbox_id or recipient, 404 mailbox not in workspace, 502 send failed or mailbox auth failed.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `true` (`x-destructive`).", "operationId": "campaigns_test_send_lead", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } }, { "in": "path", "name": "contact_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "body": { "description": "Body to send as-is.", "type": "string" }, "mailbox_id": { "description": "Mailbox to send from (same workspace).", "type": "integer" }, "subject": { "description": "Subject to send as-is (no re-rendering).", "type": "string" }, "to": { "description": "Recipient email (must contain @).", "type": "string" } }, "required": [ "to", "mailbox_id" ], "type": "object" } } } }, "responses": { "200": { "description": "JSON {ok: true, sent_from: } or {ok: false, error}." } }, "summary": "Send a one-off test email for a lead", "tags": [ "Leads" ], "x-destructive": true, "x-min-role": "edit" } }, "/campaigns/{campaign_id}/mailboxes/add": { "post": { "description": "Assigns the given mailboxes to the campaign. Ids from other workspaces and already-assigned ids are ignored. With no valid ids it flashes 'No mailboxes selected'. Note: a campaign with no assigned mailboxes sends from every active mailbox in the workspace, so assigning narrows the sender pool.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "campaigns_add_mailboxes", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "mailbox_ids": { "description": "Repeatable. Mailbox ids to assign.", "type": "array", "items": { "type": "integer" } } }, "required": [ "mailbox_ids" ], "type": "object" } } } }, "responses": { "200": { "description": "Redirect to the mailboxes tab; flash 'Added N mailboxes'." } }, "summary": "Assign mailboxes to a campaign", "tags": [ "Campaigns" ], "x-destructive": false, "x-min-role": "edit" } }, "/campaigns/{campaign_id}/mailboxes/remove": { "post": { "description": "Removes one mailbox from the campaign's assignment (the mailbox itself is kept). If it was the last assigned mailbox the campaign falls back to all active workspace mailboxes. A missing or non-numeric mailbox_id does nothing.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "campaigns_remove_mailbox", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "mailbox_id": { "description": "Mailbox id to unassign.", "type": "integer" } }, "required": [ "mailbox_id" ], "type": "object" } } } }, "responses": { "200": { "description": "Redirect to the mailboxes tab; flash 'Mailbox removed'." } }, "summary": "Unassign a mailbox from a campaign", "tags": [ "Campaigns" ], "x-destructive": false, "x-min-role": "edit" } }, "/campaigns/{campaign_id}/pause": { "post": { "description": "Sets status to paused so no further emails are sent. Works from any status. Nothing is deleted.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "campaigns_pause_campaign", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "redirect_to": { "description": "Send 'list' to redirect to the campaign list (UI only).", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Redirect; flash 'Campaign paused'." } }, "summary": "Pause a campaign", "tags": [ "Campaigns" ], "x-destructive": false, "x-min-role": "edit" } }, "/campaigns/{campaign_id}/pin": { "post": { "description": "Sets pinned. Pinned campaigns are listed first on the campaigns page and in GET /campaigns/list (newest first within pinned, then everything else newest first). The pin is workspace-wide, not per user. Omitting the field or sending false unpins. Nothing else about the campaign changes. 404 if the campaign is not in the workspace.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "campaigns_set_pinned", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "pinned": { "description": "true to pin, false to unpin.", "type": "boolean" } }, "required": [ "pinned" ], "type": "object" } } } }, "responses": { "200": { "description": "Redirect; flash 'pinned = true' or 'pinned = false' (the value now stored)." } }, "summary": "Pin or unpin a campaign", "tags": [ "Campaigns" ], "x-destructive": false, "x-min-role": "edit" } }, "/campaigns/{campaign_id}/sequence": { "post": { "description": "Replaces the whole multi-step sequence (every step, each with A/B variants). Preferred input is sequence_json; if it is missing or not a JSON list, the flat repeatable subject/body/wait fields are used instead (one variant per step). A positive wait on step 2+ becomes a wait step of that many days; the first step's wait is ignored. Refuses with flash 'Write at least one email before saving.' when every body is blank (nothing saved).\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "campaigns_save_sequence", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "body": { "description": "Fallback, repeatable, one per step. Used only when sequence_json is absent.", "type": "array", "items": { "type": "string" } }, "sequence_json": { "description": "JSON list: [{\"wait\": , \"variants\": [{\"subject\": \"...\", \"body\": \"...\"}]}].", "type": "string" }, "subject": { "description": "Fallback, repeatable, one per step. Used only when sequence_json is absent.", "type": "array", "items": { "type": "string" } }, "wait": { "description": "Fallback, repeatable, days to wait before each step after the first.", "type": "array", "items": { "type": "integer" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Redirect to the sequence tab; flash 'Sequence saved'." } }, "summary": "Save the email sequence", "tags": [ "Sequence" ], "x-destructive": false, "x-min-role": "edit" } }, "/campaigns/{campaign_id}/settings": { "post": { "description": "Overwrites the campaign's sending schedule. Fields not sent are CLEARED, not kept: send_hour_start/end and send_tz_offset become null, send_days becomes every day, max_gap_minutes becomes null, cc and bcc become null. Only min_gap_minutes is kept when omitted or negative. The hour window is both-or-neither: if either hour is missing, both are cleared. 404 if the campaign is not in the workspace.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "campaigns_save_settings", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "bcc": { "description": "BCC address added to every send. Omit to clear.", "type": "string" }, "cc": { "description": "CC address added to every send. Omit to clear.", "type": "string" }, "max_gap_minutes": { "description": "Maximum gap in minutes (>= 0). Omit to clear.", "type": "integer" }, "min_gap_minutes": { "description": "Minimum minutes between sends from one mailbox (>= 0).", "type": "integer" }, "send_days": { "description": "Repeatable. Weekday numbers 0-6 (Mon=0, Sun=6). Empty means every day.", "type": "array", "items": { "type": "integer" } }, "send_hour_end": { "description": "Window end hour in the campaign timezone.", "type": "integer" }, "send_hour_start": { "description": "Window start hour (0-23) in the campaign timezone.", "type": "integer" }, "send_tz_offset": { "description": "Timezone as minutes east of UTC (e.g. 330 = IST, -300 = ET, 0 = UTC).", "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Redirect to the campaign settings tab; flash 'Settings saved'." } }, "summary": "Save sending schedule", "tags": [ "Campaigns" ], "x-destructive": false, "x-min-role": "edit" } }, "/campaigns/{campaign_id}/unarchive": { "post": { "description": "Moves an archived campaign back to paused (it never resumes sending by itself; launch it to send again). No change if it is not archived.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "campaigns_unarchive_campaign", "parameters": [ { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "redirect_to": { "description": "Send 'list' to redirect to the campaign list (UI only).", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Redirect; flash 'Campaign unarchived...'." } }, "summary": "Unarchive a campaign", "tags": [ "Campaigns" ], "x-destructive": false, "x-min-role": "edit" } }, "/crm": { "get": { "description": "Kanban of replied leads, one column per stage, max 60 cards per column (count is the true total). Cached about 20 seconds.\n\n**Minimum role:** `view` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "spa_crm", "parameters": [ { "description": "Limit to one campaign id.", "in": "query", "name": "campaign", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "JSON {columns:[{key, label, tone, positive, count, cards:[{id, email, name, company, title, campaign, replied_at}]}], campaigns:[{id,name}]}." } }, "summary": "Get the reply pipeline board", "tags": [ "Pipeline" ], "x-destructive": false, "x-min-role": "view" } }, "/crm/move": { "post": { "description": "Sets a contact's lead stage (board column). 400 (no flash) if the stage is not valid or contact_id is missing/zero; 404 if the contact is not in the workspace.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "crm_move", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "contact_id": { "description": "Contact (lead) id.", "type": "integer" }, "stage": { "description": "One of: interested, meeting_request, not_interested, objection, pricing_question, more_info_needed, timing_issue, wrong_person, out_of_office, automated, unsubscribe, unclassified.", "type": "string" } }, "required": [ "contact_id", "stage" ], "type": "object" } } } }, "responses": { "200": { "description": "Redirect to the CRM board (no flash)." } }, "summary": "Move a lead to a pipeline stage", "tags": [ "Pipeline" ], "x-destructive": false, "x-min-role": "edit" } }, "/dashboard": { "get": { "description": "Workspace totals, today vs yesterday, mailbox fleet, unread counts, stage counts, 14-day series, latest positive replies and up to 6 campaigns. Days are IST. Cached about 20 seconds. Returns {empty: true} when the user has no workspace.\n\n**Minimum role:** `view` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "spa_dashboard", "parameters": [], "responses": { "200": { "description": "JSON {empty, today, sends_today, sends_yesterday, sends_yesterday_same_time, replies_today, positive_today, totals:{leads, pending, emails_sent, reached, replied, positive, bounced, reply_rate, positive_rate, bounce_rate, emails_per_positive}, mailboxes:{total, active, needs_reconnect, sending_on, live, capacity_today, at_cap}, unread, unread_positive, stage_counts, series, recent_positive, campaigns}." } }, "summary": "Dashboard summary", "tags": [ "Analytics" ], "x-destructive": false, "x-min-role": "view" } }, "/domains/list": { "get": { "description": "Per-domain rollup of mailboxes, sending, DNS score, warmup health, blacklist and redirect state. Cached about 20 seconds.\n\n**Minimum role:** `view` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "spa_domains", "parameters": [], "responses": { "200": { "description": "JSON {domains:[{domain, mailboxes, active, needs_reconnect, sending_on, sent_today, capacity_today, kind, dns_score, warmup_health, inbox_pct, spam_pct, blacklisted, redirects_to}]}." } }, "summary": "Domain health overview", "tags": [ "Domains" ], "x-destructive": false, "x-min-role": "view" } }, "/domains/refresh": { "post": { "description": "Starts the blacklist and redirect checks in a background thread (about 15 seconds). Any logged-in user may call it (no role check beyond login). Results appear in GET /domains/list.\n\n**Minimum role:** `view` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "mailboxes_domains_refresh", "parameters": [], "responses": { "200": { "description": "Redirect; flash 'Refreshing domain checks in the background...'" } }, "summary": "Refresh domain checks now", "tags": [ "Domains" ], "x-destructive": false, "x-min-role": "view" } }, "/inbox/reminder/{reminder_id}/done": { "post": { "description": "Marks the reminder done. 404 if not in the workspace.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "inbox_reminder_done", "parameters": [ { "in": "path", "name": "reminder_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Redirect to the reminder's thread (no flash)." } }, "summary": "Mark a reminder done", "tags": [ "Inbox" ], "x-destructive": false, "x-min-role": "edit" } }, "/inbox/stages": { "get": { "tags": [ "Inbox" ], "summary": "List reply stages", "operationId": "api_inbox_stages", "description": "Every lead_stage key, in the order the CRM board shows them, with its label and whether it counts as positive.\n\n**Minimum role:** `view` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "parameters": [], "responses": { "200": { "description": "JSON {stages:[{key, label, is_positive}]}." } }, "x-min-role": "view", "x-destructive": false } }, "/inbox/thread": { "get": { "description": "Full thread by id passed as a query parameter (SMTP thread ids contain special characters). SIDE EFFECT: opening a thread marks it read. 404 JSON if the id is blank or unknown.\n\n**Minimum role:** `view` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "spa_inbox_thread", "parameters": [ { "description": "Thread id.", "in": "query", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON {thread_id, mailbox, reply_to, can_send, subject, unread, messages:[{id, from, to, subject, body, at, outbound}], tags, reminders:[{id, at, note, done}], draft, contact:{id, email, name, company, title, status, stage}, campaign:{id,name}}." } }, "summary": "Get one thread with messages", "tags": [ "Inbox" ], "x-destructive": false, "x-min-role": "view" } }, "/inbox/thread/{thread_id}/draft": { "post": { "description": "Stores (or overwrites) the single draft reply body for the thread. Sends nothing.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "inbox_save_draft", "parameters": [ { "in": "path", "name": "thread_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "body": { "description": "Draft text. Blank saves an empty draft.", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Redirect to the thread; flash 'Draft saved.'" } }, "summary": "Save a reply draft", "tags": [ "Inbox" ], "x-destructive": false, "x-min-role": "edit" } }, "/inbox/thread/{thread_id}/forward": { "post": { "description": "Sends a REAL email (new thread, subject 'Fwd: ...') containing the optional note plus the latest message body, from the thread's mailbox. Refuses when to is empty or the mailbox cannot send. 404 if the thread is not in the workspace.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `true` (`x-destructive`).", "operationId": "inbox_forward", "parameters": [ { "in": "path", "name": "thread_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "note": { "description": "Text placed above the forwarded message.", "type": "string" }, "to": { "description": "Recipient address.", "type": "string" } }, "required": [ "to" ], "type": "object" } } } }, "responses": { "200": { "description": "Redirect to the thread; flash 'Forwarded.' or 'Could not forward: ...'." } }, "summary": "Forward a thread's latest message", "tags": [ "Inbox" ], "x-destructive": true, "x-min-role": "edit" } }, "/inbox/thread/{thread_id}/remind": { "post": { "description": "Adds a reminder. remind_at is parsed with ISO 8601; a blank or unparseable value is stored as no date (no error).\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "inbox_set_reminder", "parameters": [ { "in": "path", "name": "thread_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "note": { "description": "Reminder note.", "type": "string" }, "remind_at": { "description": "ISO 8601 datetime, e.g. 2026-11-01T09:00.", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Redirect to the thread (no flash)." } }, "summary": "Set a follow-up reminder on a thread", "tags": [ "Inbox" ], "x-destructive": false, "x-min-role": "edit" } }, "/inbox/thread/{thread_id}/reply": { "post": { "description": "Sends a REAL email from the thread's mailbox (Gmail API or SMTP), logs it as an outbound message, marks the thread read and deletes the saved draft. If cc or bcc is set, the prior thread messages are quoted below the body. Refuses (flash 'Could not send: ...') when to or body is empty, the thread has no mailbox, the mailbox cannot send, or auth fails (mailbox is then set to needs_reconnect). 404 if the thread is not in the workspace.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `true` (`x-destructive`).", "operationId": "inbox_reply", "parameters": [ { "in": "path", "name": "thread_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "bcc": { "description": "BCC address(es).", "type": "string" }, "body": { "description": "Message body (must not be blank).", "type": "string" }, "cc": { "description": "CC address(es).", "type": "string" }, "subject": { "description": "Subject. Default 'Re:'.", "type": "string" }, "to": { "description": "Recipient address.", "type": "string" } }, "required": [ "to", "body" ], "type": "object" } } } }, "responses": { "200": { "description": "Redirect to the thread; flash 'Reply sent.' or the error." } }, "summary": "Reply to a thread", "tags": [ "Inbox" ], "x-destructive": true, "x-min-role": "edit" } }, "/inbox/thread/{thread_id}/stage": { "post": { "description": "Manually sets the matched contact's reply stage. Always allowed (overrides the classifier). Does not fire the campaign_reply webhook. Refuses with flash when the stage is invalid or the thread is not matched to a campaign contact.\n\n**Minimum role:** `edit` (`x-min-role`). **Destructive:** `false` (`x-destructive`).", "operationId": "inbox_set_stage", "parameters": [ { "in": "path", "name": "thread_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "stage": { "description": "One of: interested, meeting_request, not_interested, objection, pricing_question, more_info_needed, timing_issue, wrong_person, out_of_office, automated, unsubscribe, unclassified.", "type": "string" } }, "required": [ "stage" ], "type": "object" } } } }, "responses": { "200": { "description": "Redirect to the thread; flash 'Marked as