# SMPP Server

## Mobile Text Alerts SMPP Server

Connect to Mobile Text Alerts via SMPP for SMS messaging from systems that use the SMPP protocol.

{% hint style="info" %}
**Limited Access** The Mobile Text Alerts SMPP server is available as an opt-in system offering. Access is currently limited to approved accounts. To request access or obtain your SMPP credentials, contact your account manager or reach out to support.
{% endhint %}

### What is SMPP?

SMPP (Short Message Peer-to-Peer) is a telecommunications protocol used for exchanging SMS messages between messaging entities. It is commonly used by enterprise platforms, telecom providers, and legacy systems that send and receive SMS at scale over persistent TCP connections rather than HTTP-based REST APIs.

If your system already communicates over SMPP — or you need a persistent, low-latency connection for high-throughput messaging — the Mobile Text Alerts SMPP server allows you to send messages, receive replies, and track delivery statuses using the same SMPP interface your platform already supports.

If you are building a new integration and do not have an existing SMPP requirement, the Mobile Text Alerts [REST API](https://developers.mobile-text-alerts.com/developer-center-introduction) is recommended as the primary integration method.

### Connection Details

| Parameter      | Value                                      |
| -------------- | ------------------------------------------ |
| Host           | `smpp.mobile-text-alerts.com`              |
| Port           | `2776` (TLS)                               |
| Protocol       | SMPP v5.0 (backwards compatible with v3.4) |
| Transport      | TLS required (SMPP over TLS)               |
| Authentication | `system_id` + `password` via SMPP bind PDU |

{% hint style="warning" %}
**TLS is required.** Plain-text TCP connections are not accepted. Your SMPP client must support TLS to connect to the Mobile Text Alerts SMPP server.
{% endhint %}

### Authentication

The Mobile Text Alerts SMPP server uses standard SMPP bind authentication. When establishing a session, your client sends a bind PDU containing a `system_id` and `password`. These credentials are provisioned by Mobile Text Alerts and are specific to your account.

#### Obtaining Credentials

SMPP credentials are provisioned by your account manager. To request access:

1. Contact your account manager or reach out to support.
2. Your team will receive a `system_id` and `password` for use in SMPP bind requests.
3. Store these credentials securely. They function as your authentication to the SMPP server, similar to an API key for the REST API.

#### Bind Modes

The server supports all three standard SMPP bind modes:

| Bind Mode   | PDU                | Use Case                                                                                        |
| ----------- | ------------------ | ----------------------------------------------------------------------------------------------- |
| Transceiver | `bind_transceiver` | Send and receive messages on the same session. **Recommended for most integrations.**           |
| Transmitter | `bind_transmitter` | Send messages only. No inbound messages or delivery receipts will be delivered on this session. |
| Receiver    | `bind_receiver`    | Receive inbound messages and delivery receipts only. Cannot be used to send messages.           |

For most integrations, `bind_transceiver` is the simplest option — it allows you to send messages and receive both replies and delivery receipts on a single connection.

### Supported Operations

The following SMPP PDUs are supported by the Mobile Text Alerts SMPP server:

#### Sending Messages

| PDU              | Direction       | Description                                                                        |
| ---------------- | --------------- | ---------------------------------------------------------------------------------- |
| `submit_sm`      | Client → Server | Submit a message for delivery to a mobile subscriber.                              |
| `submit_sm_resp` | Server → Client | Response to `submit_sm`, contains the `message_id` assigned by Mobile Text Alerts. |

#### Receiving Messages and Delivery Receipts

| PDU               | Direction       | Description                                                                                                                        |
| ----------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `deliver_sm`      | Server → Client | Delivers inbound messages (MO) and delivery receipts (DLRs) to your client.                                                        |
| `deliver_sm_resp` | Client → Server | Your client's acknowledgment of a received `deliver_sm`. Must return `command_status` `0x00000000` (ESME\_ROK) to confirm receipt. |

#### Message Management

| PDU         | Direction       | Description                                                                |
| ----------- | --------------- | -------------------------------------------------------------------------- |
| `query_sm`  | Client → Server | Query the status of a previously submitted message using its `message_id`. |
| `cancel_sm` | Client → Server | Cancel a previously submitted message that has not yet been delivered.     |

#### Session Management

| PDU                 | Direction        | Description                                                                     |
| ------------------- | ---------------- | ------------------------------------------------------------------------------- |
| `enquire_link`      | Either direction | Keepalive check to verify the SMPP session is active. Either side may initiate. |
| `enquire_link_resp` | Either direction | Response confirming the session is alive.                                       |
| `unbind`            | Either direction | Gracefully close the SMPP session. Either side may initiate.                    |
| `unbind_resp`       | Either direction | Acknowledgment confirming the session has been closed.                          |

### Sending Messages

Messages are sent by submitting a `submit_sm` PDU to the Mobile Text Alerts SMPP server. The server will route the message through your account's configured sending number(s) and return a `submit_sm_resp` containing a `message_id` that can be used to track the message.

#### Key Fields for `submit_sm`

| Field                 | Description                                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `source_addr_ton`     | Type of Number for the source address. Use `0x01` (International) for E.164 numbers or `0x00` (Unknown) if unsure. |
| `source_addr_npi`     | Numbering Plan Indicator for the source address. Use `0x01` (ISDN/E.164).                                          |
| `source_addr`         | The sender number. You may leave this empty and Mobile Text Alerts will use your account's default sending number. |
| `dest_addr_ton`       | Type of Number for the destination address. Use `0x01` (International) for E.164 formatted numbers.                |
| `dest_addr_npi`       | Numbering Plan Indicator for the destination. Use `0x01` (ISDN/E.164).                                             |
| `destination_addr`    | The recipient's phone number. Use E.164 format (e.g., `+12125551234`).                                             |
| `data_coding`         | Character encoding for the message body. See [Character Encoding](#character-encoding) below.                      |
| `short_message`       | The message body, encoded according to the `data_coding` value.                                                    |
| `registered_delivery` | Set to `0x01` to request a delivery receipt via `deliver_sm`. See [Delivery Receipts](#delivery-receipts).         |

#### Addressing

For the destination address, use E.164 format: a `+` followed by the country code and subscriber number (e.g., `+12125551234` for a US number). Set `dest_addr_ton` to `0x01` (International) and `dest_addr_npi` to `0x01` (ISDN/E.164).

For the source address, you can either provide your account's dedicated sending number in E.164 format, or leave `source_addr` empty to use your account's default number.

#### Character Encoding

The Mobile Text Alerts SMPP server supports three character encodings:

| Encoding | `data_coding` Value | Max Characters per Segment | Use Case                                                                         |
| -------- | ------------------- | -------------------------- | -------------------------------------------------------------------------------- |
| ASCII    | `0x01`              | 160                        | Standard English text messages. **Default encoding.**                            |
| Latin-1  | `0x03`              | 160                        | Western European languages with accented characters (é, ñ, ü, etc.).             |
| UCS-2    | `0x08`              | 70                         | Full Unicode support including non-Latin scripts (Chinese, Arabic, emoji, etc.). |

If `data_coding` is set to `0x00`, the server will treat the encoding as ASCII.

{% hint style="info" %}
Your SMPP client library may handle `data_coding` selection automatically based on the characters in your message. Refer to your client library's documentation.
{% endhint %}

#### Long Messages

SMS messages that exceed the per-segment character limit (160 for ASCII/Latin-1, 70 for UCS-2) must be split into multiple segments using User Data Headers (UDH) for concatenation. Most SMPP client libraries handle this automatically.

When sending a concatenated (multi-part) message:

* Each segment is sent as a separate `submit_sm` PDU.
* The `short_message` field includes a UDH that identifies the reference number, total number of parts, and the sequence number of each part.
* The `esm_class` field should have bit 6 set (`0x40`) to indicate a UDH is present in the `short_message`.

Each segment consumes one message credit. An SMS message that spans 2 segments will consume 2 credits.

#### Response

A successful `submit_sm_resp` returns `command_status` `0x00000000` (ESME\_ROK) and a `message_id` string. Retain this `message_id` to correlate delivery receipts and to use with `query_sm` or `cancel_sm`.

### Receiving Messages and Delivery Receipts

Inbound messages (mobile-originated messages from subscribers) and delivery receipts are both delivered to your client via `deliver_sm` PDUs on the same SMPP session. Your client must be bound in transceiver or receiver mode to receive these.

#### Inbound Messages (MO)

When a subscriber replies to a message sent from your account, Mobile Text Alerts delivers the reply as a `deliver_sm` PDU. The key fields are:

| Field              | Description                                              |
| ------------------ | -------------------------------------------------------- |
| `source_addr`      | The subscriber's phone number (the sender of the reply). |
| `destination_addr` | Your account's number that the reply was sent to.        |
| `short_message`    | The content of the subscriber's reply.                   |
| `data_coding`      | The encoding of the message body.                        |

Your client must respond with a `deliver_sm_resp` with `command_status` `0x00000000` (ESME\_ROK) to acknowledge receipt. If the server does not receive a valid acknowledgment, it may retry delivery.

#### Delivery Receipts

Delivery receipts (DLRs) report the delivery status of messages you have sent. To receive DLRs, set `registered_delivery` to `0x01` in your `submit_sm` request.

DLRs are delivered as `deliver_sm` PDUs with `esm_class` indicating a delivery receipt. The `short_message` field of a DLR contains a formatted string with the delivery status information.

#### DLR Message Format

The `short_message` field of a delivery receipt follows this structure:

```
id:<message_id> sub:<submitted_count> dlvrd:<delivered_count> submit date:<submit_timestamp> done date:<done_timestamp> stat:<status> err:<error_code> text:<first_20_chars>
```

| Field         | Description                                                                     |
| ------------- | ------------------------------------------------------------------------------- |
| `id`          | The `message_id` returned in the original `submit_sm_resp`.                     |
| `sub`         | Number of messages submitted (typically `001`).                                 |
| `dlvrd`       | Number of messages delivered (typically `001` for delivered, `000` for failed). |
| `submit date` | Timestamp when the message was submitted.                                       |
| `done date`   | Timestamp when the final delivery status was received.                          |
| `stat`        | Delivery status code. See the table below.                                      |
| `err`         | Network-specific error code (may be `000` if not applicable).                   |
| `text`        | First 20 characters of the original message.                                    |

#### Delivery Status Codes

Delivery receipts include a `stat` field that uses standard SMPP delivery status values.

| Status Code | Meaning                                                                     |
| ----------- | --------------------------------------------------------------------------- |
| `DELIVRD`   | Message was successfully delivered to the recipient's handset.              |
| `EXPIRED`   | Message validity period expired before delivery could be completed.         |
| `DELETED`   | Message was deleted before delivery.                                        |
| `UNDELIV`   | Message could not be delivered (permanent failure).                         |
| `ACCEPTD`   | Message has been accepted by the carrier but delivery is not yet confirmed. |
| `UNKNOWN`   | Message status is unknown.                                                  |
| `REJECTD`   | Message was rejected by the carrier or provider.                            |

For error statuses (`UNDELIV`, `REJECTD`, etc.), the `err` field contains the corresponding Mobile Text Alerts delivery status code. See [Check Delivery Status](https://developers.mobile-text-alerts.com/check-delivery-status) to learn more about Mobile Text Alerts delivery status codes and how to interpret them.

#### Distinguishing Inbound Messages from DLRs

Both inbound messages and delivery receipts arrive as `deliver_sm` PDUs. To differentiate them, inspect the `esm_class` field:

* **Inbound message (MO):** `esm_class` = `0x00` (default)
* **Delivery receipt (DLR):** `esm_class` has bits 2–5 set to indicate a delivery receipt (typically `0x04`)

Your SMPP client library may provide a higher-level abstraction for this — consult your library's documentation.

### Message Management

#### Query Message Status

Use `query_sm` to check the current status of a previously submitted message. Provide the `message_id` from the `submit_sm_resp` to retrieve the message's delivery state.

#### Cancel a Message

Use `cancel_sm` to cancel a message that has not yet been delivered. This is useful for time-sensitive messages where delivery after a certain point is no longer relevant. Provide the `message_id` from the `submit_sm_resp`.

{% hint style="info" %}
Cancellation is only possible if the message has not yet been forwarded to the downstream carrier. Once a message is in transit, it cannot be recalled.
{% endhint %}

### Session Management

#### Keepalive (`enquire_link`)

SMPP sessions are long-lived TCP connections. To keep the session active and detect connection issues, the `enquire_link` PDU is used as a heartbeat mechanism. Either side (your client or the Mobile Text Alerts server) may send an `enquire_link`, and the other side must respond with an `enquire_link_resp`.

Configure your SMPP client to send `enquire_link` PDUs at regular intervals. An interval of **30 to 60 seconds** is recommended.

{% hint style="warning" %}
**Inactivity Timeout:** The server will close sessions that have not received any PDU (including `enquire_link`) within **120 seconds**. Ensure your client sends `enquire_link` PDUs well within this window to avoid disconnection.
{% endhint %}

#### Disconnecting

To gracefully close an SMPP session, send an `unbind` PDU. The server will respond with `unbind_resp` and close the connection. If your client disconnects without unbinding (e.g., due to a network failure), the server will detect the broken connection and clean up the session.

#### Reconnection

If your session is disconnected — whether due to network issues, server maintenance, or inactivity timeout — your client should automatically attempt to reconnect and rebind. Implement reconnection with exponential backoff to avoid overwhelming the server:

1. Wait 1 second, then attempt to reconnect.
2. If the connection fails, wait 2 seconds, then retry.
3. Continue doubling the wait time up to a maximum of 60 seconds.
4. Once connected, send a new bind PDU to re-authenticate.

### Error Handling

When a request fails, the server returns a response PDU with a non-zero `command_status` value indicating the reason for the failure.

#### Common SMPP Error Codes

| `command_status` | Name              | Description                                            |
| ---------------- | ----------------- | ------------------------------------------------------ |
| `0x00000000`     | ESME\_ROK         | Success — no error.                                    |
| `0x00000001`     | ESME\_RINVMSGLEN  | Message length is invalid.                             |
| `0x00000002`     | ESME\_RINVCMDLEN  | Command length is invalid.                             |
| `0x00000003`     | ESME\_RINVCMDID   | Invalid or unsupported command ID.                     |
| `0x00000005`     | ESME\_RALYBND     | Client is already bound to the session.                |
| `0x0000000D`     | ESME\_RINVSRCADR  | Invalid source address.                                |
| `0x0000000E`     | ESME\_RINVDSTADR  | Invalid destination address.                           |
| `0x00000045`     | ESME\_RSUBMITFAIL | Message submission failed.                             |
| `0x00000058`     | ESME\_RTHROTTLED  | Request was throttled. Slow down your submission rate. |
| `0x000000FF`     | ESME\_RUNKNOWNERR | An unknown error occurred.                             |

For a complete list of SMPP error codes, refer to the [SMPP v3.4 specification](https://smpp.org/SMPP_v3_4_Issue1_2.pdf), Section 5.1.3.

### Session and Rate Limits

The Mobile Text Alerts SMPP server enforces two types of limits that are configured on a per-account basis:

* **Bind limits** restrict the number of concurrent SMPP sessions (binds) your account can maintain at the same time. If you attempt to bind beyond your account's limit, the bind request will be rejected.
* **Throttling limits** restrict the rate at which your account can submit messages. If you exceed your account's submission rate, the server will return `ESME_RTHROTTLED` (`0x00000058`). Your client should wait briefly and retry.

Your specific limits are communicated when your SMPP credentials are provisioned. Contact your account manager if you need to adjust these limits.

### Comparison: SMPP vs REST API

If you're deciding between the SMPP server and the Mobile Text Alerts REST API, the table below summarizes the key differences:

| Feature               | SMPP Server                                                  | REST API                                                           |
| --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------ |
| Protocol              | SMPP v5.0 over TLS (backwards compatible with v3.4)          | HTTPS (REST/JSON)                                                  |
| Connection model      | Persistent TCP session (long-lived)                          | Stateless HTTP requests                                            |
| Authentication        | `system_id` + `password` (SMPP bind)                         | Bearer token (API key)                                             |
| Best suited for       | Legacy systems, high-throughput pipelines, telecom platforms | Web/mobile applications, modern integrations, event-driven systems |
| Message sending       | `submit_sm` PDU                                              | `POST /send` endpoint                                              |
| Delivery receipts     | `deliver_sm` PDU on the same session                         | `delivery-status` webhook or `GET /deliveries` polling             |
| Inbound messages      | `deliver_sm` PDU on the same session                         | `message-reply` webhook                                            |
| Subscriber management | Not available via SMPP                                       | Full CRUD via `/subscribers` endpoints                             |
| Scheduling            | Not available via SMPP                                       | `scheduledDate` field on `POST /send`                              |
| Groups / segmentation | Not available via SMPP                                       | Full support via `/groups` endpoints                               |
| Templates             | Not available via SMPP                                       | `templateId` on `POST /send`                                       |
| SDK support           | Use any SMPP client library                                  | Official TypeScript SDK                                            |
| Availability          | Early preview (by request)                                   | Generally available with all subscriptions                         |

{% hint style="info" %}
The SMPP server provides message-level operations (send, receive, delivery status). Account management features such as subscriber management, groups, templates, campaigns, and scheduling are available exclusively through the [REST API](https://developers.mobile-text-alerts.com/developer-center-introduction).
{% endhint %}

### Getting Started

1. **Request access.** Contact your account manager or Mobile Text Alerts support to request SMPP access for your account.
2. **Receive your credentials.** Your team will be provided a `system_id` and `password` for authenticating with the SMPP server.
3. **Configure your SMPP client.** Set the connection details in your SMPP client library:

   | Setting     | Value                                |
   | ----------- | ------------------------------------ |
   | Host        | `smpp.mobile-text-alerts.com`        |
   | Port        | `2776`                               |
   | TLS         | Enabled (required)                   |
   | `system_id` | *(provided by your account manager)* |
   | `password`  | *(provided by your account manager)* |
4. **Bind to the server.** Establish a TLS connection and send a `bind_transceiver` PDU with your credentials. A successful `bind_transceiver_resp` with `command_status` `0x00000000` confirms you are connected and authenticated.
5. **Send a test message.** Submit a `submit_sm` PDU with `registered_delivery` set to `0x01` to a test phone number. Verify you receive both a `submit_sm_resp` (with a `message_id`) and a subsequent `deliver_sm` with the delivery receipt.
6. **Set up `enquire_link`.** Configure your client to send `enquire_link` PDUs every 30–60 seconds to keep the session alive. The server will close sessions that are inactive for more than 120 seconds.