SMPP

Request access

Contact TNZ for SMPP pricing and access credentials. Tell us:

• Your SMPP client or library and its version.
• The countries you intend to send messages to.
• Your expected message volume and peak sending rate.
• Whether you need inbound SMS and delivery receipts.

Your TNZ representative will arrange access and explain how to supply your client IP addresses for allowlisting. Do not include passwords in an initial enquiry.

Setup sequence

1. Request access and IP allowlisting through a TNZ representative.
2. Configure your connection and bind with the settings TNZ supplies.
3. Submit a test SMS to a test number you control.
4. Check the receipt and match its message ID to the ID in the submission response.
5. Complete compatibility testing before production use.

Connect and bind

Your TNZ representative provides your hostname and credentials privately and arranges allowlisting for your client IP addresses.

Connection settings

Recommended starting settings

Configure these settings in your client, then test them at your agreed sending rate. The server does not enforce client timeouts or keepalive intervals.

Limits and session behaviour

Keep your total active binds within the limit agreed with TNZ. The connection limit applies separately to each connector process, rather than across all servers.

Stay within the sending rate agreed with TNZ. The connector does not enforce a submission rate limit. Confirm whether your agreed rate counts submissions or message parts.

Your client must send keepalive requests. The connector does not send them or disconnect sessions solely because they are idle. A timeout while the connector reads an incomplete protocol data unit (PDU) can disrupt subsequent PDU parsing. Include partial-PDU timeouts in your connection recovery tests.

Send SMS

Use submit_sm on a TX or TRX session. Use your account's provisioned sender identities, with the destination number format and TON/NPI settings supplied by TNZ.

Check the address format before sending. The connector passes addresses through unchanged, regardless of the submission TON/NPI values.

submit_sm
  sequence_number: 2
  source_addr: <SOURCE>
  destination_addr: <DESTINATION>
  esm_class: 0
  registered_delivery: 1
  data_coding: 0
  sm_length: 5
  short_message hex: 48 65 6C 6C 6F

submit_sm_resp
  sequence_number: 2
  command_status: 0
  message_id: 01900000-0000-7000-8000-000000000001

Submission fields

For a complete message, the submission response contains a lowercase, hyphenated UUID. Store this message ID exactly as received, without converting it to a number or changing its case.

Supported operations

The connector handles TX/RX/TRX binds, submit_sm, enquire_link and unbind. It sends deliver_sm and logs client deliver_sm_resp responses.

query_sm, cancel_sm, replace_sm, submit_multi and data_sm are unsupported. The connector sends neither a response nor a generic_nack for unsupported commands. Set a response timeout in your client to handle unanswered requests.

Encoding and multipart messages

Choose an encoding

Use the encodings in the table above. Other coding values fall back to UTF-8 decoding, with replacement characters for invalid bytes. This fallback does not support other encodings or binary SMS. Test Unicode text on the receiving handset and check the inbound Unicode limitations below.

For example, to send Hi 😀, use data_coding=8, sm_length=10 and bytes 00 48 00 69 00 20 D8 3D DE 00.

Multipart submissions

For multipart messages, submit each segment with a UDH containing an 8-bit concatenation reference (information element 0x00) or a 16-bit reference (information element 0x08). Set the UDHI bit (0x40) in esm_class.

Your client supplies the segments, which the connector combines into one message for delivery. The connector does not split messages into SMS parts. Ask TNZ for the SMS part limits and charges that apply to your connection.

• Do not split a UTF-16 surrogate pair or a GSM escape sequence between message parts. The connector decodes each part independently.
• SAR TLVs and message_payload are unsupported. Put the message text in the short_message field. A submission that contains text only in an ignored TLV can return success with an empty message.
• Use the same concatenation reference for every part of one message. Use a different reference for each concurrent message with the same sender and destination.
• Disconnecting and reconnecting does not clear incomplete multipart messages. They remain in memory without an expiry time, but a connector restart removes them.

Delivery receipts

Receipts arrive on an RX or TRX bind as deliver_sm with esm_class=0x04 and data_coding=0. The source and destination address fields both contain the destination address from the original submission, with TON/NPI 1/1.

id:01900000-0000-7000-8000-000000000001 sub:001 dlvrd:001 stat:DELIVRD err:000

Read the status

UNDELIV covers both temporary delivery states and final failures. Do not automatically resend based only on this status. The error field can be 000 even on failure. Use the status mapping above when processing receipts.

Receipts always report sub:001. A multipart message has one UUID, so its receipts identify the complete message rather than individual parts.

Receipt options and acknowledgements

The registered_delivery setting does not filter delivery receipts. Your client must handle both success and failure receipts, including when it requests no receipts or failure receipts only.

Acknowledge each receipt promptly with deliver_sm_resp. Use the sequence number from the receipt, status 0 and an empty message ID. Where possible, save the receipt to persistent storage before acknowledging it. The connector logs acknowledgements but does not use them to clear pending receipt records or decide whether to resend receipts.

A delivery receipt does not tell you whether the recipient read the message. Do not rely on receipts being resent after a disconnection. See Acknowledgements and retries under Receive SMS.

Receive SMS

Ask TNZ to arrange a receiving number and route its messages to your connection. Inbound SMS arrive as deliver_sm with esm_class=0, which distinguishes them from delivery receipts. Use an RX or TRX bind.

Inbound encoding and length limits

Neither inbound method splits messages into parts or includes multipart headers or SAR TLVs. At 256 encoded bytes or more, the length field overflows and no longer matches the message size. Percent-decoding can also corrupt multibyte UTF-8. Arrange tests with TNZ using the characters and message lengths your application needs to receive on this connection.

Acknowledgements and retries

Promptly acknowledge inbound messages with deliver_sm_resp, the same sequence number, status 0 and an empty message ID.

• The connector does not wait for an acknowledgement or resend a message when an acknowledgement is missing. It considers a message delivered once it writes the message to the client connection.
• The connector rejects HTTP callbacks while your account is disconnected and does not store them. The system sending the callback must handle retries.
• Queued messages and delivery statuses can be lost if no receiving session is available or a socket write fails.
• When your client binds again, the connector loads saved retry messages into memory and deletes their files before your client acknowledges them. These messages can still be lost before acknowledgement. Do not rely on automatic retries for file-based inbound messages.
• Handle duplicate messages in your client and keep your own message records. Confirm retention arrangements with TNZ.
• The connector tries receiving sessions in registration order and sends each message or receipt to the first session it can write to successfully. It does not rotate deliveries evenly between sessions or send a copy to every session.

Test your connection

Before testing, agree on the test account, destination numbers and message volume with TNZ. Check that your client library handles the responses described in this guide.

1. Verify TLS certificate and hostname validation on port 2776, then bind using SMPP 3.4 and your provisioned credentials.
2. Send GSM extension characters, Latin-1 and UTF-16BE emoji. Check that the text displayed on the handset matches the text your application sent.
3. Test both UDH reference formats, out-of-order parts and your library's handling of empty response bodies for incomplete multipart submissions.
4. Match complete-message UUIDs to successful and unsuccessful receipts. Check both temporary and final delivery statuses against the receipt mapping above.
5. Test inbound text on your configured connection, including Unicode and the message lengths your application uses.
6. Agree controlled tests for reconnects, outstanding submissions, missing acknowledgements, process restarts and multiple receivers.
7. Test the recommended request window and timeouts at your agreed sending rate.

The connector cannot answer message status queries or detect duplicate submissions. If the connection drops before a response arrives, your client cannot determine whether the submission succeeded. Retrying the submission can send the same message twice.

Errors and troubleshooting

Response codes

The connector does not return ESME_RTHROTTLED when your client exceeds its agreed sending rate. Set your client to stay within the rate agreed with TNZ.

Do not rely on automatic retries for unacknowledged deliveries. Retain sequence numbers and complete-message IDs for troubleshooting.

Common questions

Get help with SMPP

When contacting support, include the UTC time of the issue and your client library name and version. We also need the bind type, sequence numbers, message IDs, SMPP command and response status, text encoding and message byte count. For multipart issues, add the concatenation reference, total number of parts and each part's sequence number. Also provide your request window, sending rate and reconnect history.

Send the steps to reproduce the issue and a PDU trace with sensitive information removed. Check configuration and PDU logs for credentials, authentication keys, private keys, connection addresses, personal telephone numbers and message content before sharing them. Bind PDUs contain credentials even in hexadecimal form, so remove those values from the trace as well.

For questions about connection settings, sending limits, message formatting or delivery behaviour, contact TNZ.