# SMS Trunks

Note

To configure SMS trunks in the User Panel, see [SMS Trunks](../../../../sms/sms-trunks/index.html#userpanel-sms).
For the message formats and protocols used by the trunks, see the
[SMS HTTP specification](../../../../sms/sms-trunks/technical-data/http-specification.html#user-panel-sms-http-specification) and the
[SMPP specification](../../../../sms/sms-trunks/technical-data/smpp-specification.html#service-smpp-specification).

Use the SMS Trunks resource to create, retrieve, update, and delete SMS trunks, and to
regenerate the credentials DIDWW generates for some trunk types.

An SMS trunk defines how DIDWW delivers the inbound SMS sent to your DIDs, how your
application submits outbound SMS to DIDWW, or both. The `configuration` attribute selects
the trunk type, and the type decides which configuration attributes the trunk takes and
which directions it handles:

| Configuration type | Direction | Description |
| --- | --- | --- |
| `sms_to_email` | Inbound | DIDWW forwards inbound SMS as email. |
| `http_in` | Inbound | DIDWW delivers inbound SMS as an HTTP request to your endpoint. |
| `http_out` | Outbound | Your application submits outbound SMS to DIDWW over HTTP. |
| `smpp_esme` | Inbound and outbound | Your application connects to DIDWW as an SMPP ESME. |
| `smpp_smsc` | Inbound and outbound | DIDWW connects to your SMSC as an SMPP client. |

SMS trunks are available starting from version `2026-11-19`.

## Requirements and behavior

When creating or updating an SMS trunk:

- Provide a `name` and a `configuration` object when creating the trunk. The name must
  be unique among the SMS trunks and SMS trunk groups of the account.
- The configuration type cannot be changed after the trunk is created. On update, the
  `configuration.type` must match the trunk's type; the configuration attributes you send
  are written and the others keep their stored values.
- Each configuration type requires its own set of attributes on creation. See
  [Create SMS Trunk](create-sms-trunk.html).
- `priority` and the `sms_trunk_group` relationship apply only to the trunk types that
  can join an [SMS Trunk Group](../sms-trunk-groups/index.html): `sms_to_email`,
  `http_in`, `smpp_esme`, and `smpp_smsc`. On these types `priority` defaults to
  `100`. On `http_out` trunks `priority` must stay `null` and a group cannot be
  assigned.
- `allow_any_did_as_source` can be enabled only on the trunk types that send messages:
  `http_out`, `smpp_esme`, and `smpp_smsc`. Enabling it removes all
  `outgoing_dids`, which must stay empty while it is `true`.
- `outgoing_dids` accepts only DIDs of your account that support the `p2p` feature, and
  rejects DIDs awaiting registration.
- `incoming_dids` is read-only. To route inbound SMS of a DID to a trunk, update the
  `sms_trunk` relationship of the [DID](../did/index.html). To route it to a group, use
  the DID `sms_trunk_group` relationship instead.
- `smpp_esme` and `http_out` trunks receive credentials generated by DIDWW. They are
  returned as read-only configuration attributes and can be replaced with
  [Regenerate SMS Trunk Credentials](sms-trunk-regenerate-credentials.html).
- The number of SMS trunks and SMS trunk groups an account can create is limited. When the
  limit is reached, a create request returns `400 Bad Request` with the title
  `Quota limit reached`. Contact DIDWW Support to request a higher limit.
- A trunk cannot be deleted while any DID is routed to it for inbound SMS. Sender ID
  verifications that use a deleted trunk are left without one, and their outbound messages
  stop until another trunk is assigned.
- `sender_id_verifications` is read-only. To route a verification through a trunk, update
  the `sms_trunk` relationship of the
  [Sender ID Verification](../sender-id-verifications/index.html).

## Endpoints

| Action | Method | Endpoint |
| --- | --- | --- |
| Retrieve all SMS Trunks | `GET` | `/v3/sms_trunks` |
| Retrieve SMS Trunk | `GET` | `/v3/sms_trunks/{id}` |
| Create SMS Trunk | `POST` | `/v3/sms_trunks` |
| Update SMS Trunk | `PATCH` | `/v3/sms_trunks/{id}` |
| Delete SMS Trunk | `DELETE` | `/v3/sms_trunks/{id}` |
| Regenerate SMS Trunk credentials | `POST` | `/v3/sms_trunk_regenerate_credentials` |

## Retrieve all SMS Trunks

Retrieves all SMS trunks configured for the account.

Use this endpoint to filter trunks by name, external reference ID, ID, or configuration
type. Outgoing DIDs, incoming DIDs, the SMS trunk group, and Sender ID verifications can be
included in the response.

See [Retrieve All SMS Trunks](get-sms-trunks.html).

```
GET /v3/sms_trunks
```

## Retrieve SMS Trunk

Retrieves a specific SMS trunk by its unique ID.

Use this endpoint to inspect the trunk configuration, including the generated credentials
of `smpp_esme` and `http_out` trunks, and the URL of the endpoint to which `http_out`
trunks submit outbound SMS (`meta.host`).

See [Retrieve SMS Trunk](get-sms-trunk.html).

```
GET /v3/sms_trunks/{id}
```

## Create SMS Trunk

Creates an SMS trunk of one of the five configuration types.

Provide a unique name and the configuration, and optionally set the external reference ID,
status, priority, source-address settings, outgoing DIDs, and the SMS trunk group.

See [Create SMS Trunk](create-sms-trunk.html).

```
POST /v3/sms_trunks
```

## Update SMS Trunk

Updates a specific SMS trunk.

Use this endpoint to change the trunk name, external reference ID, status, priority,
source-address settings, configuration attributes, outgoing DIDs, or SMS trunk group. The
configuration type cannot be changed.

See [Update SMS Trunk](update-sms-trunk.html).

```
PATCH /v3/sms_trunks/{id}
```

## Delete SMS Trunk

Permanently deletes a specific SMS trunk. The request is rejected while any DID is routed
to the trunk for inbound SMS; route those DIDs elsewhere first. Sender ID verifications that
use the trunk are left without one, and their outbound messages stop until another trunk is
assigned.

See [Delete SMS Trunk](delete-sms-trunk.html).

```
DELETE /v3/sms_trunks/{id}
```

## Regenerate SMS Trunk credentials

Replaces the generated credentials of an `smpp_esme` trunk (`system_id` and
`password`) or an `http_out` trunk (`auth_name` and `auth_password`). The response
contains only the trunk ID; retrieve the trunk to read the new credentials.

See [Regenerate SMS Trunk Credentials](sms-trunk-regenerate-credentials.html).

```
POST /v3/sms_trunk_regenerate_credentials
```

## Data reference

See [SMS Trunk Object](sms-trunk-object.html) for the complete trunk attributes, the
configuration attributes of each trunk type, relationships, and metadata.

## Common SMS Trunk use cases

| Use case | Description |
| --- | --- |
| Receive inbound SMS by email | Create an `sms_to_email` trunk and route DIDs to it. |
| Receive inbound SMS on a web endpoint | Create an `http_in` trunk with the URL, method, and request template DIDWW uses to deliver each message. |
| Send outbound SMS over HTTP | Create an `http_out` trunk, read its generated credentials and the endpoint URL in `meta.host`, and submit messages as described in the [SMS OUT HTTP specification](../../../../sms/outbound-sms-api/index.html#sms-out-specification). |
| Exchange SMS over SMPP | Create an `smpp_esme` trunk to bind to DIDWW, or an `smpp_smsc` trunk to let DIDWW bind to your SMSC. |
| Control source addresses | Assign `outgoing_dids` or enable `allow_any_did_as_source` on a trunk that sends messages. |
| Configure failover for inbound SMS | Add trunks to an [SMS Trunk Group](../sms-trunk-groups/index.html) and set their `priority`. |
| Rotate credentials | Regenerate the credentials of an `smpp_esme` or `http_out` trunk. |
| Pause a trunk | Set `blocked` to `true` to stop the trunk from handling messages. |

## Related resources

Use SMS Trunks together with DIDs and SMS Trunk Groups to configure SMS services.

| Resource | Description |
| --- | --- |
| [DIDs](../did/index.html) | DID phone numbers routed to an SMS trunk or SMS trunk group for inbound SMS, and used as source addresses for outbound SMS. |
| [SMS Trunk Groups](../sms-trunk-groups/index.html) | Groups of inbound-capable SMS trunks used as one routing destination. |
| [Sender ID Verifications](../sender-id-verifications/index.html) | Verifications of sender identities whose outbound messages are routed through a trunk. |
| [Exports](../../export/index.html) | Exports of inbound and outbound SMS records. |
