Connect via SMPP

Most Orbit customers send SMS through the REST Messaging API. If you already run SMPP-based sending infrastructure — a legacy platform migration, an aggregator integration, or a high-throughput application built around an SMPP client library — Orbit also exposes a direct SMPP bind, so you don’t have to rewrite that integration to switch providers.

Wire protocol: PDUs, not JSON

Your client speaks SMPP 3.4 binary PDUs to Orbit’s edge — there is no HTTP JSON layer on the bind. The frames you exchange:

PDU	Direction	Purpose
`bind_transmitter` / `bind_receiver` / `bind_transceiver`	client → edge	Open the session. A transceiver bind carries traffic in both directions and is what almost every integration wants.
`submit_sm`	client → edge	Send one message. `submit_sm_resp` carries the Orbit message id you reconcile against delivery receipts.
`deliver_sm`	edge → client	Delivery receipt inbound — only when the credential’s `dlrMode` is `bind` or `both`.
`enquire_link`	both ways	Keepalive. Send one every 30–60 seconds; a session silent longer than the edge’s idle timeout is torn down.
`unbind` / `unbind_resp`	client → edge	Clean session close.

A minimal submit_sm for one recipient — the envelope the runnable client examples below put on the wire when they send a single message:

source_addr_ton=0 source_addr_npi=0 source_addr="OrbitBrand"
dest_addr_ton=1  dest_addr_npi=1  destination_addr="447700900123"
esm_class=0 protocol_id=0 data_coding=0 short_message="hello world"

Batch the way SMPP batches: pipeline many submit_sm PDUs in flight over one bind rather than asking for a batch endpoint — there is none on the wire. Respect the remote window your client negotiates and the credential’s TPS cap; data_coding=8 on submit_sm is how you send UCS-2 (Unicode) text, and esm_class=0x40 (UDHI) marks concatenated segments when a message is longer than one segment.

How it works

Orbit issues you a system_id and password. Your SMPP client binds to smpp.orbit.devotel.io:2775 with those credentials and submits submit_sm PDUs exactly as it would against any other SMPP provider. Traffic sent this way flows through the same Orbit sending infrastructure as a REST-submitted message — the same routing, delivery tracking, and compliance gates apply either way.

A runnable client: bind, send one message, read the receipt

Orbit issues the system_id and password below when you create a credential — use the create curl later in this section. Set the four environment variables, then run either example end to end: it opens a transceiver bind, sends one submit_sm, prints the Orbit message id from submit_sm_resp, and (if the credential’s dlrMode is bind or both) reads the deliver_sm receipt before unbind.

export SMPP_SYSTEM_ID="smpp_sys_abcd12"
export SMPP_PASSWORD='Ab3Xy9Zq'
export SMPP_FROM="OrbitBrand"
export SMPP_TO="447700900123"

Python with smpplib

pip install smpplib
python send_once.py

# send_once.py — bind to Orbit, send one message, print the receipt, unbind.
import logging, os

import smpplib.client

# pip install smpplib
logging.basicConfig(level=logging.DEBUG)
client = smpplib.client.Client("smpp.orbit.devotel.io", 2775, timeout=15)

# Log every PDU the edge sends back: bind resp, submit_sm_resp, deliver_sm.
client.set_message_sent_handler(lambda pdu: print(f"message_id={pdu.message_id}"))
client.set_message_received_handler(
    lambda pdu: print(f"receipt: status={pdu.receipted_message_state}, text={pdu.short_message}")
)

client.connect()
client.bind_transceiver(
    system_id=os.environ["SMPP_SYSTEM_ID"],
    password=os.environ["SMPP_PASSWORD"],
)
client.send_message(
    source_addr_ton=smpplib.consts.SMPP_TON_ALNUM,  # sender is an alphanumeric brand
    source_addr_npi=smpplib.consts.SMPP_NPI_UNK,
    source_addr=os.environ["SMPP_FROM"],
    dest_addr_ton=smpplib.consts.SMPP_TON_INTL,
    dest_addr_npi=smpplib.consts.SMPP_NPI_E164,
    destination_addr=os.environ.get("SMPP_TO", "447700900123"),
    short_message=b"hello world",
)
# In a real service you stop here: smpplib's client thread continues to
# receive deliver_sm receipts for the life of the bind. For this demo,
# sleep a moment, then unbind.
import time

time.sleep(3)
client.unbind()
client.disconnect()

The logging.DEBUG output is the expected PDU trace — on a healthy run, bind_transceiver_resp (command_status=0), then submit_sm followed immediately by submit_sm_resp:

DEBUG: Received bind_transceiver_resp command
DEBUG: Received submit_sm_resp command, message_id='msg_01H4XK6D7Y'
INFO: receipt: status=DELIVRD, text='id:msg_01H4XK6D7Y stat:DELIVRD ...'

Node.js with the smpp package

npm install smpp
node send-once.js

// send-once.js — bind to Orbit, send one message, print the receipt, unbind.
import smpp from 'smpp';

const session = new smpp.Session({
  url: 'smpp://smpp.orbit.devotel.io:2775',
  system_id: process.env.SMPP_SYSTEM_ID,
  password: process.env.SMPP_PASSWORD,
});

session.submit_sm({
  source_addr_ton: 5, // 5 = alphanumeric sender
  source_addr_npi: 0,
  source_addr: process.env.SMPP_FROM || 'OrbitBrand',
  dest_addr_ton: 1,
  dest_addr_npi: 1,
  destination_addr: process.env.SMPP_TO || '447700900123',
  short_message: 'hello world',
}, (pdu) => {
  if (pdu.command_status === 0) {
    console.log(`submit accepted, message_id=${pdu.message_id}`);
  } else {
    console.error(`submit rejected, command_status=${pdu.command_status}`);
  }
  session.close();
});

session.on('pdu', (pdu) => {
  if (pdu.command === 'deliver_sm') {
    console.log(`receipt: stat=${pdu.short_message?.message.toString()}`);
  }
});

The pdu event observes every inbound frame — the expected PDU trace on a healthy run is bind_transceiver_resp command_status=0 first, then submit_sm → submit_sm_resp, then (when dlrMode is bind or both) a deliver_sm receipt such as id:msg_01H4XK6D7Y stat:DELIVRD. Keep one long-lived bind per process and add an enquire_link keepalive every 30–60 seconds before productionizing either snippet — the discipline below and the linked receipts guide both apply. To send through the snippet, point SMPP_SYSTEM_ID and SMPP_PASSWORD at a credential from the create curl; if the password has aged out of its reveal window, rotate it and use the fresh one.

Ports and connectivity

Orbit’s SMPP edge accepts binds on two ports, and only these two:

Port	Transport	Notes
`2775`	Plain TCP	The default. Same port every SMPP provider uses.
`3550`	TLS (SMPPS)	The SMPP session runs inside a TLS tunnel. The server presents a publicly-trusted certificate for `smpp.orbit.devotel.io`; verify it against that hostname.

Both ports speak the same protocol and take the same credentials, so switching between them is a client-side setting, not a new credential. Every other port on smpp.orbit.devotel.io is closed to the internet. Two things follow from that, and they matter when you are debugging a bind:

A blocked port drops your connection instead of refusing it. You will not get a fast connection refused. The connection attempt sits open until your own client gives up, so a typo in the port looks exactly like a slow network. Configure an explicit connect timeout — 5 to 10 seconds is plenty — so a wrong port fails in seconds instead of hanging.
Your own network has to allow the outbound side. Permit egress from the machine running your SMPP client to smpp.orbit.devotel.io on 2775 and 3550. Corporate firewalls that silently discard traffic to non-web ports produce the identical hang.

The dashboard console

Developer → SMPP is the console for everything on this page. It is organized in three tabs:

Credentials — the default tab. Before it lists your bind credentials it shows a Connection details card with the copyable host (smpp.orbit.devotel.io) and both ports, so you can hand the endpoint to a client config without leaving the dashboard. Create, update, reveal, and rotate credentials from the same tab.
Carriers — where enterprise tenants register their own upstream carrier connections, and where you fire a bind test against a carrier row (see the testing section below).
Compliance — a read-only view of how Orbit’s compliance gates (opt-out suppression, quiet hours, consent tracking) apply to the traffic on your SMPP binds. Every submit_sm passes these gates regardless of the wire path it took.

Reachability and bind testing

The console’s Carriers tab has a Test bind action per carrier row. It exists for upstream carriers, not for verifying your own client; for carrier rows it runs the edge-side checks that fail fast — wrong carrier type, missing SMPP fields, an undecryptable stored password — and returns a structured result:

{ "ok": false, "bindStatus": "BIND_FAILED", "reason": "...", "durationMs": 0 }

POST /api/v1/messaging/smpp/carriers/{id}/test exposes the same check over the API, rate-limited so a stuck endpoint can’t be hammered. For your own bind credential, use the diagnostic ladder below — the reachability question (bind_transceiver_resp vs. no response at all) is answered from your own client, not the dashboard.

Is it the network or the credential?

Run bind_transceiver and read what comes back:

You get a bind_transceiver_resp — including one carrying an error status such as ESME_RINVPASWD (wrong password) or ESME_RINVSYSID (unknown system_id) — then the edge is reachable and the problem is the credential. Check it hasn’t been rotated or revoked in the dashboard under Developer → SMPP.
The TCP connection never completes — nothing reached Orbit. Confirm you are dialling 2775 or 3550, that smpp.orbit.devotel.io resolves for you, and that your egress firewall allows the port.
The connection opens on 3550 but the TLS handshake fails — your client is either verifying against a different hostname or is missing the public CA chain in its trust store. Verify against smpp.orbit.devotel.io.

Long-lived bind vs. transient sessions

Run one long-lived bind per sending process and keep it open. Enquire every 30–60 seconds, rebind after any connection drop with exponential backoff, and drain in-flight submit_sm before you unbind on shutdown. Opening a fresh bind per batch or per message is the one usage pattern SMPP punishes and HTTP doesn’t — each bind costs a full handshake, and the edge treats a rapid rebind loop the same way every SMPP server does: throttled and flagged. If your architecture genuinely re-connects per batch, switch that path to the REST API instead.

Troubleshooting bind rejects and throughput

Work this list top to bottom — the first row that matches is the fix.

Symptom	Meaning	Fix
`ESME_RINVPASWD` (`0x0E`) on bind	Wrong password	Re-copy it exactly — 8 characters, one reveal window. If the window has passed, rotate the credential and use the new password.
`ESME_RINVSYSID` (`0x0F`) on bind	Unknown `system_id`	Use the exact id returned at creation, not your description.
`ESME_RINVBNDFMT` (`0x15`) on bind	Source IP not permitted	Your egress IP is outside the credential’s `allowedCidrs` allow-list. Add the CIDR on the dashboard or via `PATCH`, or clear the list.
Bind thrashed — reconnects within seconds	Keepalive or version issue	Send `enquire_link` every 30–60s and set a 10s response timeout; confirm the client negotiates SMPP 3.4.
`ESME_RTHROTTLED` (`0x58`) on `submit_sm`	Over throughput	You exceeded the credential’s TPS cap. Back off with jittered retry, or raise `tpsLimit`; spread load across more than one bind if the ceiling still binds.
`ESME_RMSGQFUL` (`0x14`)	Edge queue full	Slow your enqueue rate; check whether inbound `deliver_sm` receipts are flooding the session and drain them first.
`ESME_RINVDSTADR` (`0x0B`) on `submit_sm`	Bad destination	Normalize to E.164 digits; only set `dest_addr_ton=1` if your client requires it.
`ESME_RINVMSGLEN` (`0x04`)	Message too long	Split into concatenated segments with the UDH marker, or shorten the payload.

A binding reject comes back in the bind_*_resp as a non-zero command_status; read the status from that PDU before assuming the network ate it.

When to use SMPP vs. the REST API

	REST API	SMPP
Best for	New integrations, most applications	Existing SMPP client code, high-throughput bulk senders
Wire protocol	HTTPS + JSON body	Binary PDUs, pipelined in flight
Delivery receipts	Webhook	Bind (`deliver_sm`), webhook, or both
Setup	API key	Bind credential (`system_id` + password) + optional IP allow-list
Throughput model	Per request	Sustainable high rate over one long-lived bind

Both paths send through the same underlying platform — pick whichever fits the integration you already have, or the one your team is more comfortable operating. Delivered status goes wherever you point it: dlrMode = "webhook" posts receipt JSON to your endpoint, dlrMode = "bind" streams deliver_sm frames back on the session, dlrMode = "both" does the two. Everything you would get over the REST path is available no matter which sending wire you chose.

Creating a credential

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": "Legacy platform migration",
    "tpsLimit": 50,
    "allowedCidrs": ["203.0.113.0/24"],
    "dlrMode": "webhook",
    "dlrWebhookUrl": "https://example.com/webhooks/smpp-dlr"
  }'

Field	Notes
`description`	Your label for the credential, shown in the dashboard.
`tpsLimit`	Submissions per second this bind may sustain. Defaults to 50; raise it (up to a platform ceiling) if your integration needs more throughput.
`allowedCidrs`	Optional IP allow-list (CIDR notation, up to 16 entries) restricting which source IPs may bind with this credential.
`dlrMode`	Where delivery receipts go: `bind` (returned as `deliver_sm` PDUs over the same SMPP session — the default), `webhook` (posted as JSON to `dlrWebhookUrl`), or `both`.
`dlrWebhookUrl`	Required when `dlrMode` is `webhook` or `both`. Must be `https://`.

The response includes the generated system_id and a one-time password. The password is exactly 8 alphanumeric characters — that is the maximum the SMPP 3.4 bind PDU password field can carry (a 9-octet value including its trailing NUL), so paste it into your client configuration verbatim; your client does not need to truncate it. The password is only ever shown in full at creation or rotation — it can be re-fetched once within a 60-second reveal window (GET /smpp/credentials/{id}/reveal) in case your session closed before you copied it, and after that window it’s gone. If you lose it, rotate the credential to issue a new one:

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

Rotating invalidates the old password immediately, so schedule it for a maintenance window if the bind is live in production.

Throughput limits

Every credential has a TPS (transactions-per-second) cap — 50 by default, adjustable per organization up to a platform ceiling. A single SMPP bind on Orbit’s infrastructure sustainably tops out well below that ceiling, so if you need very high throughput, open several binds (several credentials) rather than pushing one bind past its practical limit.

Bring-your-own upstream carriers (advanced)

Enterprise tenants with their own direct carrier relationships can additionally register upstream SMPP (or HTTP-API) carrier connections that Orbit’s routing layer uses when picking the best egress path for that tenant’s traffic — alongside Orbit’s own carrier network, not instead of it. This is a separate, more advanced surface from the bind credentials above; see the SMPP API reference for the carrier endpoints if your organization has a direct carrier agreement you want Orbit to route through. Test a saved carrier from the console’s Carriers → Test bind action before enabling it for routing.

Rebinding across regions

Multi-region failover is client-side. A healthy implementation caches a connect latency per region endpoint, rebinds to the lowest-latency healthy region after a drop, and never rotates through endpoints per message — only on failure. Keep the same discipline for regions as for binds: rebind on drop with backoff, drain in-flight work before unbind, and let a sticky session do the work of a fleet of ephemeral ones.

Endpoints

Method	Path	Purpose
`GET`	`/api/v1/messaging/smpp/credentials`	List credentials
`POST`	`/api/v1/messaging/smpp/credentials`	Create a credential
`GET`	`/api/v1/messaging/smpp/credentials/{id}`	Get a credential
`PATCH`	`/api/v1/messaging/smpp/credentials/{id}`	Update a credential
`DELETE`	`/api/v1/messaging/smpp/credentials/{id}`	Revoke a credential
`GET`	`/api/v1/messaging/smpp/credentials/{id}/reveal`	Re-fetch the password inside the 60s reveal window
`POST`	`/api/v1/messaging/smpp/credentials/{id}/rotate`	Rotate the password
`POST`	`/api/v1/messaging/smpp/carriers/{id}/test`	Run the edge-side bind test on an upstream carrier row

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

Connect via SMPP: bind an SMPP client to Orbit

Connect via SMPP

Wire protocol: PDUs, not JSON

How it works

A runnable client: bind, send one message, read the receipt

Python with smpplib

Node.js with the smpp package

Ports and connectivity

The dashboard console

Reachability and bind testing

Is it the network or the credential?

Long-lived bind vs. transient sessions

Troubleshooting bind rejects and throughput

When to use SMPP vs. the REST API

Creating a credential

Throughput limits

Bring-your-own upstream carriers (advanced)

Rebinding across regions

Endpoints

See also

​Connect via SMPP

​Wire protocol: PDUs, not JSON

​How it works

​A runnable client: bind, send one message, read the receipt

​Python with smpplib

​Node.js with the smpp package

​Ports and connectivity

​The dashboard console

​Reachability and bind testing

​Is it the network or the credential?

​Long-lived bind vs. transient sessions

​Troubleshooting bind rejects and throughput

​When to use SMPP vs. the REST API

​Creating a credential

​Throughput limits

​Bring-your-own upstream carriers (advanced)

​Rebinding across regions

​Endpoints

​See also

Connect via SMPP

Wire protocol: PDUs, not JSON

How it works

A runnable client: bind, send one message, read the receipt

Python with smpplib

Node.js with the smpp package

Ports and connectivity

The dashboard console

Reachability and bind testing

Is it the network or the credential?

Long-lived bind vs. transient sessions

Troubleshooting bind rejects and throughput

When to use SMPP vs. the REST API

Creating a credential

Throughput limits

Bring-your-own upstream carriers (advanced)

Rebinding across regions

Endpoints

See also