{ "openapi": "3.1.0", "info": { "title": "Argorant API", "version": "1.0.0", "description": "One API for the whole workflow: find the companies and people that fit your offer, verify their work emails, save and export lists, then run the email campaign from your own Google Workspace or Microsoft 365 mailboxes and read the replies. The CLI (`npx argorant`) and the MCP server (`https://mcp.argorant.com/mcp`) are thin layers over exactly these endpoints, so an AI agent can operate every step.\n\nAuthenticate with an API key from app.argorant.com/profile as a bearer token. Counts, previews and lookups are free; reveals, exports and enrichment use credits; campaigns send from your own mailboxes.", "contact": { "name": "Argorant support", "url": "https://help.argorant.com" } }, "servers": [ { "url": "https://app.argorant.com", "description": "Production" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Account", "description": "The connected account: plan, credits, daily quota and scopes." }, { "name": "Lookups", "description": "Free autocomplete endpoints for the filter vocabularies: industries, countries, keywords and field values. Use the returned labels in the filters of search, export and campaigns." }, { "name": "Search", "description": "Count and preview matching people. Previews are masked (initials, role, company); nothing here spends credits." }, { "name": "Enrich", "description": "Fill in one record you already have: an email, a name plus company domain, or a company domain." }, { "name": "Lists", "description": "Saved lists: a reusable, named segment you can export or enroll into a campaign." }, { "name": "Export", "description": "Verified CSV exports. Every email is checked live at export time; you pay only for deliverable contacts." }, { "name": "Campaigns", "description": "Email outreach end to end: create a campaign, write the sequence, enroll a list, attach mailboxes, launch. Everything the app can do, the API can do." }, { "name": "Inbox", "description": "Replies across every campaign: list, open, answer in-thread and set a verdict, including your own opportunity stages." }, { "name": "Inboxes", "description": "The mailboxes that send: list them and connect a whole Google Workspace in one step." } ], "paths": { "/api/industries/suggest": { "get": { "tags": [ "Lookups" ], "operationId": "suggest-industries", "summary": "Industries lookup", "description": "Autocomplete canonical industry labels with live coverage counts. Type a plain-English market (\"saas\") and get the canonical industries that match — no NAICS or SIC codes. Use the returned labels in the `industries` filter on search and export.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Partial industry text.", "schema": { "type": "string" }, "example": "soft" }, { "name": "size", "in": "query", "required": false, "description": "Max suggestions (default 15).", "schema": { "type": "integer" }, "example": 15 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "integer" } } } } } }, "example": { "suggestions": [ { "label": "Software Development", "count": 18402551 }, { "label": "IT Services & Consulting", "count": 11204889 } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/countries/suggest": { "get": { "tags": [ "Lookups" ], "operationId": "suggest-countries", "summary": "Countries lookup", "description": "Normalized country list with coverage counts for the `country` filter. Names are canonicalized (no raw ISO codes), so \"Germany\" and \"DE\" resolve to the same bucket.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Partial country text.", "schema": { "type": "string" }, "example": "ger" }, { "name": "size", "in": "query", "required": false, "description": "Max suggestions (default 30).", "schema": { "type": "integer" }, "example": 30 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "integer" } } } } } }, "example": { "suggestions": [ { "label": "Germany", "count": 2516622 } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/keywords/suggest": { "get": { "tags": [ "Lookups" ], "operationId": "suggest-keywords", "summary": "Keywords lookup", "description": "Autocomplete free-text keywords (technologies, descriptors, niche tags) with coverage counts. Compound source values are decomposed into individual components, so \"buyout\" resolves cleanly to \"Buyout/LBO\" and similar.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Partial keyword text.", "schema": { "type": "string" }, "example": "buyout" }, { "name": "size", "in": "query", "required": false, "description": "Max suggestions (1–200, default 25).", "schema": { "type": "integer" }, "example": 25 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "integer" } } } } } }, "example": { "suggestions": [ { "value": "Buyout/LBO", "count": 38211 }, { "value": "Growth Equity", "count": 21044 } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/people/suggest": { "get": { "tags": [ "Lookups" ], "operationId": "suggest-values", "summary": "Field values lookup", "description": "Generic autocomplete for any filterable field (title, seniority, department, company_name, city, state). Pass the field name and a prefix.", "parameters": [ { "name": "field", "in": "query", "required": true, "description": "Field to suggest values for (title, seniority, department, company_name, city, state).", "schema": { "type": "string" }, "example": "title" }, { "name": "q", "in": "query", "required": false, "description": "Prefix to filter by.", "schema": { "type": "string" }, "example": "head of" }, { "name": "limit", "in": "query", "required": false, "description": "Max suggestions (1–50, default 20).", "schema": { "type": "integer" }, "example": 20 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "integer" } } } } } }, "example": { "suggestions": [ { "value": "Head of Sales", "count": 412904 }, { "value": "Head of Marketing", "count": 388140 } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/people/search": { "get": { "tags": [ "Search" ], "operationId": "search-people", "summary": "Search people", "description": "Search the contact database by industry, country, role, seniority, company, and email verification status. Returns paginated, ranked results with coverage counts. Emails are returned only on plans that include reveal; previews are masked otherwise.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text query across name, title, company, and email domain.", "schema": { "type": "string" }, "example": "head of growth" }, { "name": "industries", "in": "query", "required": false, "description": "Pipe-separated industry labels.", "schema": { "type": "string" }, "example": "SaaS|Fintech" }, { "name": "country", "in": "query", "required": false, "description": "Comma-separated country names.", "schema": { "type": "string" }, "example": "Germany,Austria" }, { "name": "seniority", "in": "query", "required": false, "description": "Comma-separated seniority bands (C-Level, VP, Director, Manager, Owner).", "schema": { "type": "string" }, "example": "C-Level,VP" }, { "name": "title", "in": "query", "required": false, "description": "Job-title contains match.", "schema": { "type": "string" }, "example": "VP of Sales" }, { "name": "company_name", "in": "query", "required": false, "description": "Company name match.", "schema": { "type": "string" }, "example": "Stripe" }, { "name": "company_domain", "in": "query", "required": false, "description": "Company website domain.", "schema": { "type": "string" }, "example": "stripe.com" }, { "name": "verify_status", "in": "query", "required": false, "description": "Comma-separated: valid, catch_all, risky, unknown, invalid.", "schema": { "type": "string" }, "example": "valid" }, { "name": "keywords", "in": "query", "required": false, "description": "Comma-separated free-text keywords matched across company name, description, title, and industry — widens niches that aren't a formal industry.", "schema": { "type": "string" }, "example": "solar,renewable" }, { "name": "technologies", "in": "query", "required": false, "description": "Pipe-separated technologies the company uses.", "schema": { "type": "string" }, "example": "Shopify|Klaviyo" }, { "name": "employee_range", "in": "query", "required": false, "description": "Comma-separated size buckets: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10000+, unknown.", "schema": { "type": "string" }, "example": "11-50,51-200" }, { "name": "record_ids", "in": "query", "required": false, "description": "Comma-separated Argorant record ids for exact source-record lookups.", "schema": { "type": "string" }, "example": "rec_123,rec_456" }, { "name": "has_email", "in": "query", "required": false, "description": "Only contacts that have an email on file.", "schema": { "type": "boolean" }, "example": true }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer" }, "example": 1 }, { "name": "page_size", "in": "query", "required": false, "description": "Results per page (1–100).", "schema": { "type": "integer" }, "example": 25 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "record_id": { "type": "string" }, "full_name": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" }, "company_domain": { "type": "string" }, "country": { "type": "string" }, "verification": { "type": "string" }, "email": { "type": "string" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "example": { "results": [ { "record_id": "p_8d4ba3d46cc885007c38e437", "full_name": "Alex Schneider", "title": "VP of Sales", "company": "Evenito", "company_domain": "evenito.com", "country": "Switzerland", "verification": "valid", "email": "a••••@evenito.com" } ], "total": 1843, "page": 1, "page_size": 25, "total_pages": 74 } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/people/{person_id}": { "get": { "tags": [ "Search" ], "operationId": "get-person", "summary": "Get a person", "description": "Fetch a single contact record by its stable record_id. Email and direct fields are masked unless the plan and permissions allow reveal.", "parameters": [ { "name": "person_id", "in": "path", "required": true, "description": "The record_id returned by search.", "schema": { "type": "string" }, "example": "p_8d4ba3d46cc885007c38e437" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "record_id": { "type": "string" }, "full_name": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" }, "company_domain": { "type": "string" }, "industry": { "type": "string" }, "country": { "type": "string" }, "verification": { "type": "string" }, "email": { "type": "string" } } }, "example": { "record_id": "p_8d4ba3d46cc885007c38e437", "full_name": "Alex Schneider", "title": "VP of Sales", "company": "Evenito", "company_domain": "evenito.com", "industry": "Software Development", "country": "Switzerland", "verification": "valid", "email": "a••••@evenito.com" } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } }, "404": { "description": "404 — Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Record not found" } } } } } } }, "/api/v1/enrich": { "post": { "tags": [ "Enrich" ], "operationId": "enrich-company", "summary": "Enrich a company domain", "description": "Send a domain on its own and get the company profile: name, domain, industry, and location. This mode is free and returns no contact details. Use search, reveal, or the person modes above for people.\n\n> Company enrichment costs zero contact credits, the same as counts and previews.", "parameters": [ { "name": "domain", "in": "body", "required": true, "description": "Company website domain. A full URL is accepted and reduced to the host.", "schema": { "type": "string" }, "example": "evenito.com" } ], "responses": { "200": { "description": "200 — No match", "content": { "application/json": { "schema": { "type": "object", "properties": { "found": { "type": "boolean" }, "type": { "type": "string" }, "charged": { "type": "integer" } } }, "example": { "found": false, "type": "company", "charged": 0 } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" } } }, "example": { "domain": "evenito.com" } } } } } }, "/api/exports/create": { "post": { "tags": [ "Export" ], "operationId": "create-export", "summary": "Create export", "description": "Create an asynchronous export job for a filtered segment. Emails are verified at export time using recent results plus fresh probes, with catch-all results separated from deliverable addresses. Poll the job, then download the CSV when complete.\n\n> Export and email reveal are billed and gated by plan.", "parameters": [], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer" }, "status": { "type": "string" } } }, "example": { "job_id": 84213, "status": "queued" } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "industries": { "type": "string" }, "country": { "type": "string" }, "verify_status": { "type": "string" }, "record_type": { "type": "string" } } }, "limit": { "type": "integer" }, "email_when_done": { "type": "boolean" } } }, "example": { "filters": { "industries": "SaaS", "country": "Germany", "verify_status": "valid", "record_type": "person" }, "limit": 5000, "email_when_done": false } } } } } }, "/api/exports/{job_id}": { "get": { "tags": [ "Export" ], "operationId": "get-export", "summary": "Get export status", "description": "Poll an export job. When `status` is `done`, the CSV is available at the download endpoint.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "The export job id.", "schema": { "type": "integer" }, "example": 84213 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "progress": { "type": "integer" }, "total": { "type": "integer" }, "verified": { "type": "integer" } } }, "example": { "id": 84213, "status": "processing", "progress": 3120, "total": 5000, "verified": 3120 } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/exports/{job_id}/download": { "get": { "tags": [ "Export" ], "operationId": "download-export", "summary": "Download export", "description": "Download the finished export as a CSV attachment. Returns `text/csv`.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "The export job id.", "schema": { "type": "integer" }, "example": 84213 } ], "responses": { "200": { "description": "200 — CSV", "content": { "text/csv": { "schema": { "type": "string" }, "example": "record_id,full_name,title,company,company_domain,email,verification,country\np_8d4b…,Alex Schneider,VP of Sales,Evenito,evenito.com,alex@evenito.com,valid,Switzerland" } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/exports": { "get": { "tags": [ "Export" ], "operationId": "list-exports", "summary": "List exports", "description": "List recent export jobs for the workspace, newest first, with status and row counts.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max jobs to return (1–200, default 50).", "schema": { "type": "integer" }, "example": 50 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "exports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "rows": { "type": "integer" }, "verified": { "type": "integer" }, "created_at": { "type": "string" } } } } } }, "example": { "exports": [ { "id": 84213, "status": "done", "rows": 5000, "verified": 4810, "created_at": "2026-06-09T09:14:02Z" }, { "id": 84090, "status": "processing", "rows": 0, "total": 12000 } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/lists/create": { "post": { "tags": [ "Lists" ], "operationId": "create-list", "summary": "Create saved list", "description": "Save a reusable lead list from a filter set or a pinned selection of record_ids. Saving a list does not reveal contacts — exporting from it later does.", "parameters": [], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "list_id": { "type": "integer" }, "name": { "type": "string" }, "snapshot_total": { "type": "integer" } } }, "example": { "list_id": 312, "name": "DACH VP Sales", "snapshot_total": 8412 } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "filters": { "type": "object", "properties": { "industries": { "type": "string" }, "country": { "type": "string" }, "seniority": { "type": "string" }, "verify_status": { "type": "string" } } } } }, "example": { "name": "DACH VP Sales", "filters": { "industries": "SaaS", "country": "Germany", "seniority": "VP", "verify_status": "valid" } } } } } } }, "/api/lists": { "get": { "tags": [ "Lists" ], "operationId": "list-lists", "summary": "List saved lists", "description": "Return the workspace's saved lead lists with their current sizes.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max lists (1–200, default 100).", "schema": { "type": "integer" }, "example": 100 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "lists": { "type": "array", "items": { "type": "object", "properties": { "list_id": { "type": "integer" }, "name": { "type": "string" }, "total": { "type": "integer" }, "created_at": { "type": "string" } } } } } }, "example": { "lists": [ { "list_id": 312, "name": "DACH VP Sales", "total": 8412, "created_at": "2026-06-09T08:00:00Z" } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/lists/{list_id}": { "get": { "tags": [ "Lists" ], "operationId": "get-list", "summary": "Get a saved list", "description": "Fetch a single saved list's metadata, filters, and current size.", "parameters": [ { "name": "list_id", "in": "path", "required": true, "description": "The saved list id.", "schema": { "type": "integer" }, "example": 312 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "list_id": { "type": "integer" }, "name": { "type": "string" }, "filters": { "type": "object", "properties": { "industries": { "type": "string" }, "country": { "type": "string" }, "seniority": { "type": "string" } } }, "total": { "type": "integer" } } }, "example": { "list_id": 312, "name": "DACH VP Sales", "filters": { "industries": "SaaS", "country": "Germany", "seniority": "VP" }, "total": 8412 } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/lists/{list_id}/export": { "post": { "tags": [ "Lists" ], "operationId": "export-list", "summary": "Export a saved list", "description": "Create an async export from a saved list. Optionally skip records already exported, so you only pay to verify and download net-new contacts.\n\n> Export is billed and gated by plan and remaining credits.", "parameters": [ { "name": "list_id", "in": "path", "required": true, "description": "The saved list id.", "schema": { "type": "integer" }, "example": 312 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer" }, "status": { "type": "string" } } }, "example": { "job_id": 84260, "status": "queued" } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer" }, "exclude_previously_exported": { "type": "boolean" }, "email_when_done": { "type": "boolean" } } }, "example": { "limit": 5000, "exclude_previously_exported": true, "email_when_done": false } } } } } }, "/api/account/summary": { "get": { "tags": [ "Account" ], "operationId": "account-summary", "summary": "Account summary", "description": "Return the signed-in workspace: plan, seat role, credit balance, and usage this period. Call this to check remaining credits before kicking off a large export.", "parameters": [], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "string" }, "plan": { "type": "string" }, "role": { "type": "string" }, "credits_remaining": { "type": "integer" }, "credits_period": { "type": "integer" }, "exports_30d": { "type": "integer" }, "seats": { "type": "integer" } } }, "example": { "workspace": "acme", "plan": "scale", "role": "owner", "credits_remaining": 41875, "credits_period": 50000, "exports_30d": 14, "seats": 5 } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/v1/campaigns": { "get": { "tags": [ "Campaigns" ], "operationId": "list-campaigns", "summary": "List campaigns", "description": "Every campaign in your workspace with status, lead, sent, reply and sender counts.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max campaigns (default 200).", "schema": { "type": "integer" }, "example": 50 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "lead_count": { "type": "integer" }, "sent_count": { "type": "integer" }, "replied_count": { "type": "integer" }, "inbox_count": { "type": "integer" }, "daily_limit": { "type": "integer" }, "url": { "type": "string" } } } } } }, "example": { "campaigns": [ { "id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "name": "Q4 CFO outreach", "status": "active", "lead_count": 1188, "sent_count": 412, "replied_count": 19, "inbox_count": 12, "daily_limit": 40, "url": "https://app.argorant.com/campaigns/7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } }, "post": { "tags": [ "Campaigns" ], "operationId": "create-campaign", "summary": "Create a campaign", "description": "Creates a draft. Nothing sends until you launch. Accepts every setting of PATCH (limits, window, timezone, gap, opt-out line, planned start, tags); defaults: 100 a day, 08:00-17:00 America/New_York, weekdays, gap 60-120 minutes, plain text.", "parameters": [], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" } } }, "next": { "type": "string" } } }, "example": { "campaign": { "id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "name": "Q4 CFO outreach", "status": "draft" }, "next": "Add emails (POST /emails), leads (POST /leads) and senders (POST /senders), then POST /launch." } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "daily_limit": { "type": "integer" }, "per_mailbox_daily_limit": { "type": "integer" }, "timezone": { "type": "string" }, "window_start": { "type": "string" }, "window_end": { "type": "string" }, "skip_weekends": { "type": "boolean" }, "gap_minutes_min": { "type": "integer" }, "gap_minutes_max": { "type": "integer" }, "include_unsubscribe": { "type": "boolean" }, "planned_start_date": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } }, "example": { "name": "Q4 CFO outreach", "daily_limit": 40, "per_mailbox_daily_limit": 20, "timezone": "Europe/Berlin", "window_start": "08:00", "window_end": "17:00", "skip_weekends": true, "gap_minutes_min": 60, "gap_minutes_max": 120, "include_unsubscribe": true, "planned_start_date": "2026-10-01", "tags": [ "q4" ] } } } } } }, "/api/v1/campaigns/{campaign_id}": { "get": { "tags": [ "Campaigns" ], "operationId": "get-campaign", "summary": "Get a campaign", "description": "The campaign with its emails, senders and `launch_blockers`: what still has to happen before a launch is accepted.", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" }, "example": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "lead_count": { "type": "integer" }, "inbox_count": { "type": "integer" } } }, "launch_blockers": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "integer" }, "subject": { "type": "string" }, "body": { "type": "string" }, "delay_days": { "type": "integer" }, "same_thread": { "type": "boolean" } } } }, "senders": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string" } } } } } }, "example": { "campaign": { "id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "name": "Q4 CFO outreach", "status": "draft", "lead_count": 1188, "inbox_count": 12 }, "launch_blockers": [], "emails": [ { "step": 1, "subject": "Quick question, {{first_name}}", "body": "Hi {{first_name}}, …", "delay_days": 0, "same_thread": false }, { "step": 2, "subject": "Re: Quick question, {{first_name}}", "body": "Bumping this.", "delay_days": 3, "same_thread": true } ], "senders": [ { "email": "elena@northgate-advisory.com", "provider": "google", "status": "connected", "health": "healthy" } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } }, "patch": { "tags": [ "Campaigns" ], "operationId": "update-campaign", "summary": "Update campaign settings", "description": "Change any setting; only the fields you send change. `daily_limit` is campaign-wide per day, `per_mailbox_daily_limit` caps each sender, `max_active_mailboxes` limits rotation. `timezone` is an IANA name; `timezone_mode` is `fixed` (campaign timezone) or `lead` (each recipient's local time). `window_start`/`window_end` are HH:MM. `gap_minutes_min/max` is the random pause between two sends from the same mailbox. `include_unsubscribe` adds the opt-out line. Campaigns send plain text; `plain_text: false` is rejected.", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" }, "example": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "settings": { "type": "object", "properties": { "daily_limit": { "type": "integer" }, "per_mailbox_daily_limit": { "type": "integer" }, "max_active_mailboxes": { "type": "string", "nullable": true }, "timezone": { "type": "string" }, "timezone_mode": { "type": "string" }, "window_start": { "type": "string" }, "window_end": { "type": "string" }, "skip_weekends": { "type": "boolean" }, "gap_minutes_min": { "type": "integer" }, "gap_minutes_max": { "type": "integer" }, "plain_text": { "type": "boolean" }, "include_unsubscribe": { "type": "boolean" }, "planned_start_date": { "type": "string" }, "schedule_days_ahead": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } } } } } }, "changed": { "type": "array", "items": { "type": "string" } } } }, "example": { "campaign": { "id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "name": "Q4 CFO outreach", "status": "draft", "settings": { "daily_limit": 40, "per_mailbox_daily_limit": 20, "max_active_mailboxes": null, "timezone": "Europe/Berlin", "timezone_mode": "fixed", "window_start": "08:00", "window_end": "17:00", "skip_weekends": true, "gap_minutes_min": 60, "gap_minutes_max": 120, "plain_text": true, "include_unsubscribe": true, "planned_start_date": "2026-10-01", "schedule_days_ahead": 5, "tags": [ "q4", "cfo" ] } }, "changed": [ "daily_limit", "sending_window_start", "tags" ] } } } }, "400": { "description": "400 — Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "window_start must be HH:MM (24h), e.g. 08:00" } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "daily_limit": { "type": "integer" }, "per_mailbox_daily_limit": { "type": "integer" }, "timezone": { "type": "string" }, "timezone_mode": { "type": "string" }, "window_start": { "type": "string" }, "window_end": { "type": "string" }, "skip_weekends": { "type": "boolean" }, "gap_minutes_min": { "type": "integer" }, "gap_minutes_max": { "type": "integer" }, "include_unsubscribe": { "type": "boolean" }, "planned_start_date": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } }, "example": { "daily_limit": 40, "per_mailbox_daily_limit": 20, "timezone": "Europe/Berlin", "timezone_mode": "fixed", "window_start": "08:00", "window_end": "17:00", "skip_weekends": true, "gap_minutes_min": 60, "gap_minutes_max": 120, "include_unsubscribe": true, "planned_start_date": "2026-10-01", "tags": [ "q4", "cfo" ] } } } } }, "delete": { "tags": [ "Campaigns" ], "operationId": "delete-campaign", "summary": "Delete a campaign", "description": "Deletes a draft, paused or stopped campaign with its emails, leads and results. An active campaign must be stopped first (409).", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" }, "example": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "deleted": { "type": "string" } } }, "example": { "ok": true, "deleted": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } }, "409": { "description": "409 — Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Stop the campaign before deleting it (POST /stop)" } } } } } } }, "/api/v1/campaigns/{campaign_id}/emails": { "post": { "tags": [ "Campaigns" ], "operationId": "set-campaign-emails", "summary": "Write the emails", "description": "Replaces the sequence. The first email needs a subject; follow-ups default to the same thread (`Re: …`) and wait `delay_days` after the previous email. Variables: {{first_name}}, {{last_name}}, {{company}}, {{title}}, plus any column you sent with the leads ({{plan}}, {{city}} …). Spintax `{a|b}` varies phrasing per recipient. `variants` adds A/B copy for a step; each variant is rotated evenly with the main text.", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" }, "example": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "integer" }, "subject": { "type": "string" }, "delay_days": { "type": "integer" }, "variants": { "type": "integer" } } } } } }, "example": { "emails": [ { "step": 1, "subject": "Quick question, {{first_name}}", "delay_days": 0, "variants": 2 }, { "step": 2, "subject": "Re: Quick question, {{first_name}}", "delay_days": 3, "variants": 1 } ] } } } }, "400": { "description": "400 — Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Email 1 needs a subject" } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "body": { "type": "string" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "body": { "type": "string" } } } } } } } } }, "example": { "emails": [ { "subject": "Quick question, {{first_name}}", "body": "Hi {{first_name}},\n\nsaw {{company}} is hiring in finance. Worth a 10 minute call?\n\nBest", "variants": [ { "label": "Direct", "body": "Hi {{first_name}}, do you have 10 minutes this week to talk finance hiring at {{company}}?" } ] }, { "body": "Bumping this up in case it got buried.", "delay_days": 3, "same_thread": true } ] } } } } } }, "/api/v1/campaigns/{campaign_id}/leads": { "post": { "tags": [ "Campaigns" ], "operationId": "add-campaign-leads", "summary": "Add leads", "description": "Enroll a saved list (`list_id`) or explicit `rows`. Every address is verified before it joins; only valid ones are enrolled unless `include_catch_all` is true. Addresses without a verdict yet are checked in the background and enrolled automatically. Duplicates, blocklisted and suppressed addresses are skipped. Any extra key on a row (`plan`, `city`, `last_order` …) is stored with the lead and usable in emails as {{plan}}.\n\n> Use `list_id` (from a saved list) instead of `rows` to enroll a whole list.", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" }, "example": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "input_rows": { "type": "integer" }, "inserted": { "type": "integer" }, "duplicates_skipped": { "type": "integer" }, "skipped_not_valid": { "type": "integer" }, "queued_for_verification": { "type": "integer" }, "verification_counts": { "type": "object", "properties": { "valid": { "type": "integer" }, "catch_all": { "type": "integer" }, "invalid": { "type": "integer" }, "unknown": { "type": "integer" } } } } }, "example": { "ok": true, "input_rows": 1240, "inserted": 1188, "duplicates_skipped": 12, "skipped_not_valid": 40, "queued_for_verification": 0, "verification_counts": { "valid": 1188, "catch_all": 28, "invalid": 12, "unknown": 0 } } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "title": { "type": "string" } } } }, "include_catch_all": { "type": "boolean" } } }, "example": { "rows": [ { "email": "jane.doe@example-acme.com", "first_name": "Jane", "last_name": "Doe", "company": "Acme", "title": "CFO" } ], "include_catch_all": false } } } } }, "get": { "tags": [ "Campaigns" ], "operationId": "list-campaign-leads", "summary": "List enrolled leads", "description": "The people in a campaign with their status: `pending` (verification running), `queued`, `active`, `replied`, `bounced`, `completed`, `suppressed`. Paginate with `limit`/`offset`, filter by `status`, search name, email or company with `q`.", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" }, "example": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" }, { "name": "status", "in": "query", "required": false, "description": "One lead status.", "schema": { "type": "string" }, "example": "replied" }, { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page (max 500).", "schema": { "type": "integer" }, "example": 50 }, { "name": "offset", "in": "query", "required": false, "description": "Rows to skip.", "schema": { "type": "integer" }, "example": 0 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "leads": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "current_step": { "type": "integer" }, "next_send_at": { "type": "string", "nullable": true }, "last_sent_at": { "type": "string" }, "replied_at": { "type": "string" }, "bounced_at": { "type": "string", "nullable": true }, "failure_reason": { "type": "string", "nullable": true }, "created_at": { "type": "string" } } } } } }, "example": { "total": 1188, "limit": 50, "offset": 0, "leads": [ { "id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "email": "jane.doe@example-acme.com", "first_name": "Jane", "last_name": "Doe", "company": "Acme", "title": "CFO", "status": "replied", "current_step": 2, "next_send_at": null, "last_sent_at": "2026-09-18T09:12:00+00:00", "replied_at": "2026-09-18T14:03:11+00:00", "bounced_at": null, "failure_reason": null, "created_at": "2026-09-15T10:00:00+00:00" } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/v1/campaigns/{campaign_id}/senders": { "post": { "tags": [ "Campaigns" ], "operationId": "set-campaign-senders", "summary": "Choose the sending mailboxes", "description": "Attach connected mailboxes by address, or every connected mailbox with `all_connected`. Sends are spread across them within each mailbox's daily limit.", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" }, "example": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "attached": { "type": "integer" }, "senders": { "type": "array", "items": { "type": "string" } } } }, "example": { "attached": 2, "senders": [ "elena@northgate-advisory.com", "marina@northgate-partners.co" ] } } } }, "400": { "description": "400 — Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No connected mailboxes to attach. Connect Google Workspace or Microsoft 365 first." } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" } }, "all_connected": { "type": "boolean" } } }, "example": { "emails": [ "elena@northgate-advisory.com", "marina@northgate-partners.co" ], "all_connected": false } } } } } }, "/api/v1/campaigns/{campaign_id}/launch": { "post": { "tags": [ "Campaigns" ], "operationId": "launch-campaign", "summary": "Launch", "description": "Starts sending. Refused with the list of `launch_blockers` while the campaign has no email, no sender with capacity or no lead. `/pause` holds it, `/stop` ends it for good.", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" }, "example": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" } } } } }, "example": { "campaign": { "id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "name": "Q4 CFO outreach", "status": "active" } } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } }, "409": { "description": "409 — Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "attach at least one active inbox with daily capacity" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/api/v1/campaigns/{campaign_id}/pause": { "post": { "tags": [ "Campaigns" ], "operationId": "pause-campaign", "summary": "Pause or stop", "description": "`/pause` holds sending and keeps the schedule; `/stop` ends the campaign. Both take an empty body.", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" }, "example": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } } } } }, "example": { "campaign": { "id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "status": "paused" } } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/api/v1/campaigns/{campaign_id}/leads/{email}": { "delete": { "tags": [ "Campaigns" ], "operationId": "remove-campaign-lead", "summary": "Remove a lead", "description": "Takes one person out of the campaign. Nothing more is sent to them from it; already sent emails are unaffected.", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" }, "example": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" }, { "name": "email", "in": "path", "required": true, "description": "The lead's email address.", "schema": { "type": "string" }, "example": "jane.doe@example-acme.com" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "removed": { "type": "string" } } }, "example": { "ok": true, "removed": "jane.doe@example-acme.com" } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } }, "404": { "description": "404 — Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No enrolled lead with that email in this campaign" } } } } } } }, "/api/v1/campaigns/{campaign_id}/replies": { "get": { "tags": [ "Campaigns" ], "operationId": "campaign-replies", "summary": "Replies to a campaign", "description": "Replies received for this campaign, newest first, with the stored classification. For replies across all campaigns use the Inbox endpoints.", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" }, "example": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" }, { "name": "limit", "in": "query", "required": false, "description": "Rows (max 200).", "schema": { "type": "integer" }, "example": 50 }, { "name": "offset", "in": "query", "required": false, "description": "Rows to skip.", "schema": { "type": "integer" }, "example": 0 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "replies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "from_email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "classification": { "type": "string" }, "event_type": { "type": "string" }, "created_at": { "type": "string" } } } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "replies": [ { "id": "a1b2c3d4-0000-4000-8000-000000000001", "from_email": "jane.doe@example-acme.com", "first_name": "Jane", "last_name": "Doe", "company": "Acme", "subject": "Re: Quick question, Jane", "body": "Happy to talk. Does Thursday 10:00 work?", "classification": "interested", "event_type": "provider_reply", "created_at": "2026-09-18T14:03:11+00:00" } ], "limit": 50, "offset": 0 } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/v1/campaigns/{campaign_id}/senders/{email}": { "delete": { "tags": [ "Campaigns" ], "operationId": "remove-campaign-sender", "summary": "Remove a sender", "description": "Detaches one mailbox from the campaign. The mailbox stays connected to your account.", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" }, "example": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" }, { "name": "email", "in": "path", "required": true, "description": "Mailbox address.", "schema": { "type": "string" }, "example": "elena@northgate-advisory.com" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "detached": { "type": "string" } } }, "example": { "ok": true, "detached": "elena@northgate-advisory.com" } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/v1/inbox": { "get": { "tags": [ "Inbox" ], "operationId": "inbox", "summary": "List conversations", "description": "Replies, bounces and unsubscribes across every campaign, newest first. `folder` is one of `all`, `replies`, `interested`, `not_interested`, `out_of_office`, `bounces`, `unsubscribes`. Filter further by `campaign_id`, `classification` or free text `q`. Bodies are shortened to 400 characters here; open a thread for the full text.", "parameters": [ { "name": "folder", "in": "query", "required": false, "description": "Which conversations.", "schema": { "type": "string" }, "example": "replies" }, { "name": "campaign_id", "in": "query", "required": false, "description": "Only this campaign.", "schema": { "type": "string" } }, { "name": "classification", "in": "query", "required": false, "description": "interested, not_interested, out_of_office, meeting_booked, referral, other.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search subject, text, sender, company.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Rows (max 500).", "schema": { "type": "integer" }, "example": 50 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "folder": { "type": "string" }, "count": { "type": "integer" }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "event_type": { "type": "string" }, "classification": { "type": "string" }, "campaign_id": { "type": "string" }, "campaign_name": { "type": "string" }, "from_email": { "type": "string" }, "lead_name": { "type": "string" }, "company": { "type": "string" }, "inbox_email": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "created_at": { "type": "string" }, "reply_url": { "type": "string" } } } } } }, "example": { "folder": "replies", "count": 1, "events": [ { "id": "native-conversation:lead:7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c:0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "provider": "native_sequencer", "event_type": "provider_reply", "classification": "interested", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "from_email": "jane.doe@example-acme.com", "lead_name": "Jane Doe", "company": "Acme", "inbox_email": "elena@northgate-advisory.com", "subject": "Re: Quick question, Jane", "body": "Happy to talk. Does Thursday 10:00 work?", "created_at": "2026-09-18T14:03:11+00:00", "reply_url": "/api/v1/inbox/native-conversation:lead:7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c:0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f/reply" } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/v1/inbox/{thread_id}": { "get": { "tags": [ "Inbox" ], "operationId": "inbox-thread", "summary": "Open a conversation", "description": "One thread with the full message text.", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "description": "The `id` from the list.", "schema": { "type": "string" }, "example": "native-conversation:lead:7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c:0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "object", "properties": { "id": { "type": "string" }, "campaign_name": { "type": "string" }, "from_email": { "type": "string" }, "inbox_email": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "classification": { "type": "string" }, "created_at": { "type": "string" } } } } }, "example": { "event": { "id": "native-conversation:lead:7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c:0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "campaign_name": "Q4 CFO outreach", "from_email": "jane.doe@example-acme.com", "inbox_email": "elena@northgate-advisory.com", "subject": "Re: Quick question, Jane", "body": "Happy to talk. Does Thursday 10:00 work?\n\nJane", "classification": "interested", "created_at": "2026-09-18T14:03:11+00:00" } } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/v1/inbox/{thread_id}/reply": { "post": { "tags": [ "Inbox" ], "operationId": "inbox-reply", "summary": "Answer in-thread", "description": "Sends a plain-text reply in the same thread from the mailbox that received it. Goes out immediately.", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "description": "The `id` from the list.", "schema": { "type": "string" }, "example": "native-conversation:lead:7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c:0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "sent": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } }, "example": { "ok": true, "sent": { "ok": true } } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } }, "404": { "description": "404 — Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Thread not found" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" } } }, "example": { "body": "Thursday 10:00 works. I will send an invite." } } } } } }, "/api/v1/inbox/{thread_id}/classify": { "post": { "tags": [ "Inbox" ], "operationId": "inbox-classify", "summary": "Set the verdict", "description": "Stores your verdict on the conversation: any key from `GET /api/v1/reply-statuses`, built-in or your own stage.", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "description": "The `id` from the list.", "schema": { "type": "string" }, "example": "native-conversation:lead:7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c:0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" }, "classification": { "type": "string" } } }, "example": { "ok": true, "id": "native-conversation:lead:7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c:0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "classification": "meeting_booked" } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "classification": { "type": "string" } } }, "example": { "classification": "meeting_booked" } } } } } }, "/api/v1/reply-statuses": { "get": { "tags": [ "Inbox" ], "operationId": "reply-statuses", "summary": "Reply statuses", "description": "The verdicts you can set on a conversation: the built-in ones (`positive`, `meeting_booked`, `question`, `referral`, `not_interested`, `out_of_office`, `wrong_person`, `vendor_pitch`, `neutral`, `unsubscribe`) plus the opportunity stages your workspace defined.", "parameters": [], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "statuses": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string" }, "builtin": { "type": "boolean" } } } } } }, "example": { "statuses": [ { "key": "positive", "label": "Interested", "color": "lime", "builtin": true }, { "key": "meeting_booked", "label": "Meeting booked", "color": "lime", "builtin": true }, { "key": "proposal_sent", "label": "Proposal sent", "color": "purple", "builtin": false } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } }, "post": { "tags": [ "Inbox" ], "operationId": "create-reply-status", "summary": "Add an opportunity stage", "description": "Create a stage your pipeline uses, e.g. `Proposal sent` or `Demo scheduled`. The key is derived from the label. Delete with `DELETE /api/v1/reply-statuses/{key}`; conversations carrying it fall back to `neutral`.", "parameters": [], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string" }, "builtin": { "type": "boolean" } } } } }, "example": { "status": { "key": "proposal_sent", "label": "Proposal sent", "color": "purple", "builtin": false } } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } }, "409": { "description": "409 — Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "'positive' is a built-in status" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "color": { "type": "string" } } }, "example": { "label": "Proposal sent", "color": "purple" } } } } } }, "/api/v1/campaigns/{campaign_id}/analytics": { "get": { "tags": [ "Campaigns" ], "operationId": "campaign-analytics", "summary": "Campaign analytics", "description": "A daily series for the campaign: sent, replies, positive replies, bounces, unsubscribes, with totals and rates for the window.", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" }, "example": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c" }, { "name": "days", "in": "query", "required": false, "description": "Window in days (max 365).", "schema": { "type": "integer" }, "example": 30 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign_id": { "type": "string" }, "days": { "type": "integer" }, "totals": { "type": "object", "properties": { "sent": { "type": "integer" }, "replies": { "type": "integer" }, "positive": { "type": "integer" }, "bounces": { "type": "integer" }, "unsubscribes": { "type": "integer" }, "reply_rate": { "type": "number" }, "bounce_rate": { "type": "number" } } }, "series": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "sent": { "type": "integer" }, "replies": { "type": "integer" }, "positive": { "type": "integer" }, "bounces": { "type": "integer" }, "unsubscribes": { "type": "integer" } } } } } }, "example": { "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "days": 30, "totals": { "sent": 1188, "replies": 41, "positive": 9, "bounces": 3, "unsubscribes": 1, "reply_rate": 3.45, "bounce_rate": 0.25 }, "series": [ { "day": "2026-09-17", "sent": 120, "replies": 4, "positive": 1, "bounces": 0, "unsubscribes": 0 }, { "day": "2026-09-18", "sent": 118, "replies": 6, "positive": 2, "bounces": 1, "unsubscribes": 0 } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/v1/blocklist": { "get": { "tags": [ "Campaigns" ], "operationId": "list-blocklist", "summary": "Blocklist", "description": "Addresses and domains your campaigns never contact. Entries you add are yours; Argorant-wide entries (known spam traps, role addresses that complained) are included and marked `yours: false`.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Rows (max 5000).", "schema": { "type": "integer" }, "example": 500 } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "reason": { "type": "string" }, "created_at": { "type": "string" }, "yours": { "type": "boolean" } } } } } }, "example": { "entries": [ { "id": "c9a94730-604c-4156-bee1-d52e24a3f847", "type": "domain", "value": "competitor.com", "reason": "customer", "created_at": "2026-09-19T12:54:32+00:00", "yours": true } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } }, "post": { "tags": [ "Campaigns" ], "operationId": "add-blocklist", "summary": "Block an address or domain", "description": "Send an email address or a domain. Matching leads already enrolled in your campaigns are suppressed immediately; future enrollments skip them.\n\n> Remove with `DELETE /api/v1/blocklist/{id}`.", "parameters": [], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "leads_suppressed": { "type": "integer" } } }, "example": { "ok": true, "id": "c9a94730-604c-4156-bee1-d52e24a3f847", "type": "domain", "value": "competitor.com", "leads_suppressed": 3 } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" }, "reason": { "type": "string" } } }, "example": { "value": "competitor.com", "reason": "customer" } } } } } }, "/api/v1/inboxes/{email}": { "patch": { "tags": [ "Inboxes" ], "operationId": "update-inbox", "summary": "Change mailbox settings", "description": "Daily cold-send limit, warm-up on or off, whether the mailbox may be scheduled, display name and timezone. Only the fields you send change.", "parameters": [ { "name": "email", "in": "path", "required": true, "description": "The mailbox address.", "schema": { "type": "string" }, "example": "elena@northgate-advisory.com" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "inbox": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string" }, "daily_limit": { "type": "integer" }, "active": { "type": "boolean" }, "warmup": { "type": "boolean" }, "timezone": { "type": "string" } } }, "changed": { "type": "array", "items": { "type": "string" } } } }, "example": { "inbox": { "email": "elena@northgate-advisory.com", "name": "Elena Vaughn", "provider": "google", "status": "connected", "health": "healthy", "daily_limit": 40, "active": true, "warmup": true, "timezone": "Europe/London" }, "changed": [ "daily_limit", "timezone" ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } }, "404": { "description": "404 — Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No connected mailbox with that address" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "daily_limit": { "type": "integer" }, "warmup": { "type": "boolean" }, "active": { "type": "boolean" }, "display_name": { "type": "string" }, "timezone": { "type": "string" } } }, "example": { "daily_limit": 40, "warmup": true, "active": true, "display_name": "Elena Vaughn", "timezone": "Europe/London" } } } } }, "delete": { "tags": [ "Inboxes" ], "operationId": "delete-inbox", "summary": "Disconnect a mailbox", "description": "Detaches the mailbox from its campaigns and disconnects it. Nothing more sends from it.", "parameters": [ { "name": "email", "in": "path", "required": true, "description": "The mailbox address.", "schema": { "type": "string" }, "example": "elena@northgate-advisory.com" } ], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "disconnected": { "type": "string" } } }, "example": { "ok": true, "disconnected": "elena@northgate-advisory.com" } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/v1/inboxes": { "get": { "tags": [ "Inboxes" ], "operationId": "list-inboxes", "summary": "List connected mailboxes", "description": "The Google and Microsoft mailboxes connected to your workspace with connection state, health and today's sends against the daily limit. No credentials are ever returned.", "parameters": [], "responses": { "200": { "description": "200 — OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "inboxes": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string" }, "daily_limit": { "type": "integer" }, "sent_today": { "type": "integer" } } } } } }, "example": { "inboxes": [ { "email": "elena@northgate-advisory.com", "name": "Elena Vaughn", "provider": "google", "status": "connected", "health": "healthy", "daily_limit": 40, "sent_today": 38 } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/v1/inboxes/google-workspace": { "post": { "tags": [ "Inboxes" ], "operationId": "connect-google-workspace", "summary": "Connect Google Workspace", "description": "Two calls. Without `emails`: returns what the Workspace admin must add under Google Admin > Security > API controls > Domain-wide delegation (client id and scopes) and, once that is done, every mailbox and alias in the Workspace. With `emails` (or an empty list for all): connects those addresses as senders. No passwords, no per-mailbox login.", "parameters": [], "responses": { "200": { "description": "200 — connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "health": { "type": "string" } } } } } }, "example": { "connected": [ { "email": "elena@northgate-advisory.com", "health": "healthy" } ] } } } }, "401": { "description": "401 — Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Not authenticated" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "admin_email": { "type": "string" }, "emails": { "type": "array", "items": { "type": "string" } } } }, "example": { "admin_email": "admin@northgate-advisory.com", "emails": [ "elena@northgate-advisory.com" ] } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ag_live_…", "description": "Your API key from app.argorant.com/profile, sent as `Authorization: Bearer `." } } } }