# How campaigns work

> Learn how a campaign moves from draft to completed, what it checks before each send, and which events report it.

A campaign sends paced, safety-checked WhatsApp messages from the Numbers in one
project to a list of recipients. It is the only bulk sending path in Polymorfa.
Every message passes the checks on this page, and every state change is
reported by a status on the campaign and its recipients and by a webhook
event.

- **Content**: one approved template, up to 10 composed messages, or an
  experiment such as an [A/B test](https://docs.polymorfa.com/campaigns/ab-tests).
- **Recipients**: inline phone numbers, an [audience](https://docs.polymorfa.com/campaigns/audiences), or a
  [segment](https://docs.polymorfa.com/campaigns/segments), each with its own template variables.
- **Sending Numbers**: the connected Numbers in the project whose tier includes
  Campaigns. A campaign sends through one sending type: linked-device, Cloud
  API or test numbers.
- **Delivery settings**: pacing, per-Number caps, a send window and retries.

## Requirements

Campaigns send only from Numbers on a [Number tier](https://docs.polymorfa.com/billing/number-tiers)
that includes Campaigns. In the current catalog that is **Pro**; Free and
Standard do not include Campaigns. The rule applies to test numbers too.

You can create and edit a draft on any tier. Launch checks every sending
Number again, and a running campaign pauses when its Numbers lose Campaigns.
See [Campaign safety checks](https://docs.polymorfa.com/campaigns/safety-checks#campaigns-is-a-pro-capability).

Credentials:

| Surface | Path | Credential |
| --- | --- | --- |
| Messaging API | `/messaging/projects/{projectSlug}/campaigns` | Project token for that project |
| Platform API | `/platform/campaigns` | Team key with `projectId`, or a project token for its own project |

Reading needs `campaigns:read`. Creating, launching, rescheduling, pausing,
resuming, stopping and deleting need `campaigns:manage`. Audiences, segments,
profiles and the opt-out list belong to the team and need a team key.

## Lifecycle

### Draft

A new campaign is a `draft`. Change its content, recipients, sending Numbers
and schedule, and [send a test](https://docs.polymorfa.com/campaigns/send#send-a-test) to your own phone.
Nothing is sent to recipients.

### Launch

Launch runs the launch checks below. When they pass, Polymorfa copies the
audience into the campaign, skips numbers on the team's opt-out list and sets
`recipientCount`. A launch over your team's approval threshold waits for an
owner or admin instead; see
[Require approval for large sends](https://docs.polymorfa.com/campaigns/send#require-approval-for-large-sends).

### Scheduled

A campaign launched with a future `scheduledAt` waits for that time. Its
recipients are already fixed. The Console labels it **Scheduled**, and the API
still reports `draft` until sending starts. Move the start with
[reschedule](https://docs.polymorfa.com/campaigns/send#reschedule-a-scheduled-launch).

### Running

The campaign sends to each recipient in queue order, at its pace, from the
Numbers that can send at that moment.

### Finished

The campaign is `completed` when every recipient has resolved and no message
is waiting. It is `failed` when every recipient settled as failed. Archive a
finished campaign to keep its history marked as archived.

### Campaign statuses

| Status | Meaning | What you can do |
| --- | --- | --- |
| `draft` | Not launched, or launched and waiting for its scheduled start | Edit, test, launch, reschedule a scheduled launch, stop, delete an unscheduled draft |
| `running` | Sending | Pause, stop |
| `paused` | Sending is held, by you or by a check | Resume, stop, edit the send window or frequency cap |
| `cancelling` | A stop was accepted and sends already in progress are finishing | Wait |
| `cancelled` | Stopped; recipients not yet sent were skipped | Archive, delete |
| `completed` | Every recipient resolved | Archive, delete, retarget its recipients |
| `failed` | Every recipient settled as failed | Archive, delete |
| `archived` | A finished campaign you archived | Delete |

Stop is never blocked by a suspension or a lost tier entitlement, so a
campaign a check paused can always be stopped. A campaign with no active
delivery run cannot be paused or resumed; stop it, duplicate it and launch the
copy.

### Recipient statuses

| Status | Meaning |
| --- | --- |
| `queued` | Waiting to be sent, including outside the send window or while the campaign is paused |
| `sending` | A send is in progress |
| `sent` | WhatsApp accepted the first message |
| `delivered` | The recipient's device confirmed delivery |
| `read` | The recipient opened the message |
| `failed` | The send failed after every attempt |
| `skipped` | Never attempted, such as an opt-out, a cold hold or a stopped campaign |

`failureReason` gives the stable reason a recipient was skipped or failed. See
[Failure reasons](https://docs.polymorfa.com/campaigns/send#failure-reasons).

## Checks before each send

Launch checks the campaign once. Polymorfa then checks each recipient again
when its message is about to be sent, so a change after launch still applies.

| Check | At launch | At send time |
| --- | --- | --- |
| Tier includes Campaigns | Every pinned Number, or at least one Number in the project when none are pinned | The campaign pauses if its Numbers lose Campaigns |
| Connection and sending type | Pinned Numbers are connected and share one sending type | A disconnected Number leaves the pool until it is ready |
| Throughput | Requested pacing is within its ceiling | The campaign runs at the lower of its rate and any restriction's rate |
| Content and variables | The template is complete, and every variable has a value or fallback | Each message is checked again; no message is sent with an empty variable |
| Opt-out list | Opted-out recipients are skipped | An opted-out number is never claimed, even if it opted out after launch |
| Contact history | | A recipient who never wrote to the sending Number is held by default |
| Warm-up and caps | | A new Number's daily cap ramps up; recipients over a cap wait for the next window |
| Frequency cap (requires access) | | Messages over the team or campaign cap are skipped |

Every campaign send also uses jittered pacing and a typing indicator before
each text message. The
exact rules, limits and error codes are in
[Campaign safety checks](https://docs.polymorfa.com/campaigns/safety-checks).

## Holds are not failures

A recipient a check holds back is skipped or retried, never counted as a
delivery failure. `failedCount` counts sends WhatsApp refused, not sends
Polymorfa never made.

| What happened | The recipient | The campaign |
| --- | --- | --- |
| Opted out, or never wrote first while cold sends are held | `skipped`, never attempted | Keeps running |
| The sending Number is paced or reached a cap | Queued again, no attempt spent | Keeps running |
| No Number can pass a check, such as a lost tier or a suspension | Left queued, attempt given back | Pauses |

## Pausing

You pause a campaign to hold it. Sends already in progress finish, and the
remaining recipients wait. Resume runs the same checks as before the pause.

Polymorfa pauses a campaign for you when no sending Number can clear a check,
instead of failing recipients one at a time. The `campaign.paused` event then
carries a `reason` and one of these codes:

| `code` | Cause |
| --- | --- |
| `campaigns_not_entitled` | No sending Number is on a tier with Campaigns |
| `bansafe_team_suspended` | Every Number in the team is suspended |
| `bansafe_suspended` | Every Number the campaign sends from is suspended |
| `campaign_throughput_capped` | The requested throughput is above the Numbers' ceiling |
| `invalid_parameter` | A selected Number left the project, or the selection now mixes sending types |
| `hybrid_campaign_unsupported` | The campaign sends from a Hybrid Link Number |
| `blocked_by_safety` | Another safety check on the sending Numbers stopped the campaign |
| `number_quality_dropped` | A Cloud API Number's quality rating dropped while the campaign ran |
| `messaging_limit_dropped` | WhatsApp lowered a Cloud API Number's messaging limit |

Fix the cause, then resume. A campaign that uses an A/B test, weighted
variations, drip steps, a segment or a frequency cap also pauses when your team
loses access to that beta.

## Events

Subscribe a project webhook to the `campaign.*` events to follow a campaign
without polling. Payloads and delivery rules are in
[Campaign events](https://docs.polymorfa.com/api/events#campaigns-events).

| Event | Sent when |
| --- | --- |
| `campaign.launched` | The campaign begins sending |
| `campaign.rescheduled` | The start of a scheduled campaign moved |
| `campaign.paused` | The campaign stopped sending, with `reason` and `code` for an automatic pause |
| `campaign.resumed` | A paused campaign sends again |
| `campaign.stopped` | A stop settled and the campaign is cancelled |
| `campaign.completed` | Every recipient resolved, with the final counts |
| `campaign.failed` | Every recipient failed (`reason` `all_recipients_failed`) |
| `campaign.recipient_sent` | A message was sent to a recipient, one event per message |
| `campaign.recipient_failed` | A message failed after every attempt |
| `campaign.recipient_skipped` | A recipient will not receive a message |
| `campaign.cold_blocked` | A recipient was held because they never wrote first |
| `campaign.throttled` | Sending was paced back this pass |
| `campaign.cap_reached` | A sending Number reached its hourly, daily or new-chat cap |
| `campaign.recipient_delivered` | First delivery receipt (requires access) |
| `campaign.recipient_read` | First read receipt (requires access) |
| `campaign.recipient_replied` | First attributed reply (requires access) |
| `campaign.recipient_link_opened` | First open of a tracked link (requires access) |

The Platform API also lists a campaign's history with
`GET /platform/campaigns/{campaignId}/events`: `launched`, `rescheduled`,
`paused`, `resumed`, `cancelled`, `completed` and `failed`, most recent first.
Team members can choose email notices for completed and failed campaigns in
[My notifications](https://docs.polymorfa.com/teams/notifications#choose-email-notifications); pausing or stopping
a campaign sends no notice.

## Test numbers

Test numbers can send campaigns when their tier includes Campaigns. A test
number reaches only other test numbers in the same project, so every
recipient of a test-number campaign must be one of them. Weighted message
variations do not send from test numbers. See
[Test numbers](https://docs.polymorfa.com/testing/test-numbers).

## See also

- [Send your first campaign](https://docs.polymorfa.com/campaigns/quickstart)
- [Send a campaign](https://docs.polymorfa.com/campaigns/send)
- [Campaign safety checks](https://docs.polymorfa.com/campaigns/safety-checks)
- [Opt-outs and STOP replies](https://docs.polymorfa.com/campaigns/opt-outs)
- [Campaign API reference](https://docs.polymorfa.com/api/campaigns/list-campaigns)
