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

# BYO-SMPP Credentials API

> Bring-your-own SMPP — connect your own carrier credentials so Orbit dispatches SMS through your trunk while still handling routing, delivery receipts, and billing.

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

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

## 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/{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) |

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

```json theme={null}
{
  "ok": true,
  "bindStatus": "BOUND",
  "reason": "BOUND",
  "durationMs": 0
}
```

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

## See also

* [Messaging API → Send SMS](/api-reference/endpoints/messaging) — once credentials are configured, sends auto-route