Campaigns

A campaign is a one-off message sent to a group of contacts: a sale announcement, a service notice, a launch. The Product API lets you assemble one programmatically, price it, read it back and throw it away. What it does not let you do is send it.

This is the surface an integration or an AI assistant uses to turn "message our VIP customers about the sale on Monday" into something a marketer can open, check and confirm.

Drafts only, and no edit counterpart

Two properties decide how you design around this whole section.

There is no update endpoint. A draft cannot be patched, and re-posting creates a second campaign rather than replacing the first. To change a campaign after it exists, someone opens it in the dashboard editor. Build your integration accordingly: assemble everything you know in one call, and treat the response as final from the API's point of view.

The upside of that split is the safety it buys. A programmatic caller, including an agent composing a campaign from a conversation, can go as far as a complete, reviewable draft, priced and checked, without ever being able to spend money or reach a customer by accident.

The five endpoints

Endpoint	What it does	Scope	Rate limit
POST /campaign	Creates a draft. See Creating a draft.	PROJECT_CAMPAIGN_WRITE	medium
GET /campaign/{id}	Reads one campaign back. See Reading campaigns.	PROJECT_CAMPAIGN_READ	large
GET /campaign	Lists the project's campaigns, filtered and paged.	PROJECT_CAMPAIGN_READ	large
GET /campaign/summary	A digest of the whole project's campaign activity.	PROJECT_CAMPAIGN_READ	large
PATCH /campaign/{id}/estimate	Prices a draft, asynchronously. See Estimating and deleting.	PROJECT_CAMPAIGN_WRITE	restrictive
DELETE /campaign/{id}	Removes a campaign that has not gone out.	PROJECT_CAMPAIGN_WRITE	restrictive

Scopes are chosen when the token is minted, under Project settings → API tokens. See Authentication and Rate limits, where each class ceiling is set by the organization's subscription plan.

The life of a campaign

stateDiagram-v2
    [*] --> Draft: created by the API
    Draft --> Prepared: audience and message reviewed in the dashboard
    Prepared --> Scheduled: confirmed in the dashboard
    Scheduled --> Sent: the send runs
    Sent --> [*]
    Draft --> Deleted: deleted through the API
    Prepared --> Deleted: deleted through the API
    Scheduled --> Deleted: deleted through the API, up to five minutes before the send
    Deleted --> [*]
    class Sent success
    class Deleted destructive

A draft created through the API lands in the project's campaign list exactly as if it had been started in the panel: same editor, same three steps (Audience, Message, Review & schedule), same estimate and confirmation. The customer-facing walkthrough of what happens from there is Creating a campaign in the Platform guides.

Statuses and phases

Every operation in this section is gated by the campaign's status, and the errors you get are mostly status errors, so it is worth reading the vocabulary once.

There are twenty-odd raw statuses. They collapse into six phases, which is how the product talks about a campaign and what GET /campaign/summary counts by:

Phase	Raw statuses	What it means
draft	draft, preview, estimating, estimated	Being written. Nothing is committed.
preparing	quoting, quoted, preparing, prepared, unpreparing	Confirmed by a person and being built. The price is locked and the individual messages are being assembled.
scheduled	confirmed, scheduled	Armed and waiting for its send time.
sending	sending, continuing, resuming	Going out now.
sent	sent	Done.
stopped	canceled, aborted, unpaid, deleted	Ended without completing, deletions included.

Two of those mappings are worth internalising, because they are not what the names suggest:

• estimating and estimated are still draft. Pricing happens while a person is still editing, so an estimate does not move a campaign forward. It is not a step towards sending.
• prepared is already preparing, not a draft. A prepared campaign has been confirmed by a person and has its messages built. This is why estimating a prepared campaign is destructive: it throws that work away.

What's next