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

Campaign safety checks

Learn what a campaign checks before it sends: the tier gate, throughput ceilings, opt-outs, per-recipient holds, the warm-up ramp and Cloud API Number standing.

View as Markdown

Campaigns is the only bulk sending path in Polymorfa. A loop over POST /messaging/{session}/messages/send opens the bulk_outside_campaigns finding on the Number that makes it, so outreach to people who have not written first belongs in a campaign, where the pacing, the per-number caps, the opt-out list, and the contact check are applied for you. See Findings and Send a campaign.

This page states every check a campaign send passes and the exact refusal you get when one fails. Each code is listed in Errors.

Both public surfaces run these checks. A campaign behaves the same whether you created and launched it through /messaging/projects/{projectSlug}/campaigns or through /platform/campaigns.

Campaigns is a Pro capability#

Campaigns send from Numbers on a Number tier that includes Campaigns: Pro. You can create and edit a draft on Free or Standard, and a draft can select Numbers on any tier. In the Console, Free and Standard Numbers appear disabled in the sender selection, with an upgrade action.

At launch, every number selected with senderConfig.sessionIds must be in the project, connected, and on a tier that includes Campaigns, and all selected numbers must use one sending type. A campaign that selects no numbers draws only from eligible numbers in its project, and its project must have at least one Number on a tier that includes Campaigns. It also sends through one sending type: WhatsApp numbers when any are ready, otherwise Cloud API numbers, otherwise test numbers.

WhenWhat happens
You create or edit the draftThe draft is saved on any tier; no message is sent
You change the selection after launchThe launch checks run on the new selection, including for a scheduled campaign that has not started
You launch it402 campaigns_not_entitled when a selected Number is missing or its tier does not include Campaigns, or when a campaign without a selection has no such number in its project. 400 invalid_parameter when a selected number is not connected or the selection mixes sending types
While it is runningThe campaign pauses when a selected number that is ready to send has lost Campaigns, or when no number in an unselected pool has Campaigns. campaign.paused carries the reason and the code campaigns_not_entitled. Upgrade the number or change the selection, then resume

A selected number that disconnects or is cooling down while the campaign runs is skipped until it is ready again; the campaign does not pause for it. If that number also lost Campaigns, the campaign pauses once it is ready to send again. If a selected number is removed from the project, or selected numbers end up on different sending types (for example after a number moves to Cloud API), the campaign pauses and campaign.paused carries the code invalid_parameter. Change the selection, then resume.

A Number whose tier cannot be resolved is treated as not entitled. The gate fails closed.

Contact frequency caps#

A contact cap limits campaign messages to one phone across your team's campaigns, projects and sending numbers. It includes first messages, sequence messages and receipt-timed follow-ups. Test sends and messages outside campaigns do not count.

Set the team cap#

Console

  1. Open Campaigns, then Settings.
  2. Under Contact frequency cap, if your team has not joined the beta, select Preview and join it in Opt-in features.
  3. Enter a limit for Per contact, rolling 24 hours, Per contact, rolling 7 days, or both. Leave a field empty for no limit in that window.
  4. Select Save.

Select Remove limits to clear both windows. Removal works even when the beta is not available to your team. If someone else saved the cap after you opened the page, the Console asks you to load the latest settings before you save again. Team members who are not owners or admins see the saved cap but cannot change it.

API

Read or replace the team cap with GET /platform/campaign-settings/frequency-cap and PUT /platform/campaign-settings/frequency-cap. Use a team key with campaigns:read or campaigns:manage, respectively. Project tokens cannot manage team settings. Signed-in team owners and admins can change the settings.

FieldAccepted valueMeaning
maxPer24HoursInteger 1 to 50, or nullMaximum messages to a phone in the rolling last 24 hours
maxPer7DaysInteger 1 to 200, or nullMaximum messages to a phone in the rolling last 7 days
revisionRevision from the latest readPrevents overwriting another edit; a stale value returns 409

Send both limit fields when replacing settings. Both null removes the team cap. When both are set, the 24-hour limit cannot exceed the 7-day limit. A team that has never saved settings has both limits null and revision 0.

Set a campaign cap#

A campaign can have its own cap. For each window, the lower of the campaign cap and the team cap applies, so a campaign cap can only make sending stricter.

Console

  1. In the campaign builder, open the Schedule step.
  2. Under Frequency cap for this campaign, enter one or both limits. The team cap is shown beside them.
  3. The draft saves automatically. Review lists the cap before launch.

On a launched campaign, the campaign page shows its cap. You can change or remove it only while the campaign is a draft or paused. Pause a running campaign first. Select Remove cap to go back to the team cap alone.

API

A campaign's optional frequencyCap uses the same limit fields. For each window, the lower of its limit and the team's limit applies. A campaign cap can only make sending stricter. Change it while the campaign is a draft or paused; a running campaign returns 409. Removing it leaves the team cap in force.

If your team loses beta access, a campaign with its own cap cannot launch or resume until you remove the cap or access returns.

How the cap is counted#

The check reserves capacity atomically before sending. Live claims, successful sends and uncertain send outcomes count; failed, released or deferred claims do not. Messages over the cap are skipped with frequency_cap_exceeded. For first-message skips, the recipient log and CSV export expose failureReason: frequency_cap. Filter them with status=skipped&reason=frequency_cap. For a later sequence message, the recipient keeps its first-send status and its remaining sequence stops. A capped receipt-timed follow-up is cancelled with that reason. Changing a cap never retries settled skips.

Campaign analytics reports frequencyCap.skippedRecipientCount, counting each recipient with a capped message once. In the Console, the campaign's Analytics page shows it as Skipped by frequency cap. Logs shows campaign.frequency_cap.skipped. The campaign.recipient_skipped event carries the reason and messageIndex; a receipt-timed follow-up also carries followUpId.

If beta access is withdrawn or cannot be checked, campaigns using a saved team or campaign cap pause before their next dispatch. Saved limits remain readable and removable. To send without the beta, remove both applicable caps and resume. Normal sender, opt-out, funding and safety checks still apply.

Throughput limits#

senderConfig.throughput sets the campaign's pacing. A value above its limit is refused with 400 campaign_throughput_capped naming the field. The per-number caps are checked when you save the draft and again at launch. The rate limit depends on the selected Numbers' tiers, so it is checked at launch:

FieldDefaultLimit
ratePerMinute20At most 6,000, the Pro tier's throughput
perNumberHourlyCap60At most 300
perNumberDailyCap500At most 2,000
jitterMinMs800At least 800
jitterMaxMs3,500Above jitterMinMs
ackTimeoutMs5,000
coldSendPolicyholdhold or allow

A campaign that is already running is brought down to the limit rather than stopped, so a change mid-flight slows the campaign instead of breaking it. The caps are per number, not per campaign: two campaigns sharing a number share its caps. While a number is paced by a restriction, the campaign sends at the lower of its own rate and the paced rate, which Restrictions lists.

Delay presets#

A campaign sends one message at a time. After each message it waits 60000 / ratePerMinute milliseconds plus a random delay between jitterMinMs and jitterMaxMs. The Console's delay presets set these fields; send the same values in senderConfig.throughput to pace an API-created campaign the same way:

PresetratePerMinutejitterMinMsjitterMaxMsGap between messages
Fast608004,0001.8 to 5 seconds
Steady1280010,0005.8 to 15 seconds
Careful480030,00015.8 to 45 seconds
Slow180060,0001 to 2 minutes
Very slow0.5800180,0002 to 5 minutes

The per-Number caps and the rate limit of the selected Numbers' tiers still apply on top of a preset. A preset's rate above that limit is refused at launch with 400 campaign_throughput_capped.

Every campaign send is typed and paced#

A send that comes from a campaign always uses at least a typing indicator before each text message and jittered pacing, whatever Safe Mode settings the number carries. A campaign never raises the number's presence or read-receipt settings, because those are visible to your contacts in ways typing and pacing are not.

The pause a send takes is bounded by the campaign's own gap between recipients, so pacing never reduces the throughput you configured. See Safe Mode.

Opted-out numbers are never messaged#

A campaign checks your team's opt-out list twice. When the campaign launches, every recipient on the list is marked skipped with failureReason opted_out and counted once in skippedCount. At send time, a number on the list is never claimed, so a number added to the list after the campaign launched is still suppressed, and re-queuing a skipped recipient does not send to it.

Recipients who never wrote first are held#

The contact check is made per recipient, at send time, on the number that is about to send. A recipient who has never written to that number is held rather than messaged, and the hold carries 409 bansafe_cold_held.

Two things change the outcome:

  • Set senderConfig.throughput.coldSendPolicy to allow to message people who have not written first. This raises the number's ban risk; the default is hold.
  • Send to people who wrote to that number. The check is per number, so a contact who wrote to one of your numbers is still cold on another.

The hold is not a failure of the number. It is a fact about the recipient list. It applies on every tier that includes Campaigns, and it does not depend on the restriction ladder: it is your campaign's own coldSendPolicy. See Restrictions for the ladder itself and how each step lifts.

What safety does to a recipient#

A campaign send passes the number's restriction step as well as the checks above. What happens to the recipient depends on which check stopped it:

What stopped the sendThe recipientThe campaign
The recipient is on the team's opt-out listCounted once in skippedCount, never attempted, with failureReason opted_outKeeps running
The recipient has never written to this number and coldSendPolicy is holdCounted once in skippedCount, never attempted again, and reported by campaign.cold_blockedKeeps running
The sending number is paced by a restrictionQueued again and retried after the reported delay, with no delivery attempt spent and nothing counted as a failureKeeps running, and campaign.throttled reports the pass
The sending Number or the whole team is suspended, the tier no longer includes Campaigns, or the requested throughput is above the safety ceilingLeft queued, with the attempt given back so no retry budget is spentPaused, with campaign.paused carrying the reason and the code
An official WhatsApp Business number's quality rating or messaging limit fell during the campaignLeft queued, with the attempt given back so no retry budget is spentPaused, with campaign.paused carrying the reason and the code number_quality_dropped or messaging_limit_dropped
WhatsApp withheld a marketing message because the person reached their marketing message limitCounted once in skippedCount, never attempted again, with lastError whatsapp_marketing_limitKeeps running, and campaign.recipient_skipped reports the reason whatsapp_marketing_limit

A recipient safety holds back is never a delivery failure. failedCount counts sends WhatsApp refused, not sends Polymorfa never made.

Official WhatsApp Business numbers#

A campaign that sends from an official WhatsApp Business number also follows two signals from WhatsApp.

Per-person marketing message limit#

WhatsApp limits how many marketing messages one person receives from all businesses. When a person is at that limit, WhatsApp withholds the message and reports error 131049. WhatsApp asks senders to wait at least 24 hours before sending that template to the person again, so the campaign does not retry them:

  • The recipient is skipped with lastError whatsapp_marketing_limit.
  • campaign.recipient_skipped reports the reason whatsapp_marketing_limit.
  • The skip is counted once in skippedCount, not in failedCount.

WhatsApp can report this after it accepted the send. A recipient already counted in sentCount then moves to skippedCount. WhatsApp can also report the message as delivered to one of the person's devices and withheld on another. Delivery wins: the recipient counts as delivered, and it returns to sentCount.

To reach these people later, send to them in a new campaign at least 24 hours after the skip.

Number quality and messaging limit#

A running campaign pauses when a number it sends from loses standing with WhatsApp while the campaign runs:

What changedcampaign.paused code
The number's quality rating dropped, for example from green to yellow, or WhatsApp flagged the numbernumber_quality_dropped
WhatsApp lowered the messaging limitmessaging_limit_dropped

Polymorfa compares each number with its standing when the campaign started sending from it. A number that was already yellow at launch can run a campaign; it pauses only if it drops further. The rating is checked at most every five minutes while the campaign sends, so a drop can take up to five minutes to pause the campaign. Once Polymorfa sees the drop, the campaign sends nothing more from that number until you resume it.

Review the number's quality in WhatsApp Manager, then resume the campaign or stop it. A resumed campaign continues from the number's current standing and pauses again only if it drops further.

Stopping and deleting#

Stop always means cancel. It moves a draft, running or paused campaign to cancelling, then to cancelled once sends already in progress finish, and the recipients not yet sent are not sent. Stop is never blocked by a team suspension or by a lost tier entitlement, so a campaign a check paused can always be stopped.

Delete removes a draft, completed, failed, cancelled or archived campaign. A campaign that is still live, including a draft with a scheduled launch, is refused with 409 state_conflict: stop it first, then delete it. If a completed or failed campaign still has a final event to deliver, delete or archive returns 409 state_conflict. Retry after that event is delivered.

A new number ramps up#

A number's daily cap starts low and rises to the campaign's perNumberDailyCap over warmupDays days, in a straight line. With the defaults (warmupDailyStart 20, perNumberDailyCap 500, warmupDays 14), the ceiling on a day is:

DayDaily capDayDaily cap
0207260
1548294
2889328
312210362
415711397
519112431
622513465
14 and after500

A number is treated as new for its first 14 days here and in the warmup_ignored finding, which starts at the same 20 messages a day. The ramp alone does not keep that finding closed: check it on the number while a new campaign runs. See Findings.

The ramp is anchored to how old the number is, not to when it first ran a campaign: Polymorfa uses the earliest instant it can prove the number was in use, such as when the number was linked or the oldest message its history carries. The anchor only ever moves earlier, so a number that is already warm cannot be pushed back onto the ramp. A number whose age cannot be established is treated as warm and sends at the full cap.

While a number is on the ramp, recipients beyond the day's cap are not dropped. They stay queued for the next window, and campaign.cap_reached reports the number, the cap, and when the window resets.

WhatsApp can also cap how many new chats a linked-device number starts in a cycle. When WhatsApp has capped a number, the number leaves the pool until the cycle resets and campaign.cap_reached reports capType new_chat. See WhatsApp new-chat cap.

See also#