> ## Documentation Index > Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt > Use this file to discover all available pages before exploring further. # Send a campaign > Create a campaign with recipients, launch it, follow every recipient, and stop it, end to end through the API. A campaign turns a list of numbers into paced, safety-checked WhatsApp messages sent from the numbers in one project. This guide runs the whole path through the API: build the recipient list, launch, follow the send, and stop. Campaigns are the only bulk sending path in Polymorfa. Every send passes the plan, throughput, opt-out, contact and warm-up checks described in [Campaigns and number safety](/guides/engage-at-scale/campaigns-and-bansafe). ## 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 credential for that project | | Platform API | `/platform/campaigns` | Team API key with `projectId`, or a project token for its own project | Reading needs `campaigns:read`. Creating, launching, 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 API key names the project with `projectId` on every campaign request, and a project token is bound to its own project and omits it. ## Create the campaign with its recipients ### Use the console In the campaign builder, 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 before continuing. Wait for **Draft saved** before launching. If saving fails, the builder shows the reason and marks the changes as unsaved. A plan or sending restriction also appears in the review step; 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. 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](/guides/engage-at-scale/opt-outs) before sending. Scheduling uses your browser's local time zone. Check the zone beside the date and time and again in the review step before scheduling. ### Use the API Send recipients inline, point at an [audience](/guides/engage-at-scale/audiences) with `recipientListId`, or do both. ```bash theme={null} 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 } } }' ``` 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 campaign that pins none draws from every number in its project that is connected, not banned, and on a plan that includes Campaigns. Add more recipients while the campaign is still a draft, 1,000 per request: ```bash theme={null} 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" \ -d '{ "recipients": [{ "phone": "+14155550101", "variables": { "first_name": "Grace" } }] }' ``` 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`. 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. ## Launch ```bash theme={null} 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": 1758326400000 }' ``` 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](/guides/engage-at-scale/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 re-runs the create checks against the campaign's stored settings, so a campaign drafted while its numbers were entitled is refused if they moved to another plan in between: | Status and code | Cause | | -------------------------------- | ---------------------------------------------------------------------------------- | | `403 bansafe_org_suspended` | The team is suspended | | `402 campaigns_not_entitled` | No number the campaign can send from is on a plan that includes Campaigns | | `400 campaign_throughput_capped` | A requested throughput is above its safety ceiling; `error.param` names the field | | `409 state_conflict` | The campaign is not a draft, or is already launched and waiting for its start time | Create, launch, pause, resume and stop accept an `Idempotency-Key` header on the Messaging API; the Platform API accepts it on launch, pause, resume and stop. A repeated key is never a second launch. See [Errors](/api/errors#idempotency-completed). ## Follow the send List recipients in queue order with cursor pagination. `limit` is 1 to 100 and defaults to 25. ```bash theme={null} curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/recipients?status=skipped&limit=100" \ -H "Authorization: Bearer $POLYMORFA_KEY" ``` ```json theme={null} { "success": true, "data": [ { "id": "0c0e4f2a-2b1d-4a67-9bb2-1f7f4a2e91a3", "phone": "+14155550100", "variables": { "first_name": "Ada" }, "variantKey": null, "status": "skipped", "attempts": 0, "lastError": "opted_out", "externalMessageId": null, "queuedAt": 1758326400000, "sentAt": null, "deliveredAt": null, "readAt": null, "failedAt": 1758326402000, "respondedAt": 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`. `lastError` gives the stable reason a recipient failed or was skipped, such as `opted_out`. It never contains message content. `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 theme={null} 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. The Platform API also lists the campaign's lifecycle history, most recent first: ```bash theme={null} curl "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID/events?projectId=$PROJECT_ID" \ -H "Authorization: Bearer $POLYMORFA_KEY" ``` Each entry carries `kind` — `launched`, `paused`, `resumed`, `cancelled`, `completed` or `failed` — and the time it happened. 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 ```bash theme={null} curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/pause" \ -H "Authorization: Bearer $POLYMORFA_KEY" ``` Pause holds a running campaign; sends already in progress finish. Resume sends the remaining recipients after the same checks as before the pause. Stop cancels. Recipients not yet sent are not sent: each queued recipient becomes `skipped` with `lastError` `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 plan entitlement, so a restricted campaign can always be stopped. In the console, **Stop requested** confirms that your request was accepted. The detail page refreshes until the campaign reaches **Cancelled** and shows the final recipient results. Sends already in progress can finish during this transition. 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. ```bash theme={null} curl -X DELETE "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID?projectId=$PROJECT_ID" \ -H "Authorization: Bearer $POLYMORFA_KEY" ``` ## Retry what failed `POST .../requeue` moves failed recipients back to `queued`. Set `includeSkippedError` to `true` to re-queue skipped recipients as well. A number on the team's opt-out list is never claimed for sending, whatever its recipient status is.