SMPP: the complete protocol guide.

What SMPP is & where it fits

An SMPP session always has two roles. The ESME (External Short Messaging Entity) is your application — a bulk-SMS platform, an OTP service, an alerting system. The SMSC (Short Message Service Centre), called an MC (Message Centre) in v5.0, is the operator or aggregator node that store-and-forwards messages to and from handsets over the mobile network. The ESME connects to the SMSC; the SMSC connects to the wider SS7 / mobile core.

SMPP is the backbone of A2P (Application-to-Person) messaging — verification codes, receipts, alerts, marketing — as opposed to P2P (Person-to-Person) texting between two handsets. A2P traffic is high-volume, machine-generated and delivery-receipt driven, which is exactly what SMPP was designed to carry.

Why a binary TCP protocol instead of HTTP? A single SMPP bind is a long-lived socket. Once it is open you avoid a TCP and TLS handshake per message, you can have many messages in flight at once (asynchronous windowing), and the SMSC pushes delivery receipts and inbound messages straight back down the same connection. At sustained high throughput this is dramatically more efficient than a request/response HTTP API — which is why operators and large senders standardise on it.

Version history

• SMPP v3.3 — the first widely deployed version; introduced the core PDU set but predates TLVs (optional parameters) and the transceiver bind.
• SMPP v3.4 — the dominant version in production today. Added the transceiver bind, optional TLV parameters, message_payload, and data_sm. Almost every real-world integration you will build speaks v3.4.
• SMPP v5.0 — the newest version. Renames SMSC to MC, adds broadcast PDUs (broadcast_sm), congestion-state signalling and more standardised TLVs. Adoption is limited; support v3.4 first and treat v5.0 as opt-in.

Architecture & bind types

The topology is simple: the ESME opens a TCP connection to the SMSC/MC and authenticates with a system_id and password. The direction the session is allowed to carry traffic is fixed at bind time by choosing one of three bind modes. Each mode is a different bind PDU.

A fourth actor is routing: the SMSC decides, per message, which downstream operator route or interconnect a submitted message takes toward the destination handset, and which bound ESME an inbound (mobile-originated) message belongs to.

On the wire, SMPP runs over TCP. The IANA-registered default port is 2775 for plain connections. SMPPS — SMPP wrapped in TLS — has no single standard port; providers expose it on a port of their choosing (3550, 8775 and 2776 are all seen in practice). Always use the encrypted port your provider assigns for production.

The session lifecycle

Every SMPP session follows the same arc: open TCP, bind, stay alive, exchange messages and receipts, then unbind and close. The diagram below traces a full transceiver session — each row is one PDU, blue flowing from the ESME to the SMSC, green flowing back.

Two important details. First, submit_sm_resp returns immediately and only means “accepted for delivery” — the real outcome arrives later as a deliver_sm receipt. Second, every request PDU has a matching _resp that echoes its sequence_number, which is how asynchronous responses are correlated back to requests.

PDU anatomy

Everything on an SMPP connection is a PDU. Every PDU begins with a fixed 16-byte header of four 4-byte (32-bit, big-endian) integers, followed by a command-specific body. Read the header first and you know exactly how to read the rest.

The body ends with any number of TLVs — optional parameters encoded as Tag (2 bytes), Length (2 bytes), Value (Length bytes). TLVs are how v3.4 extended the protocol without breaking older peers: message_payload, receipted_message_id, sar_* concatenation fields and many more all ride as TLVs.

The sequence_number is the key to windowing. Because SMPP is asynchronous, an ESME can send many submit_sm PDUs — each with an incrementing sequence_number — before any responses arrive. When submit_sm_resp PDUs come back, their sequence_number tells you which submission each one answers. The number of unacknowledged PDUs allowed in flight is the window size.

Core PDUs reference

These are the operations you will actually use. Each request has a response PDU whose command_id is the request’s id with the high bit set (0x80000000), so submit_sm 0x00000004 pairs with submit_sm_resp 0x80000004.

submit_sm field-by-field

submit_sm is the PDU you will send most. Its body is a sequence of mandatory parameters, then optional TLVs. These are the fields that matter in practice.

Data coding & concatenation

The data_coding field (the Data Coding Scheme, DCS) tells the handset how to interpret the bytes, and it decides how many characters fit in one SMS.

A message longer than one segment is split and reassembled on the handset using a UDH (User Data Header) prepended to each part. The concatenation element uses IEI 0x00 (8-bit reference) — a 6-octet header carrying a reference number, the total part count and this part’s index. Those 6 octets are why the per-part limits drop to 153 (GSM 7-bit) and 67 (UCS-2). When you send a UDH inside short_message you must also set the UDHI bit (0x40) in esm_class.

There are two ways to send long content: build the UDH-segmented parts yourself (each a submit_sm with UDHI set), or hand the whole body to the SMSC in the message_payload TLV and let it segment. Some SMSCs instead accept the sar_msg_ref_num / sar_total_segments / sar_segment_seqnum TLVs to describe concatenation without a UDH.

Delivery receipts (DLR)

When you set registered_delivery = 1, the SMSC later reports the message’s fate by sending you a deliver_sm with the delivery-receipt bit set in esm_class (0x04). The receipt text lives in the short_message field as a well-known keyword string:

id:1a2b3c4d5e sub:001 dlvrd:001 submit date:2607251432 done date:2607251432 stat:DELIVRD err:000 text:Your code is 8

The id matches the message_id you got back in submit_sm_resp (also echoed in the receipted_message_id TLV 0x001E). The stat field carries the final state:

Always answer a deliver_sm with a deliver_sm_resp; if you do not, the SMSC will re-send the receipt and may throttle or drop the bind. Note that receipt formatting is not perfectly standardised — providers vary slightly in field order and the err code map.

Error / command_status codes

Every response PDU carries a command_status in its header — an ESME_R* code. Zero means success; anything else describes why the request was refused. These are the ones you will meet most.

The full registry — including provider-specific vendor ranges — is searchable in the SMPP error-code reference.

Throughput, windowing & throttling

Throughput in SMPP is measured in TPS — transactions (submit_sm) per second — and it is governed by two things: the rate the SMSC permits, and how many messages you keep in flight. Because SMPP is asynchronous you do not have to wait for each submit_sm_resp before sending the next PDU. The number of unacknowledged submissions you allow at once is your window size (commonly 10–100). A larger window hides round-trip latency and raises effective TPS — up to the SMSC’s ceiling.

• Respect the throttle. When the SMSC returns ESME_RTHROTTLED (0x58), back off — pause and retry with exponential backoff rather than hammering the bind, which can get you disconnected.
• Keepalive on a cadence. Send enquire_link roughly every 30 seconds while idle; if a few go unanswered, assume the link is dead.
• Reconnect deliberately. On disconnect, reconnect and re-bind with backoff and jitter; do not tight-loop. Track outstanding sequence_numbers so you can reconcile receipts after a reconnect.
• Scale with binds, carefully. Higher aggregate TPS usually comes from multiple binds — but only up to the limit your provider authorises per account.

Code sample

An illustrative connect → bind → submit flow in Node-style pseudocode. Real SMPP libraries (for example node-smpp, jSMPP for Java, or python-smpplib) handle PDU encoding for you; this shows the shape of the session, not a specific library’s API.

import smpp from "smpp";

// 1. Open a TCP (or TLS) session to the SMSC.
const session = smpp.connect({
  // Host, port and bind credentials come with your test access.
  // Plain SMPP conventionally uses 2775; the TLS port is provided with your account.
  url: process.env.SMPP_URL!,             // e.g. smpp://<host>:2775 (plain) or smpps://<host>:<tls-port>
  auto_enquire_link_period: 30000,        // keepalive every 30s
});

// 2. Bind as a transceiver.
session.bind_transceiver(
  {
    system_id: "YOUR_SYSTEM_ID",
    password:  "YOUR_PASSWORD",
    system_type: "",
  },
  (pdu) => {
    if (pdu.command_status !== 0) {
      throw new Error("bind failed: 0x" + pdu.command_status.toString(16));
    }

    // 3. Submit a Unicode message, asking for a delivery receipt.
    session.submit_sm(
      {
        source_addr_ton: 5,                // alphanumeric Sender ID
        source_addr:      "BroadNet",
        dest_addr_ton:    1,               // international E.164
        destination_addr: "447700900123",
        registered_delivery: 1,            // request a DLR
        data_coding: 8,                    // UCS-2 (Unicode)
        short_message: "Your code is 8123",
      },
      (submitResp) => {
        // submit_sm_resp returns the SMSC message_id.
        console.log("accepted, message_id =", submitResp.message_id);
      }
    );
  }
);

// 4. Receive delivery receipts on the same session.
session.on("deliver_sm", (pdu) => {
  if ((pdu.esm_class & 0x04) === 0x04) {   // delivery-receipt bit
    console.log("DLR:", pdu.short_message.message);
  }
  session.send(pdu.response());            // ALWAYS deliver_sm_resp
});

BroadNet SMPP

BroadNet operates a carrier-grade SMSC gateway that accepts SMPP v3.4 binds over TLS. You get transceiver binds, high TPS with async windowing, full delivery receipts, Unicode and concatenation, and an IP-allowlisted, credentialled connection to reach operators worldwide. It is the same protocol taught on this page — pointed at real routes.

Frequently asked questions

Related tools & docs