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; for the statuses and events, see 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. 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.
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:
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"
}'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.
- Type: choose Broadcast, A / B test or Drip.
- 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.
- Compose: write up to 10 messages, or choose Use a template. An A/B test shows Variants here, and a drip shows Steps.
- 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 table lists the API values behind each preset.
- 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 before sending.
- 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.
- 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 with recipientListId, or do both.
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 }
}
}'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 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:
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" } }] }'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.
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"'"] } }'await messaging.campaigns.update("<project-slug>", campaignId, {
name: "September launch (EU)",
senderConfig: { sessionIds: ["<number-id>"] },
});The Platform API accepts the same changes at API Update campaign, and also messagesArray (see 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.
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.
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 instead. A campaign with a follow-up sends a single first message.
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:
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" }
}
}'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:
- The recipient's value for
source, or for the variable of the same name whensourceis omitted. A blank or whitespace-only value counts as no value. - The mapping's
fallback. - 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.
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." } }
]
}'keyis unique in the campaign: a lowercase letter, then up to 15 lowercase letters, digits,_or-.weightis an integer from 1 to 99, and the weights add up to 100.sourceis 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
nullto remove them. After launch an update returns409. - 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.
tomust 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.
sessionIdmust be connected and on a tier that includes Campaigns, the same requirement as launch. When the campaign selects numbers withsenderConfig.sessionIds, test from one of them. - Variables. Without
sampleRecipientIdorvariables, 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 withsampleRecipientId, and override single values withvariables. 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
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" }
}'{
"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 API Test send campaign, 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:
{
"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:
- the zone in the recipient variable named by
timeZoneVariable, when it is a valid IANA name; - otherwise the zone of the phone number's country, when that whole country uses one UTC offset. For example,
+44numbers useEurope/London. Countries with several offsets, such as the United States, Brazil and Mexico, do not resolve this way; - 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
# 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 }"// 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.
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, 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 |
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.
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:
curl -X GET "https://api.polymorfa.com/platform/campaign-settings" \
-H "Authorization: Bearer $POLYMORFA_KEY"{ "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:
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.
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
# 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 }"// 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 API Reschedule campaign, 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 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.
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"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:
{
"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.
Download recipients as CSV, one page at a time, with Export 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:
#!/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// 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:
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/analytics" \
-H "Authorization: Bearer $POLYMORFA_KEY"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 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.
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"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=....
Campaign analytics report the funnel and the reply timing:
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.
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:
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
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"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 API Pause campaign, /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.
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
curl -X DELETE "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID?projectId=$PROJECT_ID" \
-H "Authorization: Bearer $POLYMORFA_KEY"Archive with API Archive campaign.
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.