BYO-SMPP Credentials API

Bring-your-own SMPP for organizations with existing carrier relationships. Orbit issues the credentials — when you create a credential set, Orbit generates the system_id and password (the password is shown once on create and via GET /{id}/reveal, and can be rotated). The SMPP host and port are platform-provided connection details returned on the credential, not values you supply. On create you only send optional settings (description, tpsLimit, allowedCidrs, dlrMode, dlrWebhookUrl); any other field is rejected. You bind to Orbit’s SMPP control plane (Jasmin) with the issued credentials, and Orbit reconciles them into its user store every 30 seconds and routes outbound SMS through your trunk. Base path: /api/v1/messaging Authentication: API key (X-API-Key) or session JWT.

Using the SDKs

Prefer the typed client, but this page’s endpoint has no helper yet — the generic request() keeps auth/retries and the { data, meta } envelope identical:

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data } = await orbit.request<unknown>(
  "GET",
  "/messaging/credentials"
);

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/messaging/credentials")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Raw curl in the body of this page works identically. Full SDK index at SDK quickstart.

Credentials

Method	Path	Purpose
`GET`	`/api/v1/messaging/smpp/credentials`	List credentials
`POST`	`/api/v1/messaging/smpp/credentials`	Add a credential set
`GET`	`/api/v1/messaging/smpp/credentials/{id}`	Get a credential
`PATCH`	`/api/v1/messaging/smpp/credentials/{id}`	Update description, tpsLimit, allowedCidrs, dlrMode, dlrWebhookUrl, status
`DELETE`	`/api/v1/messaging/smpp/credentials/{id}`	Remove
`GET`	`/api/v1/messaging/smpp/credentials/{id}/reveal`	One-time reveal of the password (audit-logged)
`POST`	`/api/v1/messaging/smpp/credentials/{id}/rotate`	Rotate password

The Node tab of each example below uses the Node.js SDK helpers under orbit.messagingConfig.smppCredentials. The methods pass your input through as sent — the documented request fields are the ones the API accepts.

Issue a credential

POST /smpp/credentials returns the plaintext password in the response body. Save it on receipt — after the 60-second reveal window closes, the password is unrecoverable and rotation is the only way to get a new one.

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/smpp/credentials \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Production bind — primary aggregator",
    "tpsLimit": 50,
    "allowedCidrs": ["203.0.113.0/24"],
    "dlrMode": "both",
    "dlrWebhookUrl": "https://example.com/webhooks/smpp-dlr"
  }'

const credential = await orbit.messagingConfig.smppCredentials.create({
  description: 'Production bind — primary aggregator',
  tpsLimit: 50,
  allowedCidrs: ['203.0.113.0/24'],
  dlrMode: 'both',
  dlrWebhookUrl: 'https://example.com/webhooks/smpp-dlr',
});

console.log(credential.data.id);       // smppcred_7f2a9c41be0d4c8ea3b15d6072f4c81b
console.log(credential.data.password); // shown once — store it now

201 Created:

{
  "data": {
    "id": "smppcred_7f2a9c41be0d4c8ea3b15d6072f4c81b",
    "systemId": "orb_k4x9",
    "password": "f3K9qLmZ2wXv8rTbNcE6hP4s",
    "description": "Production bind — primary aggregator",
    "tpsLimit": 50,
    "allowedCidrs": ["203.0.113.0/24"],
    "dlrMode": "both",
    "dlrWebhookUrl": "https://example.com/webhooks/smpp-dlr",
    "status": "active",
    "lastRotatedAt": null,
    "lastSeenAt": null,
    "bindCount": 0,
    "createdAt": "2026-08-25T09:14:32.418Z",
    "updatedAt": "2026-08-25T09:14:32.418Z",
    "smppHost": "smpp.orbit.devotel.io",
    "smppPort": 3550,
    "passwordRevealableUntil": "2026-08-25T09:15:32.418Z",
    "password_visible_once_warning": "Save this password now. The reveal window is 60 seconds — after that, rotate the credential to issue a new one."
  }
}

The systemId, password, smppHost, and smppPort are platform-issued — use exactly these four values when you configure your SMPP client bind.

Reveal the password

Within the 60-second window after create or rotate (check passwordRevealableUntil), GET /{id}/reveal returns the password once. Every reveal is audit-logged. After the window closes the endpoint returns 410 Gone.

curl https://api.orbit.devotel.io/api/v1/messaging/smpp/credentials/smppcred_7f2a9c41be0d4c8ea3b15d6072f4c81b/reveal \
  -H "X-API-Key: dv_live_sk_your_key_here"

const revealed = await orbit.messagingConfig.smppCredentials.reveal(
  'smppcred_7f2a9c41be0d4c8ea3b15d6072f4c81b',
);
console.log(revealed.data.password);

{
  "data": {
    "id": "smppcred_7f2a9c41be0d4c8ea3b15d6072f4c81b",
    "systemId": "orb_k4x9",
    "password": "f3K9qLmZ2wXv8rTbNcE6hP4s"
  }
}

Rotate the password

POST /{id}/rotate generates a new password and returns it once, in the same shape as the create response. The old password stops working on the reconciler’s next 30-second pass — update your SMPP client immediately.

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/smpp/credentials/smppcred_7f2a9c41be0d4c8ea3b15d6072f4c81b/rotate \
  -H "X-API-Key: dv_live_sk_your_key_here"

const rotated = await orbit.messagingConfig.smppCredentials.rotate(
  'smppcred_7f2a9c41be0d4c8ea3b15d6072f4c81b',
);
console.log(rotated.data.password); // new password — update your bind config

The response is the credential wire shape plus password and the same password_visible_once_warning as on create.

Update a credential

PATCH /{id} updates the mutable fields. Pass null for description or dlrWebhookUrl to clear them; set status to suspended to disable the bind or revoked to soft-delete it.

curl -X PATCH https://api.orbit.devotel.io/api/v1/messaging/smpp/credentials/smppcred_7f2a9c41be0d4c8ea3b15d6072f4c81b \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"tpsLimit": 100, "status": "suspended"}'

const updated = await orbit.messagingConfig.smppCredentials.update(
  'smppcred_7f2a9c41be0d4c8ea3b15d6072f4c81b',
  { tpsLimit: 100, status: 'suspended' },
);

{
  "data": {
    "id": "smppcred_7f2a9c41be0d4c8ea3b15d6072f4c81b",
    "systemId": "orb_k4x9",
    "description": "Production bind — primary aggregator",
    "tpsLimit": 100,
    "allowedCidrs": ["203.0.113.0/24"],
    "dlrMode": "both",
    "dlrWebhookUrl": "https://example.com/webhooks/smpp-dlr",
    "status": "suspended",
    "lastRotatedAt": "2026-08-25T10:02:11.904Z",
    "lastSeenAt": "2026-08-25T09:58:40.102Z",
    "bindCount": 3,
    "createdAt": "2026-08-25T09:14:32.418Z",
    "updatedAt": "2026-08-25T10:22:05.771Z",
    "smppHost": "smpp.orbit.devotel.io",
    "smppPort": 3550,
    "passwordRevealableUntil": null
  }
}

Deleting a credential (DELETE /{id}) is a soft delete — status flips to revoked and the endpoint returns 204 No Content.

Carriers

A carrier definition pairs a credential set with routing metadata — supported countries, quality, fallback order, billing rate.

Method	Path	Purpose
`GET`	`/api/v1/messaging/smpp/carriers`	List configured carriers
`POST`	`/api/v1/messaging/smpp/carriers`	Add a carrier
`GET`	`/api/v1/messaging/smpp/carriers/route-scores`	Read-only route-policy scoring breakdown (analytics — see below)
`GET`	`/api/v1/messaging/smpp/carriers/{id}`	Get a carrier
`PATCH`	`/api/v1/messaging/smpp/carriers/{id}`	Update routing metadata
`DELETE`	`/api/v1/messaging/smpp/carriers/{id}`	Remove
`POST`	`/api/v1/messaging/smpp/carriers/{id}/test`	Run a bind/connectivity test against this carrier (no message is sent)

The Node tab of each example below uses the Node.js SDK helpers under orbit.messagingConfig.smppCarriers.

Add a carrier

For a type: "smpp" carrier you supply the upstream SMSC connection details — remoteHost, remotePort, remoteSystemId, and remotePassword are all required. The password never comes back on any response; SMPP 3.4 caps it at 8 usable characters, so a longer value is rejected at validation. A scope of by_country_mcc also requires a non-empty scopeFilter.mccs list of 3-digit MCCs.

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/smpp/carriers \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Primary aggregator",
    "type": "smpp",
    "remoteHost": "smsc.carrier-a.example.com",
    "remotePort": 2775,
    "remoteSystemId": "orbit_mt",
    "remotePassword": "s3cr3tPW",
    "scope": "by_country_mcc",
    "scopeFilter": { "mccs": ["310", "311"] },
    "priority": 100
  }'

const carrier = await orbit.messagingConfig.smppCarriers.create({
  label: 'Primary aggregator',
  type: 'smpp',
  remoteHost: 'smsc.carrier-a.example.com',
  remotePort: 2775,
  remoteSystemId: 'orbit_mt',
  remotePassword: 's3cr3tPW',
  scope: 'by_country_mcc',
  scopeFilter: { mccs: ['310', '311'] },
  priority: 100,
});

201 Created:

{
  "data": {
    "id": "id_smppcr_9f2c41a7be0d4c8ea3b15d6072f4c81b",
    "label": "Primary aggregator",
    "type": "smpp",
    "description": null,
    "remoteHost": "smsc.carrier-a.example.com",
    "remotePort": 2775,
    "remoteSystemId": "orbit_mt",
    "remotePasswordSet": true,
    "bindType": "tx",
    "tlsEnabled": false,
    "tlsVerifyCert": false,
    "httpUrl": null,
    "httpAuthType": null,
    "httpCredentialsSet": false,
    "scope": "by_country_mcc",
    "scopeFilter": { "mccs": ["310", "311"] },
    "priority": 100,
    "status": "active",
    "lastSeenAt": null,
    "bindStatus": null,
    "createdAt": "2026-08-25T09:31:14.002Z",
    "updatedAt": "2026-08-25T09:31:14.002Z"
  }
}

Update a carrier

PATCH /{id} updates routing metadata and connection details. Pass scopeFilter: null to clear a MCC filter. Because PATCH is partial, updating a MCC-scoped carrier’s scope to by_country_mcc requires scopeFilter.mccs in the same request when none is stored yet.

curl -X PATCH https://api.orbit.devotel.io/api/v1/messaging/smpp/carriers/id_smppcr_9f2c41a7be0d4c8ea3b15d6072f4c81b \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"priority": 50, "tlsEnabled": true}'

const updated = await orbit.messagingConfig.smppCarriers.update(
  'id_smppcr_9f2c41a7be0d4c8ea3b15d6072f4c81b',
  { priority: 50, tlsEnabled: true },
);

The response is the full carrier wire shape, as on create. Deleting a carrier (DELETE /{id}) returns 204 No Content.

Test a carrier

POST /api/v1/messaging/smpp/carriers/{id}/test checks whether the carrier can bind to its SMSC. It does not submit an SMS — no test message is delivered and you are not billed for it. Use it to confirm host, port, system ID, and password before routing live traffic. The response reports the last bind state the platform has observed for the carrier:

Field	Type	Description
`ok`	boolean	`true` only when the carrier is currently bound (`bindStatus` is `BOUND`).
`bindStatus`	string	`BOUND`, `UNBOUND`, or `BIND_FAILED`.
`reason`	string \| null	Human-readable detail — the underlying bind status, or why the test could not run (wrong carrier type, missing SMPP fields, undecryptable credential).
`durationMs`	number	Time taken by the bind attempt, in milliseconds.

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/smpp/carriers/id_smppcr_9f2c41a7be0d4c8ea3b15d6072f4c81b/test \
  -H "X-API-Key: dv_live_sk_your_key_here"

const test = await orbit.messagingConfig.smppCarriers.test(
  'id_smppcr_9f2c41a7be0d4c8ea3b15d6072f4c81b',
);

if (test.data.bindStatus !== 'BOUND') {
  console.error('Carrier not bound:', test.data.reason);
}

A healthy carrier:

{
  "ok": true,
  "bindStatus": "BOUND",
  "reason": "BOUND",
  "durationMs": 0
}

A failed bind reports the reason the SMSC rejected it:

{
  "ok": false,
  "bindStatus": "BIND_FAILED",
  "reason": "SMSC rejected the bind (ESME_RINVPASWD) — check remoteSystemId and remotePassword",
  "durationMs": 412
}

Route scores (analytics)

GET /api/v1/messaging/smpp/carriers/route-scores returns the scoring breakdown Orbit uses to decide which of your carriers carries an outbound message. It re-runs the same cost × delivery-quality × bind-health × sticky-incumbent scoring as the live router, so you can see which carrier is winning right now, why, and whether Orbit has failed over away from a degraded bind. The call is read-only — it changes no routing and sends no traffic. The route-policy panel under Developer → SMPP in the dashboard reads this same endpoint. Only carriers with status: "active" and type: "smpp" are scored, matching the set the router chooses from. If Orbit cannot read your recent delivery history, the request still succeeds and every active carrier is scored on cost and bind health alone; those entries come back with delivered and failed at 0 and deliveryRate as null.

Field	Type	Description
`windowHours`	number	Rolling window, in hours, that `delivered` and `failed` were counted over.
`selectedCarrierId`	string \| null	The `scope: "all"` carrier Orbit would currently pick as the default route, or `null` when you have no active `scope: "all"` carrier.
`carriers`	array	One entry per active carrier, highest `composite` score first.
`carriers[].delivered` / `carriers[].failed`	number	Delivery receipts counted for that carrier in the window.
`carriers[].deliveryRate`	number \| null	Observed `delivered / (delivered + failed)` over the window, or `null` when the carrier saw no terminal traffic.
`carriers[].scores`	object	The breakdown behind the ranking: `cost` (from the carrier’s `priority`), `quality` (smoothed delivery rate), `health` (live bind state), the `sticky` incumbent flag, and `composite` — the three factors multiplied together, plus a bonus when `sticky` is `true`.
`carriers[].selected`	boolean	`true` for the carrier `selectedCarrierId` refers to.

Scores are smoothed, so quality will not match deliveryRate exactly on a low-volume carrier — a carrier with no traffic yet starts at a neutral quality rather than at zero.

{
  "windowHours": 24,
  "selectedCarrierId": "id_smppcr_9f2c41a7be0d4c8ea3b15d6072f4c81b",
  "carriers": [
    {
      "carrierId": "id_smppcr_9f2c41a7be0d4c8ea3b15d6072f4c81b",
      "label": "Primary aggregator",
      "scope": "all",
      "scopeFilter": null,
      "priority": 100,
      "bindStatus": "BOUND",
      "lastSeenAt": "2026-08-19T18:22:04.113Z",
      "delivered": 1204,
      "failed": 6,
      "deliveryRate": 0.995,
      "scores": { "cost": 0.5, "quality": 0.993, "health": 1, "sticky": true, "composite": 0.521 },
      "selected": true
    }
  ]
}

Sender pools

Group multiple sender IDs / numbers into a pool that the router rotates across. Pools attach to carriers and are referenced by campaigns.

Method	Path	Purpose
`GET`	`/api/v1/messaging/sender-pools`	List sender pools
`POST`	`/api/v1/messaging/sender-pools`	Create a pool
`GET`	`/api/v1/messaging/sender-pools/{id}`	Get a pool
`PATCH`	`/api/v1/messaging/sender-pools/{id}`	Update pool members
`DELETE`	`/api/v1/messaging/sender-pools/{id}`	Delete
`GET`	`/api/v1/messaging/sender-pools/{id}/preview`	Preview which sender will be picked for a destination

The Node tab of each example below uses the Node.js SDK helpers under orbit.messagingConfig.senderPools. Pool members (sender_dids) mix E.164 long codes, numeric short codes, and alphanumeric sender IDs. strategy is one of sticky (default — same recipient keeps the same sender), round_robin, random, or geomatch (prefer a sender in the recipient’s country, falling back to sticky when none matches).

Create a pool

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/sender-pools \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "US transactional rotation",
    "sender_dids": ["+14155552671", "+16505550199"],
    "strategy": "sticky"
  }'

const pool = await orbit.messagingConfig.senderPools.create({
  label: 'US transactional rotation',
  sender_dids: ['+14155552671', '+16505550199'],
  strategy: 'sticky',
});

201 Created:

{
  "data": {
    "id": "pool_b7c41a9fe2d04c8ea3b15d6072f4c81b",
    "label": "US transactional rotation",
    "sender_dids": ["+14155552671", "+16505550199"],
    "strategy": "sticky",
    "created_at": "2026-08-25T09:40:51.236Z",
    "updated_at": "2026-08-25T09:40:51.236Z"
  }
}

An empty sender_dids, more than 50 members, duplicates, or a member that is not a valid sender returns 422. Updating (PATCH /{id} with label, sender_dids, or strategy) returns the same shape; deleting (DELETE /{id}) returns 204 No Content.

Preview sender selection

GET /{id}/preview?recipient=<E.164> resolves which sender the pool would pick for a destination without persisting anything — no stickiness assignment is written and the round-robin cycle is not advanced, so you can probe freely. Use it to verify a pool’s behaviour before wiring it into a campaign.

curl "https://api.orbit.devotel.io/api/v1/messaging/sender-pools/pool_b7c41a9fe2d04c8ea3b15d6072f4c81b/preview?recipient=%2B12125550123" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const preview = await orbit.messagingConfig.senderPools.preview(
  'pool_b7c41a9fe2d04c8ea3b15d6072f4c81b',
  '+12125550123',
);
console.log(preview.data.assigned_sender_did); // '+14155552671'

{
  "data": {
    "pool_id": "pool_b7c41a9fe2d04c8ea3b15d6072f4c81b",
    "recipient": "+12125550123",
    "assigned_sender_did": "+14155552671",
    "strategy": "sticky"
  }
}

For sticky pools the same recipient always previews to the same sender; for geomatch the preview shows the country-matched sender when the pool holds one for the recipient’s country.

API Reference

All Endpoints

BYO-SMPP Credentials API: send SMS over your own carrier

BYO-SMPP Credentials API

Using the SDKs

Credentials

Issue a credential

Reveal the password

Rotate the password

Update a credential

Carriers

Add a carrier

Update a carrier

Test a carrier

Route scores (analytics)

Sender pools

Create a pool

Preview sender selection

See also

​BYO-SMPP Credentials API

​Using the SDKs

​Credentials

​Issue a credential

​Reveal the password

​Rotate the password

​Update a credential

​Carriers

​Add a carrier

​Update a carrier

​Test a carrier

​Route scores (analytics)

​Sender pools

​Create a pool

​Preview sender selection

​See also

BYO-SMPP Credentials API

Using the SDKs

Credentials

Issue a credential

Reveal the password

Rotate the password

Update a credential

Carriers

Add a carrier

Update a carrier

Test a carrier

Route scores (analytics)

Sender pools

Create a pool

Preview sender selection

See also