Skip to content
Shortcut: /, ⌘K or Ctrl+K

Send a campaign

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

View as Markdown

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.

SurfacePathCredential
Messaging API/messaging/projects/{projectSlug}/campaignsProject token for that project
Platform API/platform/campaignsTeam 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:

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"
  }'

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 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 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.
  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.

FieldAccepted values
LabelLinked Devices: 1–256 UTF-8 bytes; Official API: 1–20 characters
Reply ID1–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
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
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
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
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
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
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.

Shell
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 happensResult
The first message fails after every attemptThe recipient is failed and no later message is sent
A later message is sentmessagesSent rises and a campaign.recipient_sent event with that messageIndex is sent
A later message fails after every attemptThe 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 messagesThe remaining messages are not sent and sequenceError is opted_out
The campaign is stopped between messagesThe remaining messages are not sent and sequenceError is campaign_cancelled
The campaign is paused between messagesThe 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
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
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.

Shell
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

Shell
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 API Test send campaign, with projectId when you use a team key.

A refused test sends nothing unless the table says otherwise:

Status and codeCauseWhat to do
400 invalid_parameterto is not a number connected to your team, or sessionId is not a number this campaign can send from; error.param names the fieldChoose a seed or sending number that meets the rules above
402 campaigns_not_entitledThe sending Number's tier does not include CampaignsMove the Number to Pro, or test from a Pro Number
409 bansafe_cold_heldThe seed has never written to the sending number, and the campaign holds first messagesSend any message from the seed phone to the sending number, then test again
409 state_conflictThe campaign is not a draft, has A/B variants or messageVariations, the seed opted out, or the sending number is a Hybrid Link numberTest before launch, or choose another seed or number. Campaigns with A/B variants or message alternatives cannot be test sent yet
422 campaign_variables_missingA variable in the selected content has no sample value, explicit value, or fallbackProvide the missing value or a campaign fallback before testing
429 rate_limit_exceededA test-send limit was reached (Polymorfa-RateLimit-Reason: campaign_test_send), or the number's campaign send cap was reachedWait for Retry-After
429 bansafe_throttled, 429 bansafe_daily_allowance_reachedThe sending number is paced or used its warm-up allowanceWait for Retry-After
503 session_not_readyThe sending number is not connectedReconnect it and test again
504 result_unknownThe outcome is unknown; the test can still arriveCheck 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" }
    ]
  }
}
FieldRule
timeZoneIANA 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.
daysOne to seven of monday to sunday, without repeats.
hoursOne 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.
recipientTimeZonetrue applies the window in each recipient's local time. Defaults to false.
timeZoneVariableRecipient 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

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
// 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 codeCause
403 bansafe_team_suspendedThe team is suspended
402 campaigns_not_entitledA 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_parameterA 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_cappedA requested throughput is above its safety ceiling; error.param names the field
400 invalid_parameterThe template is incomplete; error.param is templateId
400 template_not_approvedWhatsApp has not approved the template on a Cloud API number the campaign can send from
422 campaign_variables_missingSome recipients have no value and no fallback for a variable; the message names the variables and counts the recipients
409 campaign_approval_requiredYour 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_conflictThe 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_unavailableThe 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:

Shell
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:

Shell
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:

StatusMeaning
pendingWaiting for an owner or admin
approvedApproved; the action ran and operationId is its operation
rejectedRejected; the action did not run and nothing was sent
supersededA later request, or a change to the campaign, replaced it
expiredNot 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

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
// 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 codeCause
400 invalid_parameterscheduledAt is missing, or is not a positive whole number or null
403 bansafe_team_suspendedThe team is suspended. You can still stop the campaign.
409 state_conflictThe 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
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
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.

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:

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
// 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
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/analytics" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
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 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.

failureReasonMeaning
opted_outThe number is on the team's opt-out list
cold_heldThe number never wrote to the sending number and the campaign holds cold sends
campaign_cancelledThe campaign was stopped before this recipient was sent
invalid_recipientThe number is not a valid WhatsApp address
session_not_connectedThe sending number was not connected
ack_timeoutWhatsApp did not acknowledge the send in time
blocked_by_safetyA safety check refused the send before it was attempted; the recipient waits for the campaign to resume
send_failedWhatsApp refused the send, or its outcome could not be confirmed
missing_variableThe 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_capThe recipient reached the team's or campaign's rolling contact frequency cap
otherAny 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.

Shell
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=....

Campaign analytics report the funnel and the reply timing:

Shell
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/analytics" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
FieldMeaning
recipientCountRecipients on the campaign
sentCountMessages accepted by WhatsApp
deliveredCountRecipients whose device confirmed delivery
readCountRecipients who opened the message; a read implies a delivery
failedCountSends WhatsApp refused
skippedCountRecipients never attempted, such as an opt-out or a cold hold
respondedCountRecipients who replied
responseRaterespondedCount divided by sentCount, and 0 before anything is sent
averageResponseTimeMsMean time from send to first reply, and null before the first reply
minResponseTimeMs, maxResponseTimeMsFastest 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:

Shell
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
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
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

Shell
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.