​

BYO SMPP carrier lifecycle

​

Attach

1. POST /api/v1/messaging/smpp/carriers creates the carrier with the bind profile your upstream gave you: remoteHost / remotePort / remoteSystemId / remotePassword, plus how you want it treated: scope (all or by_country_mcc with an MCC list), priority (your own cost rank; lower wins), and status. The password is encrypted at rest and never returned in full again; reads only expose a remotePasswordSet boolean.
2. Validation at the boundary — the create hooks reject a host that points at localhost, a private range, or a cloud metadata endpoint, before anything tries to reach it on your behalf.
3. status starts as inactive. Stage the credentials, compare a dry-run quote, and flip to active when you want the route to go live. Setting active is the moment the next reconciliation pass provisions the SMPP connector and its routing rule on the platform edge; there is no separate “enable” call.
4. Failed or pending binds stay off the selection race (see health below), so a carrier you just attached never hijacks traffic on its first tick.

​

Health: probe, reconciler, and what a failing bind means

• Continuously (the reconciler). Every ~30-second pass reads your active carriers, asks the edge what the connector’s session looks like, and stamps the result back onto the row as bindStatus and lastSeenAt. The state your dashboard and reads show (BOUND, UNBOUND, BIND_FAILED:<reason>) is a projection of the last pass, never hand-set by the API. A connector that silently dropped its session shows up as a failed bind on the next pass and is nudged restarted so the bind cycle re-establishes.
• On demand (POST /api/v1/messaging/smpp/carriers/:id/test). A synchronous check that the row is well-formed and its stored credential decrypts. It reads the reconciler-stamped bindStatus back rather than blocking on a live dial, and it is rate-limited so a stuck upstream can’t be hammered.

​

Where the carrier feeds routing

• LCR scoring ([concepts/least-cost-routing]) multiplies four axes: costScore from your priority, deliveryQuality (smoothed delivered/terminal over a window), bindHealth (the value above: failed bind ≈ 0.05, unbound ≈ 0.4, stale bound hit slightly, unknown treated neutral), and a small stickyBonus for the incumbent. A failed bind nearly removes the carrier from contention; a missing health signal never punishes it.
• Route-quality and circuit breakers ([concepts/outbound-route-quality-and-circuit-breakers]) meter the route operationally over your own messages (delivery conversion, DLR latency, acknowledged-but-no-receipt) and, once you opt in, trip a breaker that suspends a sustained-failing route and records the failover channel. A flapping bind both loses its sticky bonus (the LCR failover moment) and, once the degradation becomes a sustained signal, feeds the trip gate.
• Dry-run preview. POST /api/v1/messaging/smpp/carriers/route-quote (and the policy-aware POST /api/v1/messaging/lcr/quote) runs the same engine the live gate does, so a preview cannot disagree with a live send.

​

Detach

• In candidateOrder it does not error. A stale id in your saved policy’s explicit candidateOrder is dropped at evaluation time; the remaining candidates fold back into scorer order, and the route picks the next-best entrant. A misconfigured (or now-missing) candidate order degrades, it never rejects a send.
• In-flight traffic already handed to the carrier finishes on the old route. New sends stop selecting it only after the pass completes, so a detach made during a burst can let a few in-flight messages drain.

​

Credentials and capacity

• Cost is not computable. The quote preview prices the Devotel wholesale row off the pricing ladder; a BYO candidate returns null for cents because your upstream spend lives outside Orbit. A fabricated 0 would mislead the preview. Your priority is the preference rank you give the scorer, not an Orbit price.
• Throughput and scope are yours. Two active carriers matching a destination resolve by priority, and a carrier scoped by_country_mcc never drags cross-region traffic it can’t serve. Set priority before you enable, and scope to the MCC list if the upstream only covers a region.

​

Example: attach → probe → dry-run quote with preferByo: true

# 1. Stage the carrier (inactive so no traffic yet)
curl -X POST https://orbit.devotel.io/api/v1/messaging/smpp/carriers \
  -H "Authorization: Bearer $DEVOTEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "My upstream SMSC",
    "type": "smpp",
    "remoteHost": "smsc.example-carrier.net",
    "remotePort": 2775,
    "remoteSystemId": "acct_001",
    "remotePassword": "••••••••",
    "bindType": "tx",
    "scope": "all",
    "priority": 10
  }'

# 2. Enable it (next reconcile pass provisions the connector)
curl -X PATCH https://orbit.devotel.io/api/v1/messaging/smpp/carriers/smppcr_abc123 \
  -H "Authorization: Bearer $DEVOTEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

# 3. Synchronous probe of the row after one pass
curl -X POST https://orbit.devotel.io/api/v1/messaging/smpp/carriers/smppcr_abc123/test \
  -H "Authorization: Bearer $DEVOTEL_API_KEY"
# → { ok: true, bindStatus: "BOUND", ... }

# 4. Dry-run: which route would a send to this destination take
#    under preferByo: true (candidates ranked, no side effects)
curl -X POST https://orbit.devotel.io/api/v1/messaging/lcr/quote \
  -H "Authorization: Bearer $DEVOTEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+12125550123",
    "policy": { "preferByo": true }
  }'
# The BYO carrier outranks the Devotel wholesale row when its
# composite score wins; its estimatedUnitCents stays null (BYO spend
# isn't computable), while the Devotel row carries the ledger price.

​

See also

• Least-cost routing (LCR) policy — how the winner is ranked and how candidateOrder and preferByo steer it
• SMPP edge model — the relay, the per-credential Jasmin user model, and the reconciler contract
• Outbound route quality and circuit breakers — operational metering and the trip gate a degrading route feeds
• Sender resolution — the step LCR runs after