> For the complete documentation index, see [llms.txt](https://docs.cuoral.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuoral.com/api-reference/engagement/sms/smpp-integration.md).

# SMPP Integration

This is Cuoral SMPP integration guide

Cuoral provides an SMPP 3.4 gateway that allows your platform to send SMS through Cuoral.

Your platform connects to Cuoral using SMPP. Cuoral validates your credentials, source IP, sender ID, route, and available balance before processing messages.

### Connection details

```
Host: smpp.cuoral.com
Port: 2776
TLS: Required
SMPP version: 3.4
Bind mode: Transceiver
```

Each organization receives its own:

* System ID
* Password
* Allowed source IP addresses
* Throughput limit
* Default SMS route

### Dashboard setup

An organization administrator should:

1. Open **Messaging → SMS → Sender IDs**.
2. Select the **SMPP access** tab.
3. Add the customer platform’s public outbound IP address.
4. Select the default SMS route.
5. Enable SMPP access.
6. Click **Save changes**.
7. Copy the generated password immediately.

The password is shown only once. Use **Rotate password** if it is lost or compromised.

Do not use `127.0.0.1` unless the SMPP client is running on the same server as the gateway.

Example allowlisted address:

```
203.0.113.42/32
```

You may add one IP address or CIDR range per line.

### Customer platform configuration

Configure your SMPP client with:

```
Host: smpp.cuoral.com
Port: 2776
TLS: enabled
SMPP version: 3.4
Bind mode: transceiver
System ID: generated system ID
Password: generated password
```

Use an approved Cuoral sender ID when submitting messages.

### Connection flow

The customer platform should:

1. Establish a TLS connection to `smpp.cuoral.com:2776`.
2. Send a `bind_transceiver` request.
3. Wait for a successful bind response.
4. Submit SMS messages using `submit_sm`.
5. Request delivery receipts with `registered_delivery`.
6. Keep the connection open to receive `deliver_sm`.
7. Acknowledge each delivery receipt.

### Sending SMS

A standard `submit_sm` request should include:

```
source_addr: approved sender ID
destination_addr: recipient number
short_message: message content
data_coding: GSM-7 or UCS-2
registered_delivery: requested when delivery receipts are needed
```

Phone numbers must use international format without spaces.

Example:

```
Sender: cuoral
Recipient: 2348100000000
Message: hi, this is cuoral
```

### Per-message route selection

Customers can select the SMS route for each message using the standard SMPP `service_type` field.

Use:

```
service_type = generic
```

for the Generic route, or:

```
service_type = dnd
```

for the DND route.

If `service_type` is empty or unsupported, Cuoral uses the organization’s default route configured in the dashboard.

Example:

```
service_type: dnd
source_addr: cuoral
destination_addr: 2348100000000
short_message: Your message
```

### Sender IDs

The sender ID used in `submit_sm` must be approved for the organization in Cuoral.

Examples:

```
cuoral
ACME
MYBRAND
```

Messages using unapproved sender IDs are rejected.

### Delivery receipts

Request delivery receipts by setting `registered_delivery`.

Cuoral sends receipts through `deliver_sm`.

| Status    | Meaning                         |
| --------- | ------------------------------- |
| `ACCEPTD` | Message accepted for processing |
| `DELIVRD` | Message delivered               |
| `UNDELIV` | Message could not be delivered  |
| `REJECTD` | Message rejected                |
| `EXPIRED` | Delivery window expired         |

Example delivery receipt:

```
id:8d1f2c3a4b5c6d7e8f901234567890ab
sub:001
dlvrd:001
submit date:2611131200
done date:2611131201
stat:DELIVRD
err:000
text:
```

Keep the connection open and acknowledge each `deliver_sm` response.

### Throughput

Each SMPP account has a configurable throughput limit.

If the configured rate is exceeded, additional submissions may be rejected temporarily.

Customers should:

* Implement retry handling with backoff.
* Avoid uncontrolled message bursts.
* Respect the configured throughput limit.

### Balance and message segments

Cuoral validates available account balance before accepting a message.

Long messages may be split into multiple segments. Each segment may count separately.

Customers should confirm that their SMPP platform correctly handles:

* GSM-7 encoding
* UCS-2 encoding
* Message segmentation
* Delivery receipts for segmented messages

### Supported features

* SMPP 3.4
* TLS connections
* `bind_transceiver`
* `bind_transmitter`
* `bind_receiver`
* `submit_sm`
* GSM-7 messages
* UCS-2 messages
* Delivery receipts
* Receipt acknowledgement
* Source IP allowlisting
* Sender ID validation
* Per-message route selection
* Organization-specific configuration
* Balance validation

### Current limitations

The gateway currently rejects:

* Multipart SAR messages
* Multipart UDH messages
* Scheduled delivery
* Unsupported data codings
* Invalid or missing sender IDs
* Messages submitted before binding
* Connections from non-allowlisted IP addresses

For long messages, confirm that your SMPP client handles segmentation correctly.

### Security requirements

Customers must:

* Keep the System ID and password private.
* Use TLS.
* Provide only trusted public source IPs.
* Rotate credentials if exposed.
* Keep delivery-receipt connections open.
* Acknowledge delivery receipts.
* Avoid committing credentials to source control.
* Avoid sharing credentials in support requests or chat.

### Troubleshooting

#### Bind rejected

Check that:

* The System ID is correct.
* The password is current.
* The source IP is allowlisted.
* SMPP access is enabled.
* TLS is enabled.
* Port `2776` is reachable.
* The client is using SMPP version 3.4.

#### Sender rejected

Confirm that the sender ID is approved in the Cuoral dashboard and matches the value used in `source_addr`.

#### Route rejected

Use one of the supported values:

```
generic
dnd
```

If no route is provided, the organization’s dashboard default is used.

#### Insufficient balance

Ensure the organization has sufficient balance for the message and all of its segments.

#### No delivery receipt

Check that:

* `registered_delivery` was requested.
* The SMPP connection remains open.
* The customer platform supports receiver or transceiver mode.
* The customer platform acknowledges `deliver_sm`.
* The client is not disconnecting immediately after `submit_sm`.

#### Connection timeout

Run:

```
openssl s_client \
  -connect smpp.cuoral.com:2776 \
  -servername smpp.cuoral.com
```

The certificate should be valid for:

```
smpp.cuoral.com
```

#### Source IP rejected

Confirm that the IP configured in the Cuoral dashboard is the customer platform’s public outbound IP, not a private address such as:

```
10.0.0.10
192.168.1.20
127.0.0.1
```

### Contacting support

When contacting Cuoral support, provide:

* Organization name
* System ID
* Timestamp of the failed request
* SMPP command involved
* SMPP response status
* Customer platform name
* Public source IP
* Relevant message ID, if available

Never send the SMPP password in a support request.
