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

Campaigns is the only bulk sending path in Polymorfa. A loop over
[`POST /messaging/{session}/messages/send`](https://docs.polymorfa.com/api/messages/send-message)
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](https://docs.polymorfa.com/safety/findings) and
[Send a campaign](https://docs.polymorfa.com/campaigns/send).

This page states every check a campaign send passes and the exact refusal you
get when one fails. Each code is listed in
[Errors](https://docs.polymorfa.com/api/errors#bansafe-and-safe-mode-codes).

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](https://docs.polymorfa.com/billing/number-tiers) 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.

| When | What happens |
| --- | --- |
| You create or edit the draft | The draft is saved on any tier; no message is sent |
| You change the selection after launch | The launch checks run on the new selection, including for a scheduled campaign that has not started |
| You launch it | `402 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 running | The 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

> **Note**
>
> **Contact frequency caps require access.** The beta must be offered to your
> team and your team must join it. Setting a limit without access returns
> `403 feature_unavailable`.

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](https://docs.polymorfa.com/teams/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`](https://docs.polymorfa.com/api/campaign-settings/get-campaign-frequency-cap)
and
[`PUT /platform/campaign-settings/frequency-cap`](https://docs.polymorfa.com/api/campaign-settings/update-campaign-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.

| Field | Accepted value | Meaning |
| --- | --- | --- |
| `maxPer24Hours` | Integer 1 to 50, or `null` | Maximum messages to a phone in the rolling last 24 hours |
| `maxPer7Days` | Integer 1 to 200, or `null` | Maximum messages to a phone in the rolling last 7 days |
| `revision` | Revision from the latest read | Prevents 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:

| Field | Default | Limit |
| --- | ---: | --- |
| `ratePerMinute` | 20 | At most 6,000, the Pro tier's throughput |
| `perNumberHourlyCap` | 60 | At most 300 |
| `perNumberDailyCap` | 500 | At most 2,000 |
| `jitterMinMs` | 800 | At least 800 |
| `jitterMaxMs` | 3,500 | Above `jitterMinMs` |
| `ackTimeoutMs` | 5,000 | |
| `coldSendPolicy` | `hold` | `hold` 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](https://docs.polymorfa.com/safety/restrictions#pacing-rates) 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:

| Preset | `ratePerMinute` | `jitterMinMs` | `jitterMaxMs` | Gap between messages |
| --- | ---: | ---: | ---: | --- |
| Fast | 60 | 800 | 4,000 | 1.8 to 5 seconds |
| Steady | 12 | 800 | 10,000 | 5.8 to 15 seconds |
| Careful | 4 | 800 | 30,000 | 15.8 to 45 seconds |
| Slow | 1 | 800 | 60,000 | 1 to 2 minutes |
| Very slow | 0.5 | 800 | 180,000 | 2 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](https://docs.polymorfa.com/safety/safe-mode).

## Opted-out numbers are never messaged

A campaign checks your team's [opt-out list](https://docs.polymorfa.com/campaigns/opt-outs)
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](https://docs.polymorfa.com/safety/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 send | The recipient | The campaign |
| --- | --- | --- |
| The recipient is on the team's opt-out list | Counted once in `skippedCount`, never attempted, with `failureReason` `opted_out` | Keeps running |
| The recipient has never written to this number and `coldSendPolicy` is `hold` | Counted once in `skippedCount`, never attempted again, and reported by `campaign.cold_blocked` | Keeps running |
| The sending number is paced by a restriction | Queued again and retried after the reported delay, with no delivery attempt spent and nothing counted as a failure | Keeps 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 ceiling | Left queued, with the attempt given back so no retry budget is spent | Paused, with `campaign.paused` carrying the reason and the code |
| An official WhatsApp Business number's quality rating or messaging limit fell during the campaign | Left queued, with the attempt given back so no retry budget is spent | Paused, 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 limit | Counted once in `skippedCount`, never attempted again, with `lastError` `whatsapp_marketing_limit` | Keeps 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 changed | `campaign.paused` code |
| --- | --- |
| The number's quality rating dropped, for example from green to yellow, or WhatsApp flagged the number | `number_quality_dropped` |
| WhatsApp lowered the messaging limit | `messaging_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:

| Day | Daily cap | Day | Daily cap |
| ---: | ---: | ---: | ---: |
| 0 | 20 | 7 | 260 |
| 1 | 54 | 8 | 294 |
| 2 | 88 | 9 | 328 |
| 3 | 122 | 10 | 362 |
| 4 | 157 | 11 | 397 |
| 5 | 191 | 12 | 431 |
| 6 | 225 | 13 | 465 |
| | | 14 and after | 500 |

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](https://docs.polymorfa.com/safety/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](https://docs.polymorfa.com/numbers/new-chat-cap).

## See also

- [How campaigns work](https://docs.polymorfa.com/campaigns/how-campaigns-work)
- [Restrictions](https://docs.polymorfa.com/safety/restrictions)
- [Safe Mode](https://docs.polymorfa.com/safety/safe-mode)
- [Errors](https://docs.polymorfa.com/api/errors#bansafe-and-safe-mode-codes)
