Endpoints

All customer API paths use /v1 and bearer authentication. API keys begin with ssk_. Run creation is asynchronous and returns 202 Accepted with the durable state.

Runs

POST /runs requires Idempotency-Key. Its body accepts an existing campaign or campaign metadata, auto/explicit/tag sender selection, inline leads, contact IDs, segment IDs, ordered steps and variants, a daily limit, schedule, stop_on_reply, opt-out state, and draft or launch intent.

An accepted launch moves through queued, preflighting, and then one of awaiting_approval, launching, active, failed, or denied. Later states are paused, completed, and cancelled. GET /runs/:id includes its append-only event stream.

Agent policies and approvals

Policies bind to one API key or OAuth grant. Capabilities are campaign.launch, email.compose, inbox.reply and mailbox.provision; the last is autonomous only with a max_monthly_mailbox_spend_cents the order's monthly total fits under. Autonomous grants require explicit mailbox IDs, independent capabilities, recipient/run and daily limits, action limits, and an expiry. Approval records expire after 30 minutes. Approving a run causes preflight and all hard safety gates to run again immediately before the campaign starts.

Direct sends

API-key and OAuth callers receive an executed or awaiting_approval result. JWT browser sessions are already human-authorized. Suppressions, organization limits, mailbox holds/authentication/health, and deliverability rules remain authoritative regardless of policy.

App connections and product events

An app connection is the base URL and signing secret an app_action step calls. POST /app-connections/:id/test sends a signed app.ping and answers 200 with a checklist (dns, tls, connection, authentication, status, latency_ms, error) whether or not the app accepted it. POST /events records a product event for a contact and resumes every wait_for_event step open for it; the 202 names each resumed step under matched_runs.

Mailboxes

POST /emails connects an SMTP/IMAP mailbox after a worker has validated the credential; Google and Microsoft mailboxes go through cli-start, which returns a consent URL and a session to poll. POST /emails/:id/test dials the stored credential again and answers 200 with a checklist even when it fails. GET /emails/:id carries the campaigns the mailbox sends for and its recent errors beside the mailbox itself.

Managed mailboxes

renewals lists every managed domain's renewal cycle: when it renews, what was charged, and whether anything needs a person. Renewal is automatic and priced at the provider's current renewal cost plus processing, read fresh each cycle.

providers lists the mailbox platforms that can be ordered right now, with the live per-mailbox monthly price of each. The catalog and its prices come from the upstream provider, not from configuration, so it is the only accurate source for a provider menu.

A quote prices an order from the upstream provider's live costs and checks every domain; it is valid for fifteen minutes, after which those prices are no longer guaranteed. Pass domain for one domain, or domains for several: the mailboxes are spread across them as evenly as possible, and each domain is priced on its own because registration cost varies by TLD. Provisioning turns a quote into an order once the caller may spend: a session directly, a credential through an agent policy that grants mailbox.provision with a max_monthly_mailbox_spend_cents the order fits under, or a human approval (the 202 awaiting_approval shape, re-submitted with the same quote_id). The order then waits on a Stripe checkout link (awaiting_payment) and moves through paid, queued, provisioning, configuring and ready, or failed and cancelled. Offered on SendSets Cloud only; a self-hosted instance answers 503 mailbox_provisioning_unavailable.

Campaign checks

validate is the read-only twin of preflight: the same checks plus the structural checks on the step graph, answered as problems with a fix each, without storing a report. /system/readiness is what sendsets doctor reads: the workflow sidecar, live workers, the scheduler, and whether inbound events are accepted.

Other supported surfaces

The default contract also mounts authentication, campaigns and sequences, contacts/leads and segments, mailboxes and warmup, inbox, analytics and deliverability, suppressions, realtime/audit events, API keys/OAuth, and webhooks. The generated OpenAPI document is the field-level reference.

CRM, forms, automations, advisor, templates, integrations, and internal AI engines remain compiled for later reuse but return 404 by default. Operators can mount them explicitly with SENDSETS_ENABLE_EXTENDED_SURFACES=true; they are outside this supported contract.