# Send a campaign

> Create a campaign with recipients, launch it, follow every recipient and stop it, in the Console or through the API.

A campaign turns a list of phone numbers into paced, safety-checked WhatsApp
messages sent from the Numbers in one project. This page covers the whole path:
build the recipient list, launch, follow the send and stop. Each step shows the
Console and API ways to do it. For a short first run, see
[Send your first campaign](https://docs.polymorfa.com/campaigns/quickstart); for the statuses and events,
see [How campaigns work](https://docs.polymorfa.com/campaigns/how-campaigns-work).

Campaigns are the only bulk sending path in Polymorfa. Every send passes the
tier, throughput, opt-out, contact and warm-up checks described in
[Campaign safety checks](https://docs.polymorfa.com/campaigns/safety-checks).
To compare two to four messages on part of the audience before sending the best
one to the rest of the audience, see [A/B test a campaign](https://docs.polymorfa.com/campaigns/ab-tests).

## Pick a surface

Two public paths reach the same campaign engine with the same checks, the same
errors and the same results.

| 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`. The examples below use the
Messaging API; the Platform API takes the campaign id in the path. On the
Platform API a team key names the project with `projectId` on every campaign
request, and a project token is bound to its own project and omits it.

In the TypeScript SDK, `messaging.campaigns` calls the Messaging API by project
slug, and `platform.campaigns` calls the Platform API. A campaign sends from
Numbers whose tier includes Campaigns; when none of the eligible Numbers
qualifies, create and launch fail with `402 campaigns_not_entitled`.

The Graph API has no campaign methods. It sends one marketing template at a
time from a Meta Cloud API Number:

```bash Graph API
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/$PHONE_NUMBER_ID/marketing_messages" \
  -H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "15551234567",
    "type": "template",
    "template": {
      "name": "spring_sale",
      "language": { "policy": "deterministic", "code": "en_US" }
    },
    "product_policy": "STRICT"
  }'
```

**Graph API:** Meta Cloud API Numbers: Partly supported. Linked Devices Numbers: Not supported.

[Send a marketing message](https://docs.polymorfa.com/api/graph/marketing/send-a-marketing-message)
sends one recipient's template with an explicit `STRICT` product policy and
needs `messages:write`. Meta decides eligibility and the message's status, and
a simulated Number cannot send it.
[Get marketing status](https://docs.polymorfa.com/api/graph/marketing/get-marketing-status)
returns Meta's Marketing Messages onboarding status, the business portfolio's
terms state and the Cloud API marketing setting. Terms are accepted in
WhatsApp Manager, not through the API; webhooks in Meta's format receive the
`account_update` terms notification (`MM_LITE_TERMS_SIGNED`).

## Create the campaign with its recipients

**Console:**

Open **Campaigns** and select **New campaign**. The builder saves the draft as
you go; wait for **Draft saved** before launching. If saving fails, the builder
shows the reason and marks the changes as unsaved. If the first save gets no
clear answer, it may still have created the draft, so **Check for a saved draft**
before you choose **Create another draft**, which can add a duplicate.

1. **Type**: choose **Broadcast**, **A / B test** or **Drip**.
2. **Audience**: choose an audience, import a CSV, or paste phone numbers. The
   import summary shows the recipients kept, duplicates and invalid rows. For
   pasted numbers, the summary stays visible after import so you can correct
   the source numbers.
3. **Compose**: write up to 10 messages, or choose **Use a template**. An A/B
   test shows **Variants** here, and a drip shows **Steps**.
4. **Sending**: select the Numbers that send the campaign. Free and Standard
   Numbers appear disabled, with an upgrade action, and you can save the draft
   before upgrading. Each Number shows its sending type; after you select one,
   Numbers of another sending type are disabled, because a campaign sends
   through one type. Under **Delay between messages**, pick a preset from
   **Fast** (1.8 to 5 seconds between messages) to **Very slow** (2 to 5
   minutes), or choose **Custom** to set the rate and random delay yourself.
   The [delay presets](https://docs.polymorfa.com/campaigns/safety-checks#delay-presets) table lists the
   API values behind each preset.
5. **Opt-outs**: review how opt-outs are handled. Write any opt-out
   instruction in your message. The builder does not append a footer or send a
   separate consent prompt. Review your team's
   [keyword settings](https://docs.polymorfa.com/campaigns/opt-outs) before sending.
6. **Schedule**: choose **Send on launch** or **Schedule for later**.
   Scheduling uses your browser's local time zone; check the zone beside the
   date and time. To send only during set hours, turn on **Send only during
   set hours**. It starts with Monday to Friday, 09:00 to 18:00, in your
   browser's time zone. See
   [Choose when the campaign sends](#choose-when-the-campaign-sends).
7. **Review**: check the audience, messages, delivery settings and safeguards.
   A sending restriction appears here; resolve it before launching.

The review step checks the selected audience again. If its recipient count
changed since the draft was saved, review the new count and confirm it before
launching. The builder checks once more when you launch; if the count changes
during review, it stops and asks you to confirm the updated audience.

### Add buttons

On the Compose step, choose **Add button**. Linked Device messages hold up to
10 buttons, and up to 3 can be links or calls. Select a button to set its type
(**Reply**, **Link** or **Call**) and its label.

Each reply button has a **Reply ID**, returned with the recipient's response
when they select that reply. The builder fills in a generated ID. Replace it
with your own value, such as `offer-interested`, to match responses in your
system. Editing the label keeps the reply ID.

| Field | Accepted values |
| --- | --- |
| Label | Linked Devices: 1–256 UTF-8 bytes; Official API: 1–20 characters |
| Reply ID | 1–256 UTF-8 bytes, unique within the message, no control characters |

Uploaded attachments in the Console cannot yet be used as campaign media
headers. For Linked Device image, video or document headers, use the API with
a public HTTPS `media.url`. Audio cannot be combined with buttons; remove one
of them.

Official API numbers send up to 3 reply buttons; links, calls and media headers
need an approved template. Choose **Send test** to check the result on a phone
before launching.

**API:**

Send recipients inline, point at an
[audience](https://docs.polymorfa.com/campaigns/audiences) with `recipientListId`, or do
both.

```bash cURL
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: september-launch-1" \
  -d '{
    "name": "September launch",
    "templateId": "'"$TEMPLATE_ID"'",
    "recipients": [
      { "phone": "+14155550100", "variables": { "first_name": "Ada" } },
      { "phone": "+442071838750", "variables": { "first_name": "Alan" } }
    ],
    "senderConfig": {
      "sessionIds": ["'"$SESSION_ID"'"],
      "throughput": { "ratePerMinute": 20, "perNumberDailyCap": 500 }
    }
  }'
```

```typescript TypeScript
const created = await messaging.campaigns.create(
  "<project-slug>",
  {
    name: "September launch",
    templateId: "<template-id>",
    recipients: [
      { phone: "+14155550100", variables: { first_name: "Ada" } },
      { phone: "+442071838750", variables: { first_name: "Alan" } },
    ],
    senderConfig: {
      sessionIds: ["<number-id>"],
      throughput: { ratePerMinute: 20, perNumberDailyCap: 500 },
    },
  },
  { idempotencyKey: "september-launch-1" },
);
const campaignId = created.data.data.id;
```

*TypeScript:*

The campaign starts as a draft. Pass an audience as `recipientListId`, and a
[send window](#choose-when-the-campaign-sends) as `sendWindow`, in the same body.

Inline `recipients` accepts at most 1,000 entries and is all or nothing: one
invalid entry refuses the request and names it, so a campaign is never created
with someone silently missing. A number repeated inside the request is kept
once. The same number and variable rules apply as for audience members.

`senderConfig.sessionIds` pins the numbers the campaign sends from. A draft can
pin Numbers on any tier. When you launch, every pinned Number must be connected
and on a tier that includes Campaigns. A campaign that pins none draws from the
connected, unrestricted Numbers in its project whose tiers include Campaigns,
using one sending type: WhatsApp numbers when any are ready, otherwise Cloud API
numbers, otherwise test numbers. To send from a specific set, pin it.

Add more recipients while the campaign is still a draft, 1,000 per request:

```bash cURL
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/recipients" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: september-launch-batch-2" \
  -d '{ "recipients": [{ "phone": "+14155550101", "variables": { "first_name": "Grace" } }] }'
```

```typescript TypeScript
const added = await messaging.campaigns.addRecipients(
  "<project-slug>",
  campaignId,
  { recipients: [{ phone: "+14155550101", variables: { first_name: "Grace" } }] },
  { idempotencyKey: "september-launch-batch-2" },
);
console.log(added.data.data.added, added.data.data.duplicateCount, added.data.data.invalidRows);
```

Appending reports `added`, `recipientCount`, `duplicateCount`, `invalidCount`
and up to 20 `invalidRows`, and skips a number already on the campaign. Once the
campaign has been launched, appending returns `409`.

Send an `Idempotency-Key` to make an append safe to retry after a timeout or a
lost response. After an append succeeds, a retry with the same key and body
within 24 hours is not applied again: it returns that append's counts with
`Idempotent-Replayed: true`, even if the campaign has launched since. An append
that failed leaves no record, so a retry with the same key runs it again. The
Platform API append accepts the same header.

*TypeScript:*

Without an `idempotencyKey`, `addRecipients` is sent once and never retried;
after a lost response, list the recipients before you add them again.

### Edit the draft

**Console:**

Open the draft from **Campaigns** and select **Edit**. The builder saves each
change as you make it; wait for **Draft saved** before you launch. You can
change the audience, messages, sending Numbers and schedule until the campaign
launches.

**API:**

Send only the fields you want to change. On the Messaging API, `name`,
`recipientListId`, `senderConfig`, `scheduledAt`, `sendWindow`, `templateId`
and `variableMapping` can be updated; any other field is refused with `400`. `templateId` and
`variableMapping` change only while the campaign is an unlaunched draft; after
launch a different value returns `409`. A non-null `scheduledAt` must be integer Unix
milliseconds from zero through the JavaScript Date maximum; an out-of-range
value returns `400`.

```bash cURL
curl -X PATCH "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "September launch (EU)", "senderConfig": { "sessionIds": ["'"$SESSION_ID"'"] } }'
```

```typescript TypeScript
await messaging.campaigns.update("<project-slug>", campaignId, {
  name: "September launch (EU)",
  senderConfig: { sessionIds: ["<number-id>"] },
});
```

The Platform API accepts the same changes at
`PATCH /platform/campaigns/{campaignId}`, and also `messagesArray` (see
[Send several messages](#send-several-messages)). After launch, a different
`messagesArray` also returns `409`.

To send to a different audience, update the draft with another
`recipientListId`. After the campaign launches, the audience is fixed and the
update returns `409`. Changing a draft's audience replaces its existing
recipients; add any individual recipients you still want after the change.

A draft saves any sender selection, on any tier; launch checks it. After launch,
a new `senderConfig` must pass the launch checks and can return
`402 campaigns_not_entitled` or `400 invalid_parameter`. A different
`scheduledAt` is accepted only before launch. To move a scheduled
start that has not begun, [reschedule it](#reschedule-a-scheduled-launch).

*TypeScript:*

Change a draft with `messaging.campaigns.update(projectSlug, campaignId, body)`,
or with `platform.campaigns.update` on the team client, which names the project
in its options.

## Send several messages

A campaign sends one approved template, or up to 10 composed messages in order.
Set the composed messages with `messagesArray` on the Platform API campaign
create or update request. Each message has `source` text, and can also have
`media`, `buttons`, and a `footer`. `delayAfterSec` is the minimum wait, from 0 to
86,400 seconds, after the previous message was accepted. A template campaign
sends only its template.

A template must be complete and, on Cloud API numbers, approved for every sending number. Linked-device and test numbers send it as a normal message. Authentication (one-time code) templates cannot be sent by a campaign; launch returns `400 invalid_parameter` on `templateId`.

```bash
curl -X PATCH "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messagesArray": [
      { "version": 2, "source": "Hi {{first_name | there}}, your order shipped." },
      { "version": 2, "source": "Track it here: https://example.com/t/{{order_id}}", "delayAfterSec": 120 }
    ],
    "templateId": null
  }'
```

`"templateId": null` switches a draft that had a template to its composed
messages; while a template is set, the template is the only message sent.

Attach media with a public https `media.url`, which the sending number
downloads when it sends. Launch returns `400 invalid_parameter`, naming the
message, when an attachment has no `url`.

`{{name}}` inserts a recipient variable; `{{name | fallback}}` uses the fallback
when the variable is missing or empty. A message with no text, media, link or
call button, footer or Flow form is not sent.

On Linked Device numbers, saved replies, links and calls are sent as native
controls with stable reply IDs. A message supports ten total buttons and at
most three links/calls; those controls can mix with replies. Image, video and
document attachments become the button message's media header. The API checks
the selected sending numbers before launch or test send. Official API numbers
retain their reply limits and require approved templates for other controls or
media headers. Invalid combinations are rejected rather than split into extra
messages. Use a campaign test send to check the native result on the recipient.
The older saved-template sandbox text test does not test native controls or
media.

Every message goes through the same checks as the first: pacing, per-number
caps, warm-up allowance, typing indicator and the recipient's contact history.
Before each message, Polymorfa checks the team's opt-out list again, so a
recipient who replies STOP gets nothing more. Pacing, caps and a paused campaign
can make a wait longer than `delayAfterSec`, never shorter. Each later message is
sent from the number that sent the first. If that number cannot send, the
message waits until it can.

### How multi-message results are counted

The recipient's `status`, `sentAt`, `deliveredAt`, `readAt` and `externalMessageId`
describe its first message. The campaign's `sentCount`, `failedCount` and
`skippedCount` count each recipient once.

| What happens | Result |
| --- | --- |
| The first message fails after every attempt | The recipient is `failed` and no later message is sent |
| A later message is sent | `messagesSent` rises and a `campaign.recipient_sent` event with that `messageIndex` is sent |
| A later message fails after every attempt | The recipient stays `sent`. Its remaining messages are not sent, `sequenceError` names the failure class, and `campaign.recipient_failed` carries the `messageIndex` |
| The recipient opts out between messages | The remaining messages are not sent and `sequenceError` is `opted_out` |
| The campaign is stopped between messages | The remaining messages are not sent and `sequenceError` is `campaign_cancelled` |
| The campaign is paused between messages | The next message waits until the campaign resumes |

A later message that fails is retried under the campaign's retry settings, like a
first message. The failure classes `conversation_window_closed`,
`recipient_not_on_whatsapp` and `template_not_approved` are not retried, because
another attempt fails the same way.

The campaign completes when every recipient has resolved and no message is
waiting. `nextMessageAt` on a recipient shows when its next message is due.

To send one more message only after the first was delivered or read, and
never to someone who replied or opted out, add a
[follow-up](https://docs.polymorfa.com/campaigns/follow-ups) instead. A campaign with a follow-up
sends a single first message.

> **Note**
>
> On a Cloud API number, WhatsApp delivers a message that is not an approved
> template only within 24 hours of the recipient's last message to that number.
> Outside that window, each composed message fails with
> `conversation_window_closed`. A campaign that must reach people outside that
> window sends an approved template.

## Fill template and message variables

Every `{{variable}}` is filled per recipient from a recipient field, with an
optional fallback.

**Console:**

On the **Compose** step, choose **Use a template**, pick the template, and set
the recipient field and fallback for each variable. The preview shows the
message one recipient receives.

**API:**

Set `variableMapping` to name a recipient variable and an optional fallback:

```bash cURL
curl -X PATCH "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "'"$TEMPLATE_ID"'",
    "variableMapping": {
      "first_name": { "source": "FirstName", "fallback": "there" },
      "coupon": { "source": "Coupon" }
    }
  }'
```

```typescript TypeScript
await messaging.campaigns.update("<project-slug>", campaignId, {
  templateId: "<template-id>",
  variableMapping: {
    first_name: { source: "FirstName", fallback: "there" },
    coupon: { source: "Coupon" },
  },
});
```

The Messaging API accepts the same `templateId` and `variableMapping` when you
create a campaign or update a draft.

Each variable is filled in this order:

1. The recipient's value for `source`, or for the variable of the same name when
   `source` is omitted. A blank or whitespace-only value counts as no value.
2. The mapping's `fallback`.
3. A fallback written in a composed message as `{{first_name | there}}`.

`{{phone}}` is filled with the recipient's number unless the recipient has its
own non-empty `phone` variable, which is used instead. The template's sample
values are never sent to recipients.

A mapping holds at most 50 variables. Names use letters, digits, `_`, `.` or `-`,
and a fallback is 1 to 1,024 characters. An invalid mapping returns
`400 invalid_parameter` and `error.param` names the field. `templateId` and
`variableMapping` can change only while the campaign is an unlaunched draft;
afterwards a different value returns `409`.

## Vary the message by weight

To avoid sending the identical text to every recipient, give a campaign two to
five alternatives in `messageVariations`. Each recipient receives one
alternative, chosen by weight, and keeps it if the send is retried. Unlike an
A/B test, nothing is compared and no winner is chosen.

> **Note**
>
> **Weighted variations require access.** A team owner or admin enrolls the team
> on the **Campaigns** page of the Console. Until the team is enrolled and the
> beta is offered to it, setting `messageVariations`, launching a campaign that
> has them and resuming one return `403 feature_unavailable`.

```bash
curl -X PATCH "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messageVariations": [
      { "key": "hello", "weight": 60, "blueprint": { "version": 2, "source": "Hello {{first_name | there}}, your order is ready." } },
      { "key": "hi", "weight": 40, "blueprint": { "version": 2, "source": "Hi {{first_name | there}}! Your order is ready to collect." } }
    ]
  }'
```

- `key` is unique in the campaign: a lowercase letter, then up to 15 lowercase
  letters, digits, `_` or `-`. `weight` is an integer from 1 to 99, and the
  weights add up to 100. `source` is 1 to 4,096 characters.
- Every alternative must use the same `{{variable}}` placeholders and inline
  fallbacks, so the same recipients qualify whichever alternative they get.
- A campaign with alternatives sends only them. It cannot also have composed
  messages, a template or A/B variants.
- Alternatives send from linked-device Numbers only, not from Cloud API
  Numbers or test numbers. Select the Numbers with `senderConfig.sessionIds`.
  A campaign whose Numbers become Cloud API Numbers pauses before its next
  send.
- Alternatives change only while the campaign is an unlaunched draft. Send
  `null` to remove them. After launch an update returns `409`.
- Test sends of a draft with alternatives return `409 state_conflict`.

If the team leaves the beta, a running campaign with alternatives pauses before
its next send and can still be stopped. Resuming it requires the beta again.

## Send a test

Before you launch, send one copy of a draft's content to your own phone. A test
goes through the same rendering, sending and safety checks as the launched
campaign, from the number you choose. It sends every message of the draft in
order, without the delays between them, and stops at the first message that is
not sent. It renders the content with the sample
values selected for the test, so each recipient's message can differ where
their own values differ. The credential needs both `campaigns:manage` and
`campaigns:read` because the test can use stored recipient sample values.

- **Seed recipient.** `to` must be the phone of a number connected to your
  team, in any project. Link your own phone to a project to receive tests on it.
  A seed on your team's opt-out list is refused.
- **Sending Number.** `sessionId` must be connected and on a tier that includes
  Campaigns, the same requirement as launch. When the campaign selects numbers
  with `senderConfig.sessionIds`, test from one of them.
- **Variables.** Without `sampleRecipientId` or `variables`, the campaign's first
  recipient fills the variables, or its audience's first member when the draft
  has no recipients of its own. Name a recipient with `sampleRecipientId`, and
  override single values with `variables`. The test applies the campaign's
  variable mapping and fallbacks to every message in the draft.
- **Statistics.** A test is not a campaign recipient. It does not change the
  campaign's counts or analytics and does not send campaign webhooks.
- **Limits.** A team can send 20 tests an hour, and at most 5 an hour to one
  seed recipient.

**Console:**

Select **Send test** on the builder's **Review** step or on a draft's page.
Choose the **Sending number**, enter the **Seed recipient** phone number in
international format and, optionally, **Sample values**. Leave them blank to
use the first recipient's values.

**API:**

```bash
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/test-send" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: september-launch-test-1" \
  -d '{
    "sessionId": "'"$SESSION_ID"'",
    "to": "+14155550199",
    "variables": { "first_name": "Ada" }
  }'
```

```json
{
  "success": true,
  "data": {
    "id": "01924f1e-7c3a-7b1d-9e2f-3a4b5c6d7e8f",
    "campaignId": "01924f1e-6a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "status": "sent",
    "from": { "sessionId": "01924f1e-5b6c-7d8e-9f0a-1b2c3d4e5f6a", "phone": "+14155550123" },
    "to": "+14155550199",
    "messageId": "3EB0C767D26A1D2E5F7A",
    "variables": { "first_name": "Ada" },
    "createdAt": 1758326300000
  }
}
```

The response arrives once the send finishes. On the Platform API, send the same
body to `POST /platform/campaigns/{campaignId}/test-send`, with `projectId` when
you use a team key.

A refused test sends nothing unless the table says otherwise:

| Status and code | Cause | What to do |
| --- | --- | --- |
| `400 invalid_parameter` | `to` is not a number connected to your team, or `sessionId` is not a number this campaign can send from; `error.param` names the field | Choose a seed or sending number that meets the rules above |
| `402 campaigns_not_entitled` | The sending Number's tier does not include Campaigns | Move the Number to Pro, or test from a Pro Number |
| `409 bansafe_cold_held` | The seed has never written to the sending number, and the campaign holds first messages | Send any message from the seed phone to the sending number, then test again |
| `409 state_conflict` | The campaign is not a draft, has A/B variants or `messageVariations`, the seed opted out, or the sending number is a Hybrid Link number | Test before launch, or choose another seed or number. Campaigns with A/B variants or message alternatives cannot be test sent yet |
| `422 campaign_variables_missing` | A variable in the selected content has no sample value, explicit value, or fallback | Provide the missing value or a campaign fallback before testing |
| `429 rate_limit_exceeded` | A test-send limit was reached (`Polymorfa-RateLimit-Reason: campaign_test_send`), or the number's campaign send cap was reached | Wait for `Retry-After` |
| `429 bansafe_throttled`, `429 bansafe_daily_allowance_reached` | The sending number is paced or used its warm-up allowance | Wait for `Retry-After` |
| `503 session_not_ready` | The sending number is not connected | Reconnect it and test again |
| `504 result_unknown` | The outcome is unknown; the test can still arrive | Check the seed phone before sending another test. A retry with the same `Idempotency-Key` does not send again |

## Choose when the campaign sends

By default a campaign sends at any time of day. Set `sendWindow` on create, or
on a Messaging or Platform API update, to send only on chosen weekdays and during chosen
local hours:

```json
{
  "sendWindow": {
    "timeZone": "America/Sao_Paulo",
    "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
    "hours": [
      { "start": "09:00", "end": "12:00" },
      { "start": "14:00", "end": "18:00" }
    ]
  }
}
```

| Field | Rule |
| --- | --- |
| `timeZone` | IANA time zone name, such as `Europe/Lisbon` or `UTC`. If you omit it, Polymorfa stores your team's time zone, or `UTC` when your team has none. The campaign always returns the stored zone. |
| `days` | One to seven of `monday` to `sunday`, without repeats. |
| `hours` | One to four ranges. `start` is `HH:MM` in 24-hour time and is included; `end` is `HH:MM` or `24:00` and is excluded. Ranges cannot overlap or cross midnight. For 20:00 to 02:00, use two ranges, `20:00` to `24:00` and `00:00` to `02:00`; every range applies on each day in `days`. |
| `recipientTimeZone` | `true` applies the window in each recipient's local time. Defaults to `false`. |
| `timeZoneVariable` | Recipient variable that holds the recipient's IANA time zone. Defaults to `timeZone`. |

A recipient who comes up outside the window is not failed or skipped. The
recipient stays `queued` and is sent after the window next opens, at the
campaign's normal pace. The campaign stays `running`, its counts do not change,
and no recipient event is sent for the wait. A campaign whose window is closed
for everyone sends nothing until it opens. Daylight-saving changes follow the
time zone's rules.

With `recipientTimeZone` set to `true`, each recipient's zone is:

1. the zone in the recipient variable named by `timeZoneVariable`, when it is a
   valid IANA name;
2. otherwise the zone of the phone number's country, when that whole country
   uses one UTC offset. For example, `+44` numbers use `Europe/London`.
   Countries with several offsets, such as the United States, Brazil and
   Mexico, do not resolve this way;
3. otherwise the window's `timeZone`.

Recipient zones are resolved when the campaign launches. To set a zone
yourself, add a variable with the `timeZoneVariable` name to each audience
member or inline recipient, for example `"variables": { "timeZone": "Asia/Tokyo" }`.
If more than 5,000 distinct nonempty values occur in that variable, launch
returns `400 invalid_parameter` with `error.param` set to
`sendWindow.timeZoneVariable`. Correct the audience values before launching.

An invalid window returns `400 invalid_parameter`, and `error.param` names the
field, such as `sendWindow.hours[1]`. Send `"sendWindow": null` to remove a
window. You can change or remove the window while the campaign is a draft or
paused. A running campaign returns `409 state_conflict`: pause it, update the
window, then resume. If a paused campaign still has sends in progress, the edit
returns `409 state_conflict`; retry after those sends settle. A stalled send
that has not reached the provider can be recovered on a later edit attempt.
If delivery may have started, the edit returns `409 state_conflict` while that
send is in flight. Retry after it settles. If its result is lost, the recipient
eventually becomes a failed send with an unknown outcome; the campaign does
not send it again. The new window applies to the remaining recipients.

## Launch

**Console:**

On the builder's **Review** step, confirm the audience count, message, sending
Numbers and schedule, then select **Launch campaign**, or **Schedule campaign**
for a future start. A draft's page also has **Launch**.

**API:**

```bash cURL
# 24 hours from now, in Unix milliseconds. Reuse this value if you retry with the same key.
SCHEDULED_AT=$(( ($(date +%s) + 86400) * 1000 ))
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/launch" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: september-launch-start-1" \
  -d "{ \"scheduledAt\": $SCHEDULED_AT }"
```

```typescript TypeScript
// 24 hours from now. Reuse this value if you retry with the same key.
const scheduledAt = Date.now() + 24 * 60 * 60 * 1000;
const launched = await messaging.campaigns.launch(
  "<project-slug>",
  campaignId,
  { scheduledAt },
  { idempotencyKey: "september-launch-start-1" },
);
await platform.operations.wait(launched.data.data.operationId);
```

*TypeScript:*

`launch` returns once the launch is accepted; sending continues in the
background as an [operation](https://docs.polymorfa.com/development/operations#wait-for-an-operation).

Sending starts at `scheduledAt`, or right away when no start time is set. At
launch, Polymorfa copies the audience into the campaign, skips numbers on the
team's [opt-out list](https://docs.polymorfa.com/campaigns/opt-outs), and sets
`recipientCount` from the recipients that exist.

For a scheduled campaign, this snapshot happens when the launch request is
accepted. Later additions, removals or changes to the source audience do not
change that campaign's recipients. Opt-outs are checked again before sending.

Launch checks the campaign's saved sender selection against the Numbers' tiers
at that moment, so a Number that changed tier after the draft was saved is
checked on its new tier. Every pinned Number must be connected and on a tier
that includes Campaigns, and all pinned numbers must use one sending type:

| Status and code | Cause |
| --- | --- |
| `403 bansafe_team_suspended` | The team is suspended |
| `402 campaigns_not_entitled` | A pinned Number's tier does not include Campaigns, a pinned Number is not in the project, or a campaign that pins none has no Number on a tier that includes Campaigns in its project |
| `400 invalid_parameter` | A pinned number is disconnected, has no phone, or uses a different sending type from another selected number; `error.param` is `senderConfig.sessionIds` |
| `400 campaign_throughput_capped` | A requested throughput is above its safety ceiling; `error.param` names the field |
| `400 invalid_parameter` | The template is incomplete; `error.param` is `templateId` |
| `400 template_not_approved` | WhatsApp has not approved the template on a Cloud API number the campaign can send from |
| `422 campaign_variables_missing` | Some recipients have no value and no fallback for a variable; the message names the variables and counts the recipients |
| `409 campaign_approval_required` | Your team requires approval for launches above a recipient threshold, and this launch would send to more recipients. Nothing was sent. See [Require approval for large sends](#require-approval-for-large-sends) |
| `409 state_conflict` | The campaign is not a draft, is already launched and waiting for its start time, or its sending numbers or a selected Number's tier or connection changed while the launch was being checked. To move a scheduled start, reschedule it. |
| `503 service_unavailable` | The Numbers' tiers could not be checked; retry the launch |

To send to everyone, add fallbacks or map another recipient variable, then launch
again. To launch without those recipients, send `"skipMissingVariables": true`
in the launch body. They are marked `skipped` with `lastError`
`missing_variable` before the first message is sent, and counted in
`skippedCount`. Each message is checked against the same rules again when it is
sent, so no recipient receives a message with an empty variable; a recipient
skipped at that point emits `campaign.recipient_skipped` with `reason`
`missing_variable`.

Create, launch, reschedule, pause, resume, stop and test send accept an
`Idempotency-Key` header on the Messaging API; the Platform API accepts it on
launch, reschedule, pause, resume, stop and test send. These campaign lifecycle
requests use a one-hour window on both APIs. A repeated key does not start a
second launch or test send.

The first request returns its original status and response. Opaque campaign
response bodies are not retained for replay. A later retry can return
`503 idempotency_replay_unavailable`; the receipt still prevents another
execution. Keep the same key and read the campaign or message events to establish
the outcome. Do not switch keys to repeat a write whose outcome is unknown.

A retry while the first request is still running returns
`409 idempotency_in_progress`. Reusing a key with a different request returns
`422 idempotency_conflict`. Audience imports and recipient appends use their
separate metadata receipts and windows described above. See
[Errors](https://docs.polymorfa.com/api/errors).

## Require approval for large sends

A team owner or admin can require approval for any launch that would send to
more recipients than a threshold. Only the Console changes the threshold, so a
credential cannot turn off the approval that holds its own launches.

**Console:**

Open **Campaigns**, then **Settings**. Under **Approval for large sends**, enter
the **Recipient threshold** and save. Leave it empty to turn approval off.

**API:**

Read the threshold:

```bash
curl -X GET "https://api.polymorfa.com/platform/campaign-settings" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```json
{ "launchApproval": { "recipientThreshold": 5000 } }
```

There is no API to change it.

When the threshold is set, a launch by a team key, a project token, or a team
member who is not an owner or admin counts the recipients the launch would send
to, after opt-outs. If there are more than the threshold, nothing is sent: the
campaign stays a draft and the launch answers `409 campaign_approval_required`.
The error message names the approval request it recorded. Launching again with
the campaign unchanged returns the same request. A launch by an owner or admin
signed in to the Console does not need approval.

**Console:**

The campaign page shows **Launch approval** with the latest request. A team
owner or admin selects **Approve and launch** or **Reject**. A held resume or
new start time shows **Approve and resume** or **Approve new start**.

**API:**

List a campaign's requests, newest first:

```bash
curl "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID/approvals?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

Each request names the held `action` (`launch`, `resume` or `reschedule`) and
its `reasons`: `audience_threshold`, `agent_request`, or both. Each request has a
`status`:

| Status | Meaning |
| --- | --- |
| `pending` | Waiting for an owner or admin |
| `approved` | Approved; the action ran and `operationId` is its operation |
| `rejected` | Rejected; the action did not run and nothing was sent |
| `superseded` | A later request, or a change to the campaign, replaced it |
| `expired` | Not decided within 72 hours |

A launch, resume or new start time requested by an AI agent through the hosted
MCP server always records a request with the reason `agent_request`, whatever
the threshold. See [MCP server](https://docs.polymorfa.com/development/mcp#a-person-approves-campaign-sends).

An owner or admin approves or rejects a request in the Console. Approving launches the campaign in the same step, with every launch
check, the requested start time, and the recipients counted for the request.
If the campaign's content, sending numbers, schedule, template or recipients
changed after the request, nothing is sent and the answer is
`409 campaign_approval_stale`; launch again to request a new approval. A request
can be approved once. A requested start time that has already passed starts the
campaign when it is approved.

## Reschedule a scheduled launch

A launched campaign waits for its `scheduledAt` before it sends anything. Until
then you can move that start earlier or later, or start sending now, without
stopping and relaunching it.

**Console:**

Open the scheduled campaign and select **Reschedule**. Pick a new date and time
in your browser's time zone, or choose **Start now**.

**API:**

```bash cURL
# 48 hours from now, in Unix milliseconds. Reuse this value if you retry with the same key.
SCHEDULED_AT=$(( ($(date +%s) + 172800) * 1000 ))
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/reschedule" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: september-launch-move-1" \
  -d "{ \"scheduledAt\": $SCHEDULED_AT }"
```

```typescript TypeScript
// 48 hours from now. Reuse this value if you retry with the same key.
const rescheduledAt = Date.now() + 48 * 60 * 60 * 1000;
await messaging.campaigns.reschedule(
  "<project-slug>",
  campaignId,
  { scheduledAt: rescheduledAt },
  { idempotencyKey: "september-launch-move-1" },
);
```

On the Platform API, send the same body to
`POST /platform/campaigns/{campaignId}/reschedule`, with `projectId` in the body
when you use a team key.

*TypeScript:*

`reschedule` sends an idempotency key and makes one attempt unless you set
`maxNetworkRetries`.

`scheduledAt` is required. Set it to a Unix time in milliseconds, or to `null`
to start sending now. A time that is not in the future also starts the campaign
now. The response is the campaign with its new `scheduledAt` and the
`operationId` of its delivery run. Sending the current start time again changes
nothing.

Rescheduling changes only when the campaign starts. The recipients and messages
stay as they were when you launched it. Every send is still checked when the
campaign starts, the same as a start that was never moved. Each accepted change
is recorded as a `rescheduled` entry in the campaign's history and sends a
[`campaign.rescheduled`](https://docs.polymorfa.com/api/events#campaign-rescheduled) event.

| Status and code | Cause |
| --- | --- |
| `400 invalid_parameter` | `scheduledAt` is missing, or is not a positive whole number or `null` |
| `403 bansafe_team_suspended` | The team is suspended. You can still stop the campaign. |
| `409 state_conflict` | The campaign has already started, is finished or being stopped, or was never launched. Launch a draft with `scheduledAt` instead. |

Once a campaign has launched, update does not change its `scheduledAt`. An update
that sends a different `scheduledAt` returns `409`; reschedule the campaign
instead.

## Follow the send

**Console:**

Open the campaign. Its page shows delivery progress, and **Analytics** shows
the funnel. The **Recipients** panel filters by status and reason, and
**Download CSV** saves up to 1,000 filtered recipients through the same export
as the API. For larger filtered results, clear the filters, download all
recipients, then filter the file locally.

**API:**

List recipients in queue order with cursor pagination. `limit` is 1 to 100 and
defaults to 25.

```bash cURL
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/recipients?status=skipped&reason=opted_out&limit=100" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
let cursor: string | undefined;
do {
  const page = await messaging.campaigns.listRecipients("<project-slug>", campaignId, {
    status: "skipped",
    reason: "opted_out",
    limit: 100,
    cursor,
  });
  for (const recipient of page.data.data) console.log(recipient.phone, recipient.status);
  cursor = page.data.page.hasMore ? page.data.page.nextCursor ?? undefined : undefined;
} while (cursor);
```

The response:

```json
{
  "success": true,
  "data": [
    {
      "id": "0c0e4f2a-2b1d-4a67-9bb2-1f7f4a2e91a3",
      "phone": "+14155550100",
      "variables": { "first_name": "Ada" },
      "variantKey": null,
      "status": "skipped",
      "attempts": 0,
      "lastError": "opted_out",
      "failureReason": "opted_out",
      "externalMessageId": null,
      "queuedAt": 1758326400000,
      "sentAt": null,
      "deliveredAt": null,
      "readAt": null,
      "failedAt": 1758326402000,
      "respondedAt": null,
      "messagesSent": 0,
      "nextMessageAt": null,
      "sequenceError": null
    }
  ],
  "page": { "nextCursor": "cjE6MjU", "hasMore": true }
}
```

Follow `page.nextCursor` until `page.hasMore` is `false`. Filter with `status`:
`queued`, `sending`, `sent`, `delivered`, `read`, `failed` or `skipped`, with
`reason`, or with both.
`messagesSent`, `nextMessageAt` and `sequenceError` report progress through a
[multi-message campaign](#send-several-messages).

Download recipients as CSV, one page at a time, with
[Export campaign recipients](https://docs.polymorfa.com/api/campaigns/export-project-campaign-recipients).
The `Polymorfa-Next-Cursor` response header carries the next page's cursor and
is absent on the last page.

A `status` or `reason` filter returns one page of at most 1,000 matches and cannot
use a cursor. Above 1,000 matches the API returns `409` with no partial file. To
select from larger results, export every recipient and filter the CSV locally.
Quoted fields can contain commas and line breaks, so read it with a CSV parser.
Save this as a script; it exits nonzero if any page fails:

```bash cURL
#!/bin/sh
set -eu
pages=$(mktemp -d)
trap 'rm -rf "$pages"' EXIT
cursor=""
page=0
while :; do
  page=$((page + 1))
  # -f exits nonzero on an HTTP error and writes no error body to the page file.
  curl -fsS -D "$pages/headers.txt" -o "$pages/$(printf '%06d' "$page").csv" \
    "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/recipients/export${cursor:+?cursor=$cursor}" \
    -H "Authorization: Bearer $POLYMORFA_KEY"
  cursor=$(grep -i '^polymorfa-next-cursor:' "$pages/headers.txt" | cut -d' ' -f2 | tr -d '\r')
  [ -n "$cursor" ] || break
done

python3 - "$pages"/*.csv > failed-recipients.csv <<'PY'
import csv, sys

writer = None
for path in sys.argv[1:]:
    with open(path, newline="", encoding="utf-8") as page:
        reader = csv.DictReader(page)
        if writer is None:
            writer = csv.DictWriter(sys.stdout, reader.fieldnames)
            writer.writeheader()
        writer.writerows(row for row in reader if row["status"] == "failed")
PY
```

```typescript TypeScript
// parseCsv is your CSV library's parser: one object per row, keyed by the header.
const failed: Array<Record<string, string>> = [];
let exportCursor: string | undefined;
do {
  const page = await messaging.campaigns.exportRecipients("<project-slug>", campaignId, {
    cursor: exportCursor,
  });
  failed.push(...parseCsv(page.data.csv).filter(row => row.status === "failed"));
  exportCursor = page.data.nextCursor ?? undefined;
} while (exportCursor);
```

Each page starts with a header row. Read totals with
[Get campaign analytics](https://docs.polymorfa.com/api/campaigns/get-project-campaign-analytics):

```bash cURL
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/analytics" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
const stats = await messaging.campaigns.analytics("<project-slug>", campaignId);
console.log(stats.data.data.sentCount, stats.data.data.deliveredCount);
```

*TypeScript:*

From SDK version `0.1.0-dev.20261004041625`, the recipient engagement events
are typed as `CampaignRecipientDeliveredPayload`,
`CampaignRecipientReadPayload` and `CampaignRecipientRepliedPayload`. With an
older package, read the [documented fields](https://docs.polymorfa.com/api/events#campaigns-events)
from `event.payload`.

### Failure reasons

`failureReason` is the stable reason a recipient was not sent, or why its last
attempt did not succeed. It is `null` when nothing went wrong. It never contains
message content, the recipient's number, or a raw error. Filter on it with
`reason`.

| `failureReason` | Meaning |
| --- | --- |
| `opted_out` | The number is on the team's opt-out list |
| `cold_held` | The number never wrote to the sending number and the campaign holds cold sends |
| `campaign_cancelled` | The campaign was stopped before this recipient was sent |
| `invalid_recipient` | The number is not a valid WhatsApp address |
| `session_not_connected` | The sending number was not connected |
| `ack_timeout` | WhatsApp did not acknowledge the send in time |
| `blocked_by_safety` | A safety check refused the send before it was attempted; the recipient waits for the campaign to resume |
| `send_failed` | WhatsApp refused the send, or its outcome could not be confirmed |
| `missing_variable` | The recipient had no value and no fallback for a variable: skipped at launch with `skipMissingVariables`, or when a message was checked at send time |
| `frequency_cap` | The recipient reached the team's or campaign's rolling contact frequency cap |
| `other` | Any other reason |

New codes may be added, so treat an unknown value like `other`. The legacy
`lastError` field returns the same normalized code as `failureReason`; raw
stored errors are not returned.

### Export recipients as CSV

`GET .../recipients/export` returns CSV in queue order. Unfiltered exports
return up to 1,000 rows per request (`limit`, default 1,000). Each page starts
with a header row. When more rows remain, send the `Polymorfa-Next-Cursor`
response header as `cursor` for the next page.

Status and failure-reason filters return one page of up to 1,000 matching
recipients. Filtered exports cannot use a cursor, and `limit`, if sent, must
be `1000`; any other value returns `400`. If more than 1,000 recipients match, the API returns `409` without a partial file.
Export all recipients and filter the CSV locally for larger results.

```bash
curl -fsS -D headers.txt -o failed.csv \
  "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/recipients/export?status=failed" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```csv
recipientId,phone,status,failureReason,attempts,variantKey,queuedAt,sentAt,deliveredAt,readAt,failedAt,respondedAt
0c0e4f2a-2b1d-4a67-9bb2-1f7f4a2e91a3,'+14155550100,failed,invalid_recipient,3,,2026-09-20T00:00:00.000Z,,,,2026-09-20T00:04:12.000Z,
```

Times are ISO 8601 in UTC and empty fields are null. A leading apostrophe keeps
phone numbers as text in spreadsheets; remove it when reading phone cells in
code. The export never contains message content or template variables. An
unfiltered page reflects each recipient's outcome when requested. A filtered
file reflects one database read, so status changes cannot cause omissions
between filtered pages. The Platform API offers the same export at
`GET /platform/campaigns/{campaignId}/recipients/export?projectId=...`.

> **Warning**
>
> `GET /platform/campaigns/{campaignId}/recipients` returns one page and a
> `page` object. If your integration expects the previous unpaginated array,
> update it to follow `page.nextCursor` until all recipients have been read.

Campaign analytics report the funnel and the reply timing:

```bash
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/analytics" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

| Field | Meaning |
| --- | --- |
| `recipientCount` | Recipients on the campaign |
| `sentCount` | Messages accepted by WhatsApp |
| `deliveredCount` | Recipients whose device confirmed delivery |
| `readCount` | Recipients who opened the message; a read implies a delivery |
| `failedCount` | Sends WhatsApp refused |
| `skippedCount` | Recipients never attempted, such as an opt-out or a cold hold |
| `respondedCount` | Recipients who replied |
| `responseRate` | `respondedCount` divided by `sentCount`, and `0` before anything is sent |
| `averageResponseTimeMs` | Mean time from send to first reply, and `null` before the first reply |
| `minResponseTimeMs`, `maxResponseTimeMs` | Fastest and slowest first reply |

A reply counts once per recipient. It is attributed to the most recent recipient
that the replying number was sent to, on the same sending number, within 7 days
of that send.

To count who opens a link in the message, see
[Track campaign links](https://docs.polymorfa.com/campaigns/link-tracking).

Subscribe to `campaign.recipient_delivered`, `campaign.recipient_read`, and
`campaign.recipient_replied` on a project webhook to follow each recipient
after the send. These three events require access: your team joins the
recipient engagement events beta. Webhook payloads include the campaign and recipient IDs, the
sending number, and the original message ID when available. The reply event
includes elapsed time but no message body. If your team has access to the
server-credential event stream beta, its entries expose the event type and time
without these recipient fields. Use the Campaigns API to retrieve recipient
status from a stream notification. Client tokens cannot open that stream.

The Platform API also lists the campaign's lifecycle history, most recent first:

```bash
curl "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID/events?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

Each entry carries `kind` (`launched`, `rescheduled`, `paused`, `resumed`,
`cancelled`, `completed` or `failed`) and the time it happened. A `rescheduled`
entry has `payload.previousScheduledAt` and `payload.scheduledAt`. A `failed` entry has
`payload.reason: "all_recipients_failed"`. The campaign fails when every recipient
settles as failed. If any recipient was sent or skipped, the
campaign completes and its counts show those outcomes.

## Pause, resume and stop

**Console:**

Open the campaign and select **Pause**, **Resume** or **Stop**. Stop asks you to
confirm with **Stop campaign**; **Stop requested** confirms that the request
was accepted. The page refreshes until the campaign reaches **Cancelled** and
shows the final recipient results.

**API:**

```bash cURL
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/pause" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Idempotency-Key: september-launch-pause-1"

curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/resume" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Idempotency-Key: september-launch-resume-1"

curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/stop" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Idempotency-Key: september-launch-stop-1"
```

```typescript TypeScript
await messaging.campaigns.pause("<project-slug>", campaignId);
await messaging.campaigns.resume("<project-slug>", campaignId);

const stopped = await messaging.campaigns.stop("<project-slug>", campaignId);
if (stopped.data.data.operationId !== null) {
  await platform.operations.wait(stopped.data.data.operationId);
}
```

Resume and stop use `POST .../resume` and `POST .../stop` on the same campaign
path. On the Platform API, use `POST /platform/campaigns/{campaignId}/pause`,
`/resume` and `/stop`.

*TypeScript:*

`create`, `launch`, `pause`, `resume` and `stop` create an idempotency key when
you pass none. If a response is lost, read the campaign before you try again.

Pause holds a running campaign; sends already in progress finish. Resume sends
the remaining recipients after the same checks as before the pause, including
the [send window](#choose-when-the-campaign-sends).

Stop cancels. Recipients not yet sent are not sent: each queued recipient becomes
`skipped` with `failureReason` `campaign_cancelled` and is counted once in
`skippedCount`. The campaign moves to
`cancelling`, then to `cancelled` once sends already in progress finish. A
campaign with no active delivery run is `cancelled` at once and `operationId` is
`null`. Stopping is never blocked by suspension or by a lost tier entitlement,
so a restricted campaign can always be stopped. Sends already in progress can
finish while the campaign is `cancelling`.

A campaign that has no active delivery run cannot be paused or resumed. Stop it,
duplicate it, and launch the copy.

## Archive or delete

Archive a `completed`, `failed` or `cancelled` campaign when you want to keep
its history while marking it archived. A campaign that is still starting,
running, paused or stopping cannot be archived.

Delete removes a `draft`, `completed`, `failed`, `cancelled` or `archived` campaign. Any
other campaign, and a draft that still has a scheduled launch, is refused with
`409`: stop it first, then delete it.
If a completed or failed campaign still has a final event to deliver, delete or
archive returns `409`. Archive and delete also wait for the delivery run
to finish. Retry after the event and run have finished.

**Console:**

Open the campaign, then **More campaign actions**, and select **Archive** or
**Delete**.

**API:**

```bash
curl -X DELETE "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

Archive with `POST /platform/campaigns/{campaignId}/archive`.

## Retry what failed

`POST .../requeue` moves failed recipients back to `queued`. Set
`includeSkippedError` to `true` to re-queue skipped recipients as well. In the
SDK, call `messaging.campaigns.requeue("<project-slug>", campaignId)`, with
`{ includeSkippedError: true }` to include them. A number
on the team's opt-out list is never claimed for sending, whatever its recipient
status is.

If delivery cannot start, the recipient stays queued for an automatic retry.
If a send may have reached WhatsApp but its result cannot be confirmed, the
recipient is not sent again automatically.

## Recipient variables in buttons

Button text and destinations are checked after recipient variable mappings and
fallbacks resolve. Copy codes are literal: they don't use recipient variables or
fallbacks. A test send is checked before it is admitted. A campaign checks
queued recipient values at launch and again at send time. A/B reserve recipients
are checked only at send time, because their variant is chosen then. A link may
use a whole-value variable such as `{{shop_url}}` or an inline fallback such as
`{{shop_url | https://example.com}}`; its resolved value must be an absolute
HTTPS URL with a hostname and at most 2,048 UTF-8 bytes. Call destinations must
contain only digits and an optional leading `+`, with 6–20 characters in total.

Expanded labels, body and footer must fit the selected transport's limits.
Official reply labels must remain distinct after substitution. Linked template
copy controls need a nonblank code of at most 256 UTF-8 bytes. Frozen follow-up
templates receive the same native-control checks as the initial template.
