# Campaigns

How the Product API models a campaign: the five endpoints it exposes, the draft-only contract behind all of them, and the statuses a campaign moves through. Start here before creating, reading, estimating or deleting one.

**Language:** en
**Audience:** developer
**TLDR:** The Product API drafts campaigns and never sends them: POST creates a draft, GET reads one back (plus a project-wide digest at /campaign/summary), PATCH .../estimate prices it, DELETE removes it. Confirming the send stays with a person in the dashboard. Every operation is gated by the campaign's status, and the twenty-odd statuses collapse into six phases: draft, preparing, scheduled, sending, sent and stopped.
**Search keywords:** campaign, campaigns, campaign api, bulk sms, mass sms, broadcast, blast, campaign status, campaign statuses, campaign phase, lifecycle, PROJECT_CAMPAIGN_WRITE, PROJECT_CAMPAIGN_READ, what can I do to a campaign
**Related pages:** /developers/product-api/campaigns/creating-a-draft, /developers/product-api/campaigns/reading-campaigns, /developers/product-api/campaigns/estimating-and-deleting
**Docs index (every page):** https://docs.instasent.com/llms.txt
**This zone's index:** https://docs.instasent.com/developers/product-api/llms-full.txt
**This page:** https://docs.instasent.com/developers/product-api/campaigns/overview/ (HTML) · https://docs.instasent.com/developers/product-api/campaigns/overview.md (Markdown)

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.

> **Warning**: **The API drafts, a person sends.** Nothing here arms, schedules or sends a campaign, no balance is spent, and no message reaches a contact. Confirming the send happens in the dashboard, where a person has seen the estimate.

**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](/developers/product-api/campaigns/creating-a-draft).                              | `PROJECT_CAMPAIGN_WRITE` | medium      |
| `GET /campaign/{id}`            | Reads one campaign back. See [Reading campaigns](/developers/product-api/campaigns/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](/developers/product-api/campaigns/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](/developers/product-api/authentication) and [Rate limits](/developers/product-api/rate-limits), where each class ceiling is set by the organization's subscription plan.

> **Tip**: **The read endpoints are not optional extras.** Estimating and deleting are both asynchronous: neither has finished the work by the time it answers you, so in both cases the way you learn the outcome is to read the campaign again. An integration that only writes cannot tell whether either one worked.

## The life of a campaign

```mermaid
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](/platform/en/campaigns/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`](/developers/product-api/campaigns/reading-campaigns#the-project-digest) 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](/developers/product-api/campaigns/estimating-and-deleting#estimating-a-draft): it throws that work away.

> **Note**: Not everything stored as a campaign is one. One-off direct sends carry `purpose: direct` instead of `standard`, are not campaigns in the dashboard sense, and are [filtered out of the campaign list](/developers/product-api/campaigns/reading-campaigns#what-the-list-leaves-out) on purpose.

## What's next

- [Creating a draft](/developers/product-api/campaigns/creating-a-draft) - The `POST` contract: the request body, the response, warnings, limits and error codes.
- [Audience targeting](/developers/product-api/campaigns/audience) - Segments, inline filters and how to count the reach before you create anything.
- [Message content](/developers/product-api/campaigns/message) - Copy, template variables, senders, RCS buttons, SMS fallback and languages.
- [Dates and scheduling](/developers/product-api/campaigns/scheduling) - The three date forms, timezones, and why setting a date schedules nothing.
- [Reading campaigns](/developers/product-api/campaigns/reading-campaigns) - One campaign, the filtered list, and the project digest a dashboard is built on.
- [Estimating and deleting](/developers/product-api/campaigns/estimating-and-deleting) - Pricing a draft and removing one. Both asynchronous, both gated by status.

---

This is one page of the Instasent documentation. For the complete machine-readable index of every guide and API reference, fetch https://docs.instasent.com/llms.txt — start there for full context.