Bulk SMS API - SMPP to SMS

You can easily connect to our servers using the Industry Standard SMPP protocol using your own login credentials. The SMPP version 3.3 protocol specification is available in PDF format as are the SMPP version 3.4 and SMPP version 5.0 specifications.

We particularly draw your attention to the SMPP Acceptance Test Plan mentioned towards the bottom of this document. Completing the Acceptance Test will ensure that your servers and our servers communicate correctly.

Introduction

Although the SMPP API is mainly aimed at high-volume customers, we do not currently put any restrictions on its usage.

The current API supports the following SMPP version 3.3 and 3.4 Protocol Description Units (PDU’s):

  • BIND_TRANSMITTER / BIND_TRANSMITTER_RESP
  • BIND_RECEIVER / BIND_RECEIVER_RESP
  • SUBMIT_SM / SUBMIT_SM_RESP
  • ENQUIRE_LINK / ENQUIRE_LINK_RESP
  • QUERY_SM / QUERY_SM_RESP
  • DELIVER_SM / DELIVER_SM_RESP
  • BIND_TRANCEIVER / BIND_TRANCEIVER_RESP
  • UNBIND / UNBIND_RESP

You must honour the unbind PDU by issuing a unbind_resp PDU before disconnecting.
You are also required to honour the enquire_link PDU by sending an enquire_link_resp PDU.

Binding

Port 2775 (non-encrypted) and 2776 (secure/TLS) on both s3.csoft.co.uk and s4.csoft.co.uk are open for SMPP connections. You should bind to both servers as either one may be taken off-line for maintenance. Binding to both will greatly enhance your service reliability.

The following credentials should be used in all bind PDU's:

  • system_id – your username
  • password – your PIN
  • system_type – blank

Security

Binding to port 2776 supports Transport Layer Security (TLSv1.0, TLSv1.1, TLSv1.2).

Submitting Messages

Please bind to our servers as a Transmitter or a Tranceiver. Our SMSC default alphabet (data_coding=0x00) is the GSM 03.38 7-bit ASCII alphabet, but we fully support the following character sets:

Data Coding Character set
0x01 IA5 ASCII ANSI X3.4
0x03 ISO-8859-1 (ISO Latin 1)
0x05 JIS
0x06 ISO-8859-5 (Cyrillic)
0x07 ISO-8859-8 (Latin/Hebrew)
0x08 UCS2 ISO/IEC 10646

We also support the SMPP version 3.4 message_payload (tag ID 0x0424) optional parameter. This allows you to send us messages that are longer than 160 characters. We will split long messages before passing them to Network Operators.

The message ID is returned in the sm_submit_resp PDU as an 8-digit hexadecimal number.

Delivery Receipts & Two-Way SMS Messages

Please bind to our servers as a Receiver or a Tranceiver.

To receive delivery receipts, you need to configure SMPP as the delivery mechanism for delivery receipts on your account. You can do this via the website: log in and select "Real-Time Delivery Receipts" from the "Account Centre". This will route all delivery receipts for messages sent on your account to your SMPP bind. The format of delivery receipts is as given in Appendix B of the SMPP v3.4 specification. The message ID in the delivery receipt is given as a 10-digit decimal number.

Similarly, to receive Two-Way SMS messages via your SMPP bind, configure this service via the website. Select "Two-Way SMS Configuration" from the "Account Centre".

If your SMPP Receiver or Transceiver bind is unavailable we will try to resend receipts for up to 24 hours.

Error Handling

The SMPP API supports the SMPP command_status as specified in section 5.1.3 of the SMPP Protocol Specification v3.4

In addition to the standard command_status values it is important that you expect and deal correctly with the command_status ESME_RNOCREDIT (0x00000400) .

This code will be returned when you are out of credit. If you receive this code in response to a bind PDU you should NOT try to rebind into either server until you have sufficient funds in your account. If you receive this code as a response to a submit PDU you should NOT try to resend the message to either server and an unbind PDU will be issued which must be honoured.

Standoff

If your Bind or Submit PDU is refused and you wish to resend it, please adhere to our stand-off strategy. You should wait for 30 seconds up to a maximum of 3 attempts after which you should wait for 5 minutes before resending the PDU. Do not try to resend PDU's that have been refused for a genuine reason like invalid number ESME_RINVDSTADR (0x0000000B) or out of credit ESME_RNOCREDIT (0x00000400) .

Mobile Numbers for Testing

The number range 07700 900000 to 900999 is designated by Ofcom for Drama purposes i.e. for Radio and Television.  This range of 1000 numbers can be used for testing and no messages will be sent or charges incurred.

Systems for Testing

For testing only, the primary bind should be to a test system whose IP address will be advised. Access to the test system will be provided on request.

SMPP PDU Decoding/Encoding

You can decode and encode SMPP PDUs using our free utilities. For your convenience we provide both an online and offline decoder/encoder to help you debug your SMPP PDUs.

SMPP Acceptance Test Plan

We strongly encourage all customers with SMPP connection to work with us to complete our SMPP Acceptance Test. Passing this test will ensure that our systems are configured correctly and thus ensure the best possible service. If your system does not behave appropriately, for example by repeatedly retrying failed messages, then we reserve the right to block your access until the problem is resolved. We would much prefer to work with you to prevent such problems occurring in the first place. A PDF copy of the SMPP Acceptance Test Plan Version 10 is available here.

Your session is about to expire

You will be logged out in seconds.

Do you want to stay signed in?

Yes, keep me signed in     No, Sign me out