# Turn on the warm-up plan

> Give every Number in a project a daily message allowance that grows over its first weeks and shrinks when its Health falls.

A new WhatsApp Number that sends hundreds of messages on its first day is the
pattern WhatsApp restricts fastest. The warm-up plan gives every Number in a
project a daily allowance that starts small, grows over the Number's first
weeks and shrinks when its Health falls.

The plan is off until you turn it on. Turning it off is always allowed.

## Before you begin

- The warm-up plan is part of BanSafe Lite, included on Standard and Pro
  Numbers. Turning it on is refused with `warmup_plan_not_entitled` when no
  Number in the project is on one of those tiers. See
  [Number tiers](https://docs.polymorfa.com/billing/number-tiers).
- In the Console, you need the owner or admin role on the team to change the
  plan. Members can read it.
- Through the API, use a team key or project token with `sessions:manage` to
  change it and `sessions:read` to read it.

## How the allowance works

Each Number gets one allowance per day, from its age and its Health band:

- On its first day a Number may send **20** messages.
- The allowance grows in a straight line to the daily cap of **2,000** over
  **14** days.
- The Health band scales the result: **good** keeps all of it, **fair** three
  quarters, **poor** half, **failing** a quarter. A Number without a fresh
  estimate keeps all of it, because the ramp is already cautious.
- The allowance never falls below the first-day figure or rises above the cap.

A Number seven days in with good Health may send 1,010 messages that day; with
poor Health, 505. You can change the first-day figure and the length of the
ramp. The 2,000 daily cap per Number is fixed, and campaigns already obey it.

The allowance resets at **midnight in the Number's own country**, worked out
from its phone number.

### How Polymorfa counts a Number's age

The ramp counts from the earliest proof the Number was active: when it was
linked, or its oldest message in history if that is earlier. A Number with
no such proof starts the ramp on the day you turn the plan on. The Number's
Health response reports this as `tenureSource`: `history`, `link` or `plan`, or
`null` when the evidence cannot be classified.

## Turn on the plan

**Console:**

1. Open the project's **Safety** page, select **Settings** and find **Warm-up plan**.
2. Turn on **Warm-up plan on for this project**.
3. Set **Messages on the first day** (1 to 2,000) and **Days to reach the cap**
   (1 to 90). The Console draws the ramp as you change them.
4. Select **Save warm-up plan**.

**API:**

Send only the settings you want to change:

```bash
curl -X PUT "https://api.polymorfa.com/platform/projects/$PROJECT_ID/warmup-plan" \
  -H "Authorization: Bearer $POLYMORFA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "warmupDays": 14, "dailyStart": 20 }'
```

| Field | Values |
| --- | --- |
| `enabled` | `true` or `false` |
| `warmupDays` | 1 to 90 |
| `dailyStart` | 1 to 2,000 |

The Messaging API serves the same setting at
`/messaging/projects/{projectId}/warmup-plan`. See
[Update the warm-up plan](https://docs.polymorfa.com/api/warm-up-plan/update-project-warmup-plan).

The response carries the plan, the cap and the allowance by day for a Number
with good Health:

```json
{
  "projectId": "3f9c...",
  "plan": { "enabled": true, "warmupDays": 14, "dailyStart": 20 },
  "ceiling": 2000,
  "curve": [
    { "day": 0, "allowance": 20 },
    { "day": 1, "allowance": 161 },
    { "day": 7, "allowance": 1010 },
    { "day": 14, "allowance": 2000 }
  ],
  "entitled": true,
  "entitlementReason": null
}
```

The plan is stored before any Number is told about it. If a connected Number
does not confirm it, the request returns `503 propagation_pending`; the plan is
already stored and Polymorfa keeps delivering it.

If the project loses BanSafe Lite while the plan is on, you can still turn it
off. Turning it on again needs a tier that includes it.

## Check a Number's allowance

**Console:**

Select the Number on the **Safety** page and open **Activity**. **Warm-up plan for this number**
shows **Allowed today**, **Sent today**, **Day of the ramp** and when the
allowance **Resets**. **Ramp starts from** names the evidence: **Message
history**, **Link date** or **Plan start**.

**API:**

`GET /platform/bansafe/health/{session}` carries a `warmup` block:

```json
{
  "warmup": {
    "enabled": true,
    "tenureSource": "history",
    "tenureDay": 7,
    "allowance": 1010,
    "sentToday": 640,
    "resetsAt": "2026-09-08T03:00:00.000Z",
    "curve": [{ "day": 0, "allowance": 20 }]
  }
}
```

When the project has no plan, `enabled` is `false` and `allowance` is null:
there is no ceiling, rather than a ceiling of zero.

`sentToday` reads `0` until the first send of the day.

## What happens at the allowance

Just before each send, Polymorfa reserves one slot in the Number's allowance
for the day. Concurrent sends and restarts share the same count, so the final
slot is never spent twice. A reserved slot stays counted even if the send then
fails or its result cannot be confirmed.

| Where | What happens |
| --- | --- |
| Messaging API send | Allowance used up: `429 bansafe_daily_allowance_reached` with the seconds until reset. Slot not confirmed: `503 bansafe_accounting_unavailable` with `retryAfter: 5`. Another attempt already holds a slot for this send: `409 bansafe_send_outcome_unknown`. |
| Webhook | `message.failed` carries the same code. Allowance and accounting refusals use `error: "blocked_by_safety"`; an unknown outcome uses `error: "send_failed"`. Retryable failures include `retryAfter`. |
| Campaigns | The recipient waits for the next reset, or is requeued after at least five seconds when the slot could not be confirmed. An unknown outcome fails the recipient without a retry. |

To handle these responses:

- After `429`, send the message again after the reset. Nothing changes on the
  Number and no restriction is applied.
- After `503`, retry the same message after `retryAfter` seconds, one retry at a
  time.
- After `409`, do not retry automatically. Check the message's delivery state
  before you decide to send a new one.

Creating a group and adding people to one do not count against the allowance;
safety limits still apply. Test numbers do not use an allowance. The smallest
of the allowance, the Number tier's throughput, a campaign's own pacing and any
restriction wins.

## See also

- [Turn on Safe Mode](https://docs.polymorfa.com/safety/safe-mode)
- [Read a Number's Health](https://docs.polymorfa.com/safety/health)
- [Set a Health rule and handle restrictions](https://docs.polymorfa.com/safety/restrictions)
