Warm up alphanumeric and international sender IDs
Orbit’s number-warming engine paces new US 10DLC numbers along a daily cap until carriers trust them. But in EMEA and MENA regulated corridors, most traffic originates from alphanumeric sender IDs (“ACME”, “OTP”) and international long codes, and those identities are not provisioned numbers in your Orbit number inventory. The per-number engine had nothing to key on, so a brand sender could jump straight to full volume on a fresh corridor with no ramp at all. The sender warm-up endpoints close that gap. They compute a warm-up meter for every alphanumeric sender ID and international long code you send from: a recommended daily send ceiling on a graduated ramp, plus a DLR-driven reputation score. Everything derives from your own message history, so there is nothing to configure. The meter starts reporting as soon as a sender has outbound traffic.Why sender IDs warm differently from DIDs
Carriers build sender trust per origination identity, whether that identity is a number or a sender ID. A brand-new alphanumeric sender that fires a full campaign on day one looks abusive to carrier anti-spam scoring, exactly like a cold 10DLC number: messages submit (and bill) but drop before delivery. The two estates differ in how Orbit can see them:- A 10DLC number is provisioned in your account, so the number-warming engine tracks it per number and enforces a hard daily cap at send time.
- A sender ID is a free-form origination identity, not a provisioned number. The per-number engine cannot see it. The sender warm-up endpoints aggregate your outbound SMS and MMS traffic per
fromvalue instead, and surface the ramp as a meter you pace against.
alphanumeric (any sender containing letters) and international_long_code (a non-NANP numeric sender). US and Canadian 10DLC numbers are excluded because the number-warming engine already owns them, and short codes are excluded because they are pre-vetted for high throughput from day one.
The meter is advisory: it publishes a recommended daily ceiling and a reputation trend rather than refusing sends. The hard
429 quota gate applies to US 10DLC numbers under the number-warming engine. For sender IDs, the carrier is the enforcement layer, which is exactly why pacing under the recommendation matters (see the operation runbook).The graduated ramp
Each sender’s recommended daily ceiling grows along a geometric curve keyed todays_active, the whole UTC days since the sender’s first outbound send:
That is roughly 30 percent compounding per day from a day-0 allowance of 200, reaching the 100,000-per-day ceiling around day 24. The curve is tuned for the steady-state volume a corridor-wide brand sender carries, well above the per-number curve.
The meter is computed from your tenant’s own
messages records: outbound SMS and MMS over a 60-day history window set days_active and the volume totals, while the reputation signals use the most recent 30 days. There is no setup step and no per-sender configuration; a sender that has never sent simply has no meter yet.
The list endpoint returns the curve constants in a ramp object (base_daily, growth_factor, max_daily, ramp_days), so you can reproduce today’s ceiling for any sender in your own tooling.
Reputation feedback adjusts the curve downward when carrier feedback degrades (see the reputation score): recommended_daily_ceiling is always at or below the raw curve value in base_daily_ceiling, never above it.
Read your whole fleet
GET /api/v1/messages/senders/warmup returns a meter for every warmable sender in your account, busiest first:
Reading a sender’s meter
limit (1 to 500, default 100) caps how many senders the list returns; the busiest always make the cut.
Forecast one sender
GET /api/v1/messages/senders/warmup/lookup?sender=<exact from value> returns one sender’s meter plus the day-by-day forecast of the curve, the same data the dashboard warm-up chart renders:
days_active: 9— the sender first sent 9 UTC days ago, so today’s raw curve value isforecast[9].base_daily_ceiling: 2120—min(200 × 1.3^9, 100000), the unadjusted curve for today.recommended_daily_ceiling: 2120— equal to the base here because the reputation tier is healthy. When feedback degrades, this is the value that drops whilebase_daily_ceilingkeeps climbing.forecast— 25 entries, day 0 through day 24. Render it as the projected line and overlay today’s send count onforecast[days_active]to chart progress, the same way the 10DLC guide charts the progression forecast.
null when the sender has no outbound SMS/MMS traffic in the history window, or when it is not a warmable scope (a US 10DLC number, a short code, or an unknown sender).
The reputation score
Each meter’sreputation is computed with the same kernel as the per-number health surface, over the same 30-day DLR window. A sender’s score is therefore directly comparable to a number’s score: 88 on a sender ID means the same delivery quality as 88 on a 10DLC number.
The score (0 to 100) blends three DLR-driven signals from your recent sends:
- Delivery rate — confirmed deliveries over sends. High delivery keeps the score up.
- Failure rate — hard failures pull it down.
- Complaint-coded failures — carrier error codes that indicate the recipient filtered or blocked the message. These weigh heaviest, because they are the strongest filtering signal carriers emit.
min_sample_size); below that you get score: null and tier unknown, and the ramp runs at the full curve on benefit of the doubt.
ramp_reason states the decision in plain text, for example reputation 'poor' (score 41.2) — holding ramp at 50% of curve.
Read it before a campaign. If the sender you plan to push shows holding or throttled, fix the deliverability problem first (opt-in quality, list hygiene, template content) and let the tier recover. Pushing full volume into a held sender burns ceiling on traffic the carriers are already filtering, and keeps the score down.
Operation runbook
Pace campaign volume under the per-day ceiling. Before a launch, read each sender’srecommended_daily_ceiling and plan the day’s volume at or under it. A 2,000-send ceiling runs comfortably at a modest campaign throttle_rate spread across the day; the same volume fired in a burst lands on carriers all at once and reads like a spam wave. The ceiling is per sender, per UTC day, so splitting a launch across several warmed sender IDs gives you the sum of their ceilings, the same way it does for numbers.
Know what happens when you exceed it. The sender meter is advisory: Orbit does not return a quota error when an alphanumeric sender goes over its recommended ceiling, because the regulated corridors these senders serve are exactly where you want visibility rather than a hard stop. The carrier is the enforcement layer, and SMS bills at submit, not at delivery, so over-ceiling volume that gets filtered still bills. That is the cost the ramp exists to avoid. US 10DLC numbers are different: the number-warming engine enforces the cap with 429 WARMING_QUOTA_EXCEEDED before submit (see Warm a new 10DLC number). Run both estates through the send-gates preflight checklist before launch.
Correlate warming state with deliverability insights. When a sender reads holding or throttled, open the deliverability reading for the same window: the failure and complaint rates there are the same signals feeding reputation.breakdown. A critical tier with a complaint-rate spike usually traces to one bad list or template; fix that and the tier recovers on the next 30-day window of traffic.
Watch the transition days. Day 24 is when the curve reaches the 100,000 ceiling and warmup_complete flips true. Graduation is time-driven, but a sender that reaches the ceiling while degraded keeps its throttled recommendation until the reputation recovers. Keep reading the meter after graduation: a mature sender whose tier drops to poor still gets held at half its (now full) ceiling.
When to use which guide
Required scopes
Both endpoints are read-only and accept eithermessages:read or messages:write. A key without one of the two receives a 403.