Version
Mandatory Fields
Each SMPP PDU includes a set of mandatory fields that must be present for the message to be considered valid and properly processed by the SMSC. These fields carry essential information such as the source and destination addresses, message content, and metadata required for routing and delivery.
The table below shows the complete set of mandatory SMPP parameters.
| system_id | Identifies the external system (ESME) to the SMSC during the bind process. This is typically a username or unique identifier used for authentication and routing. |
| password | The password associated with the system_id, used to authenticate the ESME during a bind request. |
| system_type | Specifies the type of system binding to the SMSC. It's an optional field in terms of protocol behavior but often required by SMSCs for routing or service differentiation. Common values include "SMPP" or service-specific identifiers like "EMAIL" or "WWW". |
| interface_version | Indicates the version of the SMPP protocol the ESME supports. This helps the SMSC determine compatibility. For example, 0x34 corresponds to version 3.4 of the protocol. |
| addr_ton, source_addr_ton, dest_addr_ton, esme_addr_ton | TON stands for Type of Number. These fields specify the numbering format used for addresses (e.g., international, national, alphanumeric). For example: • 0x01 = International • 0x02 = National • 0x05 = Alphanumeric (e.g., sender ID) Used by the SMSC to correctly interpret the address format of either the sender or recipient. |
| addr_npi, source_addr_npi, dest_addr_npi, esme_addr_npi | NPI stands for Numbering Plan Indicator. These fields define the numbering plan associated with the address (e.g., ISDN, data, telex). For example: • 0x01 = ISDN (most commonly used for phone numbers) • 0x03 = Data • 0x08 = National Used together with TON to guide the SMSC in correctly routing and processing addresses. |
| address_range | Used during the bind process to specify a range of destination addresses the ESME intends to serve. Often left empty ("") to indicate no restriction. When used, it enables the SMSC to filter which messages the session should receive or handle. |
| source_addr | The address of the message originator. This could be a phone number (e.g., +1234567890) or an alphanumeric sender ID (e.g., "MyApp"), depending on the source_addr_ton and source_addr_npi values. Required for message submission. |
| destination_addr | The recipient's address for the message. This is typically a mobile phone number. Its format must match what’s indicated by dest_addr_ton and dest_addr_npi. |
| esme_addr | Used in some PDU types (like alert_notification) to specify the address of the ESME being notified. It's structurally similar to source_addr or destination_addr and follows the same TON/NPI rules. |
| service_type | Indicates the type of messaging service being requested. Commonly left blank unless the SMSC requires a specific value (e.g., "CMT" for cellular messaging, "CPT" for packet data). Useful for routing messages through service-specific logic. |
| esm_class | Stands for Extended Short Message Class. This field controls messaging modes and features such as: • Message type (e.g., delivery receipt, message forwarding) • Message mode (e.g., default store-and-forward vs. datagram) • Special message handling flags It’s a bitfield, so multiple flags can be combined using bitwise operations. It plays a key role in advanced message behavior like delivery reports or cell broadcasting. |
| protocol_id | Used to indicate the higher-level protocol being used. In most cases, it’s set to 0x00 and ignored by the SMSC. Some networks may use it to support interworking with other protocols (e.g., X.400, email gateways), but this is uncommon in typical SMS scenarios. |
| priority_flag | Specifies the priority level of the message. While its effect depends on the SMSC’s implementation, values range from 0 (lowest) to 3 (highest). Higher priority messages may be delivered sooner or handled differently under load. |
| schedule_delivery_time | Specifies the absolute time when the message should be delivered. If empty or set to null, the message is sent immediately. The value must be in a specific absolute time format defined by SMPP (YYMMDDhhmmss...). |
| validity_period | Defines how long the SMSC should keep trying to deliver the message if the recipient is unavailable. After this period, the message expires and is discarded. Like schedule_delivery_time, it must be in SMPP’s absolute or relative time format. |
| registered_delivery | Controls whether and what type of delivery receipt the SMSC should return. Values include: • 0x00: No receipt • 0x01: Delivery receipt requested on success or failure • 0x02: Delivery receipt only on failure Essential for tracking message delivery status. |
| replace_if_present_flag | Instructs the SMSC to replace an existing message with the same source_addr and destination_addr if found. Set to 1 to enable replacement; 0 to allow duplicate messages. Rarely used in modern implementations. |
| data_coding | Specifies the character encoding of the message body. Common values: • 0x00: GSM 7-bit (default) • 0x08: UCS2 (for Unicode support, e.g., non-Latin scripts) • 0x04: 8-bit binary data Correct setting ensures message content displays properly on the recipient device. |
| sm_default_msg_id | Refers to a predefined message stored on the SMSC. If set to a non-zero value, the SMSC sends that stored message instead of the one in short_message. Typically set to 0x00 when the ESME provides the message content directly. |
| sm_length | Indicates the length of the short_message field in octets (bytes). Must accurately reflect the number of bytes in the message content, especially when using non-GSM encodings like UCS2 or binary. |
| short_message | Contains the actual SMS text or binary payload. Its maximum length depends on the encoding: • Up to 160 characters for GSM 7-bit • Up to 140 bytes for binary • Up to 70 characters for UCS2 If longer messages are required, message segmentation or the message_payload TLV is used. |
| message_id | A unique identifier assigned by the SMSC to a submitted message. Returned in submit_sm_resp, it can be used later with query_sm to check message status or trace delivery. |
| number_of_dests | Used in the submit_multi PDU to indicate how many destination addresses are included. This is followed by a list of destination address structures. |
| dest_flag | Found in submit_multi, this flag defines whether the destination is a single SME address or a distribution list. Helps the SMSC interpret how to route the message. |
| no_unsuccess | Returned in submit_multi_resp, this field shows the number of destinations where delivery failed. If no_unsuccess > 0, the response also includes a list of UnsucessfulSME structures detailing each failure. |
| dl_name | Specifies the name of a distribution list when using submit_multi with group messaging. The SMSC must be pre-configured with the list name and its associated recipients. |
| message_state | Used in query_sm_resp to indicate the current status of a previously submitted message. Common values include: • 0x01: Enroute • 0x02: Delivered • 0x03: Expired • 0x04: Deleted • 0x05: Undeliverable • 0x06: Accepted • 0x07: Unknown • 0x08: Rejected Helps clients track lifecycle events for submitted messages. |
Start innovating with Mobius
What's next? Let's talk!