Skip to main content

​
Warm a new 10DLC number

United States carriers build sender trust per number. A brand-new 10DLC number that sends at full campaign volume on day one looks abusive to carrier filtering, even when the campaign is registered and approved. Orbit gates outbound sends on every US 10DLC number while it warms up: a daily cap that rises along a growth curve until the number graduates as warmed. Warm-up requires no configuration. When a number starts warming, you read its state, pace your sends under the cap, and let the ramp finish.

​
Why warm a new 10DLC number

Carriers accrue sender trust as volume ramps and recipients accept the traffic. A number that jumps straight to tens of thousands of segments per day gets filtered — messages submit (and bill) but drop before delivery. Warming protects you in both directions:
  • Carriers see a compliant sender. Daily volume grows in the shape carriers publish for 10DLC onboarding, so the number earns trust instead of tripping filters.
  • You do not pay for dropped messages. Orbit enforces the per-number daily cap before each send. An over-cap send returns a 429 with code WARMING_QUOTA_EXCEEDED instead of silently submitting to the carrier and being filtered.
The cap is per number (per DID), per UTC day. Every number you warm ramps independently, and total campaign throughput at launch scales with how many warm numbers you have.

​
Why it protects you on billing

SMS billing happens at submit, not at delivery. Without the warming gate, a campaign that exceeds what carriers accept from a cold number still submits every segment — the carrier then drops them at its filtering layer and you pay for sends no recipient ever sees. The gate refuses over-cap sends before submit, so a cold number can only bill for what carriers will actually accept.

​
Read a number’s warming state

Get the full warming-tier state for one number:
The response is null for a non-10DLC number (toll-free, international, or a US number with warming not enabled).

​
Response fields

​
The four phases and their caps

Phases only advance forward. If a trust score drops, the number keeps its current phase until the score supports the next advance — the cap moves up or holds, never cuts mid-day.
The phases and tier caps above follow the published 10DLC throughput tiers from The Campaign Registry and the major carriers. External vetting (the verified → 200,000 step) is the TCR brand-vetting tier, not an Orbit-side flag.

​
Follow the 15-day progression forecast

For a lighter-weight view — and the forecast the dashboard chart renders — read the progression endpoint:

​
What the fields mean

  • warming_state — off (no warming on this number), warming (ramp in progress), or warmed (graduated; the gate no longer applies).
  • warming_max_daily_sms — today’s ramp ceiling after carrier-feedback adjustment. Persisted once per scheduler tick so the dashboard chart renders with no extra reads.
  • days_warmed — whole days since warming_started_at; the forecast index for today.
  • base, growth, ceiling — the growth-curve constants: 50 sends on day zero, roughly 35 percent daily compounding, hard-capped at 3,000 per day.
  • forecast — fifteen entries, day 0 through day 14. Each entry’s ceiling is the projected daily ceiling for that day. Render it as a projected line and overlay current_day_count on forecast[days_warmed] to chart progress.

​
How the ramp curve interacts with carrier feedback

The base curve is min(base * growth ^ days_warmed, 3000) — it reaches the 3,000-send ceiling around day 14. A freshness loop runs on top of the curve at every tick, using the number’s deliverability health tier:
  • Healthy delivery — the ramp proceeds at the full base ceiling.
  • poor health tier — the ceiling holds at half the base value.
  • critical health tier — the ceiling drops to a quarter of the base value.
A number that reaches the ceiling only graduates to warmed when its delivery feedback is healthy. A number that hits the ceiling while degraded stays in warming at its throttled ceiling until its reputation recovers.

​
Pace your sends under the cap

The practical question is how to keep campaigns under a cap that changes every day. Let the gate tell you. When a send would push a warming number over today’s ceiling, the API returns 429 with code WARMING_QUOTA_EXCEEDED. The error details carry retry_after (seconds until the counter resets at midnight UTC) and the full current ceiling. Handle it by pausing sends from that number until retry_after elapses, or by routing further sends through an already-warmed sender. Throttle the campaign, not just the API calls. Set throttle_rate on the campaign to spread sends across the day at a rate the ceiling supports. For example, a 4,000-send day runs comfortably at one message per second for a few hours; the same volume fired in a burst burns the whole daily ceiling in minutes and returns quota errors for the rest of the campaign. The campaign throttle_rate field is per-second — the warming cap is per-day — so combine a modest throttle with the quota-error handling above. See End-to-end campaign launch for the full throttle_rate reference. Split launch volume across warm numbers. Because the cap is per number, a campaign assigned to several warming numbers gets the sum of their daily ceilings. Buying a handful of numbers before launch and warming them in parallel is the fastest way to reach full volume. Watch the transition days. The phase-change moments to plan around:
  • Day 14 — the initial phase’s linear ramp ends. The number graduates to ramp (or straight to steady / verified if its trust score qualifies), jumping from roughly 2,000/day to 4,000 or 10,000.
  • Trust score crossing 51 and 76 — advancement to steady and then verified is event-driven on the score, not the calendar.

​
How progression advances (the hourly tick)

A dedicated hourly scheduler walks every number with warming_state = 'warming': it re-computes today’s base ceiling from the growth curve, applies the carrier-feedback adjustment above, and persists the result as warming_max_daily_sms. A number that reaches the 3,000-send ceiling with healthy delivery feedback graduates to warmed. The phase column on the warming state endpoint (initial → verified) moves separately, on a daily cadence that also applies the trust-score thresholds and mirrors the day’s send count. A missed scheduler tick always resolves on the next run — progression is a stateless re-compute from the number’s stored state, so the ramp self-heals.
Cap enforcement reads the live counter, never the persisted mirror — so a send is never gated by a stale tick, and the current_day_count you read is accurate to the second.

​
Warming inside the go-live checklist

Section 9 of the go-live checklist covers launch pacing — canary steps, rollback, throughput within quota. Add warming to that plan for a US SMS launch:
  1. T-minus 2 weeks. Start warming every number you plan to send from, before the launch campaign exists. The ramp runs on real sends, so route your normal transactional traffic through the new numbers while you wait.
  2. Launch planning. Total peak-day volume must stay under the sum of your numbers’ daily_cap values. The progression forecast tells each number’s ceiling on launch day; if the sum is short, either start warming more numbers earlier or plan a multi-day campaign window.
  3. Launch day. If a number hits its ceiling mid-launch, sends return WARMING_QUOTA_EXCEEDED rather than dropping at the carrier — catch the 429, pause that sender, and let surplus volume flow through the numbers with remaining headroom.
  4. Post-launch. Keep watching warming_phase until every launch number reads verified (or warming_state: warmed). Numbers sitting at initial or ramp with unresolved poor health leave throughput on the table — fix their delivery health and the ramp resumes.
A number that finishes warming during business as usual graduates the same way: read the state endpoint once a day, note the phase advance, and widen campaign schedules as caps grow.

​
Troubleshooting