> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect via SMPP: bind an SMPP client to Orbit

> Bind an existing SMPP client straight to Orbit's SMPP edge for high-throughput SMS delivery, as a drop-in alternative to the REST API for aggregators.

# Connect via SMPP

Most Orbit customers send SMS through the REST [Messaging API](/api-reference/endpoints/messaging). 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.

## 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.

## 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.

### 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`.

## Creating a credential

```bash theme={null}
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:

```bash theme={null}
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.

## 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           |
| Delivery receipts | Webhook                             | Bind (`deliver_sm`), webhook, or both                             |
| Setup             | API key                             | Bind credential (`system_id` + password) + optional IP allow-list |

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.

## 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](/api-reference/messaging-credentials) for the carrier endpoints if your organization has a direct carrier agreement you want Orbit to route through.

## 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                                |

## See also

* [Messaging API](/api-reference/endpoints/messaging) — the REST alternative to an SMPP bind
* [Messaging credentials & services](/api-reference/messaging-credentials)
* [Sender Pools](/guides/sender-pools) — rotating the `from` address across a pool of senders