SMPP

Achieve granular control and low latency of SMS messaging and with the Sinch Enhanced SMPP service.

Sinch offers a traditional telecoms protocol for submission of bulk SMS. This protocol is called the SMPP Protocol. More information about the general use and availability of the protocol can be found around the web. Read more here to understand the Sinch specific implementation of the SMPP Protocol.

If you would like to use SMPP services, please reach out to our Sales team. You can contact them here.

SMPP Outbound

SMPP account details

Host <host>.smpp.api.sinch.com
Port 3601 (TLS 1.2 Port)
System-ID <system-id>
Password <password>

Maximum instances (binds): Default 2 per SMPP account. For more connections, contact your account manager.

IP Access

To access the Sinch SMPP server, the client IP range must be announced and added to the client account.

Supported SMPP PDUs

SMPP PDU types
bindtransmitter / bindtransmitter_resp
bindreceiver/ bindreceiver_resp
bindtransceiver / bindtransceiver_resp
enquirelink / enquirelink _resp
unbind / unbind_resp
submitsm / submitsm_resp
datasm / datasm_resp
deliversm / deliversm_resp
generic_nack
querysm / querysm_resp
cancelsm / cancelsm_resp
replacesm / replacesm_resp

Source Address

Source Address Arrive on handset
Sent to Sinch Type Of Number(TON) Number Plan Indicator(NPI)
00461234567889 0x00 Unknown 0x01 MSISDN 046123456789
01234567889 0x00 Unknown 0x01 MSISDN 123456789
461234567889 0x01 International 0x01 MSISDN +46123456789
1234567889 0x02 National 0x01 MSISDN 123456789
Sinch 0x05 Alphanumeric 0x00 Unknown Sinch

The type of source address is defined by the source address TON and NPI parameters.

  • Alphanumeric sender is limited to a maximum length of 11 characters.
  • MSISDN sender maximum length is 18.
  • To enable a handset to respond to a short code, we recommend to use TON=0x00 and NPI=0x01.

Destination address

Destination Address
Sent to Sinch Type Of Number (TON) Number Plan Indicator (NPI)
46123456789 0x01 | International 0x01 MSISDN

MSISDN Format

In GSM, MSISDN is built up as:

MSISDN CC + NDC + SN
CC Country Code
NDC National Destination Code
SN Subscriber Number

For further information on the MSISDN format, see the ITU-T specification E.164.

Throughput and throttling

Throughput is the maximum number of MT messages per second that can be sent from the SMPP account to Sinch. The default value is 10 per bind. To increase the value, contact your account manager.

The recommended default window size (maximum open requests) is 10. The throughput can be restricted by the capacity of the operator receiving the MT messages.

It's recommended to set your enquire_link requests to 60 seconds.

Schedule delivery time

In order to schedule a message to be sent in the future, the optional parameter scheduledeliverytime may be added. Messages can be scheduled a maximum of 168 hours, one week, ahead of time. It can be specified in either absolute time format or relative time format. If this parameter is omitted, messages are sent immediately.

For example, the following time formats:

scheduledeliverytime Would be interpreted as:
100312163200004+ An absolute time - March 12 2010 16:32:00 GMT+1h.
000006233429000R A relative period of 6 days, 23 hours, 34 minutes and 29 seconds from the current SMSC time.

Time Zone

Sinch SMSC uses UTC (Coordinated Universal Time)

MCC MNC in delivery reports

MCC + MNC information in SMPP delivery receipts can be included as an optional parameter. This information is passed (configurable per SMPP account whether to enable this) in a vendor-specific TLV (0x1403).

In the value field, you will receive the MCC MNC of the destination operator.

Example:

Optional parameter: 0x1403 (0x1403):

  • Tag: 0x1403
  • Length: 6
  • Value (hex): 32 33 34 33 30 00 (Text: 23430n)

Result is MCC=234 and MNC=30

SMPP Inbound

How To Connect

Find the host and port number used to connect to our inbound service via SMPP in the table below. Username and password will be found in the CAD (Client Account Details) document provided to you by your account manager.

Host <host>.smpp.api.sinch.com
Port 3601 (TLS 1.2 Port)
System-ID <system-id>
Password <password>

How To Receive Messages

Encoding

A Data Coding Scheme must be specified when using SMPP. We recommend the data_coding parameter be set to 0 for basic GSM-7 encoding. For better delivery of characters outside of the GSM-7 character default alphabet, we recommend the data_coding parameter be set to 8 for UCS-2 encoding.

Parameters

Inbound messages will be delivered to your platform as a DELIVER_SM. The table below shows which parameters you will receive for each mobile originated SMS sent to your number.

Parameter Description
command_id Will always be DELIVER_SM
service_type Will always be 0
sourceaddrton TON for the source address, will be INTERNATIONAL (1) for all mobile originated messages
sourceaddrnpi NPI for the source address, will be MSISDN (1) for all mobile originated messages
source_addr Source address - the MSISDN the SMS was sent from
destaddrton TON for the destination address, will be INTERNATIONAL (1) Long numbers and NATIONAL (2) for Short code
destaddrnpi NPI for the destination address, will always be MSISDN (1)
destination_addr Destination address - the MSISDN the SMS was sent to (your Long Number or Short Code)
esm_class Will always be 0
protocol_id Will always be 0
priority_flag Will always be 0
scheduledeliverytime Will always be 0
validity_period Will always be 0
registered_delivery Will always be 0
replaceifpresent_flag Will always be 0
data_coding Encoding used. Default is GSM-7 (0), UCS-2 for messages containing characters outside GSM-7 (8)
smdefaultmsg_id Will always be 0
sm_length Short Message Length - number of characters in message content
short_message Message content

Examples

Inbound SMS sent to a Long Number

Parameter Example
command_id DELIVER_SM
service_type 0
sourceaddrton 1
sourceaddrnpi 1
source_addr 46706160585
destaddrton 1
destaddrnpi 1
destination_addr 46737494630
esm_class 0
protocol_id 0
priority_flag 0
scheduledeliverytime 0
validity_period 0
registered_delivery 0
replaceifpresent_flag 0
data_coding 0
smdefaultmsg_id 0
sm_length 4
short_message Test

Inbound SMS sent to a Short Code

Parameter Example
command_id DELIVER_SM
service_type 0
sourceaddrton 1
sourceaddrnpi 1
source_addr 46706160585
destaddrton 2
destaddrnpi 1
destination_addr 71630
esm_class 0
protocol_id 0
priority_flag 0
scheduledeliverytime 0
validity_period 0
registered_delivery 0
replaceifpresent_flag 0
data_coding 0
smdefaultmsg_id 0
sm_length 4
short_message Test

SMPP connection error codes

All errors on the SMPP connection received in SUBMITSMRESP are described in the SMPP Protocol Specification v3.4 Issue 1.2 chapter 5.1.3 command_status.

Messages states

A message will always be in one of the following states:

Message state Value Description
ENROUTE 1 Message is in the process of being sent to the destination
Delivered 2 Message has been delivered to destination
EXPIRED 3 Message validity period has expired
DELETED 4 Message has been deleted
UNDELIVERABLE 5 Message is undeliverable
UNKNOWN 7 Message is in invalid state

The states are described in the SMPP Protocol Specification v3.4 Issue 1.2 chapter 5.2.28 messagestate. The message state value is also attached in a SMPP Optional Parameter “messagestate” value 0x0427 described in the SMPP Protocol Specification v3.4 Issue 1.2 chapter 5.3.2.35.

Status reports error codes

The error codes are provided in status reports according to the SMPP Protocol Specification v3.4 Issue 1.2 Appendix B. The following are the error codes Sinch networks will be sending:

Error Error Class Description Comment Treated as
0 NO ERROR No error / Unknown error Temporary
1 ROUTING ERROR Internal routing error Report to Sinch Permanent
2 ROUTING ERROR Internal routing error Report to Sinch Permanent
3 ROUTING ERROR Internal routing error Report to Sinch Permanent
4 ROUTING ERROR Internal routing error Report to Sinch Temporary
5 ROUTING ERROR Internal routing error Report to Sinch Permanent
6 ROUTING ERROR Internal routing error Report to Sinch Permanent
7 ROUTING ERROR Internal routing error Report to Sinch Permanent
8 ROUTING ERROR Internal routing error Report to Sinch Permanent
9 ROUTING ERROR Unsupported number plan Permanent
10 ROUTING ERROR Unsupported type of number Permanent
11 ROUTING ERROR Message not delivered Permanent
12 ROUTING ERROR Dialing zone not found Permanent
13 ROUTING ERROR Not home zone and IMSI not allowed Permanent
14 ROUTING ERROR Not home zone and IMSI fetch failed Temporary
15 SCREENING ERROR Screening block Permanent
16 SCREENING ERROR Terminating IMSI blocked Permanent
17 ROUTING ERROR Destination network type unknown Permanent
18 ESME ERROR ESME error Temporary
19 SCREENING ERROR Originating location mismatch Permanent Permanent
40 INTERNAL ERROR Internal error Report to Sinch Temporary
50 INTERNAL ERROR Internal error Report to Sinch Temporary
51 INTERNAL ERROR Internal error Report to Sinch Temporary
52 INTERNAL ERROR Internal error Report to Sinch Temporary
53 INTERNAL ERROR Internal error Report to Sinch Permanent
54 INTERNAL ERROR Internal error Report to Sinch Permanent
55 INTERNAL ERROR Internal error Report to Sinch Permanent
56 INTERNAL ERROR Internal error Report to Sinch Temporary
60 SCREENING ERROR Error, originator blocked Permanent
61 SCREENING ERROR Error, destination blocked Permanent
62 SCREENING ERROR Error, keyword blocked Permanent
63 SCREENING ERROR Error, SC address blocked Permanent
64 SCREENING ERROR Error, blocked due to exceeded quota Permanent
65 SCREENING ERROR Error, loop detected Permanent
66 SCREENING ERROR Error, data coding scheme blocked Permanent
67 SCREENING ERROR Error, information element identifier blocked Permanent
70 ESME ERROR Internal error Report to Sinch Temporary
71 ESME ERROR Internal error Report to Sinch Temporary
72 ESME ERROR Internal error Report to Sinch Permanent
73 ESME ERROR Internal error Report to Sinch Temporary
74 ESME ERROR Internal error Report to Sinch Temporary
75 ESME ERROR Internal error Report to Sinch Temporary
76 ESME ERROR Internal error Report to Sinch Temporary
77 ESME ERROR IMSI lookup blocked Permanent
100 SMSC ERROR Unidentified Subscriber Permanent
101 SMSC ERROR Facility not supported Temporary
102 SMSC ERROR System failure Temporary
103 SMSC ERROR Unexpected data value Permanent
104 SMSC ERROR Data missing Permanent
105 SMSC ERROR Equipment protocol error Permanent
106 SMSC ERROR Unknown service centre address Temporary
107 SMSC ERROR Service centre congestion Temporary
108 SMSC ERROR Invalid short message entity address Permanent
109 SMSC ERROR Subscriber not service centre subscriber Temporary
110 SMSC ERROR Reject Indicates temporary problem or lost reach Permanent
111 SMSC ERROR Local Cancel Indicates temporary problem or lost reach Temporary
112 SMSC ERROR Abort Indicates temporary problem or lost reach Temporary
113 SMSC ERROR Exception (internal) Report to Sinch Permanent
114 SMSC ERROR Unknown error Temporary
150 HLR ERROR Unknown subscriber Message is rejected because there is no directory number for the mobile subscriber Permanent
151 HLR ERROR Call barred Message is rejected due to barring of the mobile subscriber Permanent
152 HLR ERROR Teleservice not provisioned Message is rejected because the recipient mobile subscriber has no SMS subscription Permanent
153 HLR ERROR Absent subscriber Temporary
154 HLR ERROR Facility not supported The message is rejected due to no provision of the SMS in the VPLMN Permanent
155 HLR ERROR System failure Message rejected due to network or protocol failure Temporary
156 HLR ERROR Unexpected data value Permanent
157 HLR ERROR Data missing Permanent
158 HLR ERROR Memory capacity exceeded Message rejected because the mobile subscriber doesn’t have enough memory Temporary
159 HLR ERROR Mobile subscriber not reachable Temporary
160 HLR ERROR Reject Indicates temporary problem or lost reach Permanent
161 HLR ERROR Local Cancel Indicates temporary problem or lost reach Temporary
162 HLR ERROR Abort Indicates temporary problem or lost reach Temporary
163 HLR ERROR Exception (internal) Report to Sinch (Local error) Permanent
164 HLR ERROR Unknown error Temporary
200 MSC ERROR Unidentified subscriber Temporary
201 MSC ERROR Absent subscriber, IMSI detached Subscriber is absent and has been for a period of time Temporary
202 MSC ERROR Absent subscriber, no page response The message is rejected because there was no paging response Temporary
203 MSC ERROR Subscriber busy for MT SMS The message is rejected because of congestion encountered at the visited MSC Temporary
204 MSC ERROR Facility not supported The message is rejected due to no provision of the SMS in the destination SIM Permanent
205 MSC ERROR Illegal subscriber Message rejected because of failed authentication Permanent
206 MSC ERROR Illegal equipment Message rejected because the mobile subscriber was blocklisted Permanent
207 MSC ERROR System failure Message rejected due to network or protocol failure Temporary
208 MSC ERROR Unexpected data value Permanent
209 MSC ERROR Data missing Permanent
210 MSC ERROR Memory capacity exceeded Message rejected because the mobile subscriber doesn’t have enough memory Temporary
211 MSC ERROR Equipment protocol error Temporary
212 MSC ERROR Equipment not short message equipped Temporary
213 MSC ERROR Reject Indicates temporary problem or lost reach Permanent
214 MSC ERROR Local Cancel Indicates temporary problem or lost reach Temporary
215 MSC ERROR Abort Indicates temporary problem or lost reach Temporary
216 MSC ERROR Exception (internal) Report to Sinch Permanent
217 MSC ERROR Unknown error Temporary
250 SCREENING ERROR Error, personal service barring, MO Personal De termined Barring White List Permanent
251 SCREENING ERROR Error, personal service barring, MO Personal De termined Barring Black List Permanent
252 SCREENING ERROR Error, personal service barring, MO Operator De termined Barring White List Permanent
253 SCREENING ERROR Error, personal service barring, MO Operator De termined Barring Black List Permanent
254 SCREENING ERROR Error, personal service barring, MT Personal De termined Barring White List Permanent
255 SCREENING ERROR Error, personal service barring, MT Personal De termined Barring Black List Permanent
256 SCREENING ERROR Error, personal service barring, MT Operator De termined Barring White List Permanent
257 SCREENING ERROR Error, personal service barring, MT Operator De termined Barring Black List Permanent
300 ESME EXTERNAL ERROR Invalid destination address Permanent
301 ESME EXTERNAL ERROR Invalid destination numbering plan Permanent
302 ESME EXTERNAL ERROR Invalid destination type of number Permanent
303 ESME EXTERNAL ERROR Invalid destination flag Permanent
304 ESME EXTERNAL ERROR Invalid number of destinations Permanent
310 ESME EXTERNAL ERROR Invalid source address Permanent
311 ESME EXTERNAL ERROR Invalid source numbering plan Permanent
312 ESME EXTERNAL ERROR Invalid source type of number Permanent
320 ESME EXTERNAL ERROR ESME Receiver permanent error Permanent
321 ESME EXTERNAL ERROR ESME Receiver reject error Permanent
322 ESME EXTERNAL ERROR ESME Receiver temporary error
330 ESME EXTERNAL ERROR Invalid command length Permanent
331 ESME EXTERNAL ERROR Invalid service type Permanent
332 ESME EXTERNAL ERROR Invalid operation Permanent
333 ESME EXTERNAL ERROR Operation not allowed Permanent
334 ESME EXTERNAL ERROR Invalid parameter Permanent
335 ESME EXTERNAL ERROR Parameter not allowed Permanent
336 ESME EXTERNAL ERROR Invalid parameter length Permanent
337 ESME EXTERNAL ERROR Invalid optional parameter Permanent
338 ESME EXTERNAL ERROR Optional parameter missing Permanent
339 ESME EXTERNAL ERROR Invalid validity parameter Permanent
340 ESME EXTERNAL ERROR Invalid scheduled delivery parameter Permanent
341 ESME EXTERNAL ERROR Invalid distribution list Permanent
342 ESME EXTERNAL ERROR Invalid message class Permanent
343 ESME EXTERNAL ERROR Invalid message length Permanent
344 ESME EXTERNAL ERROR Invalid message reference Permanent
345 ESME EXTERNAL ERROR Invalid number of messages Permanent
346 ESME EXTERNAL ERROR Invalid predefined message Permanent
347 ESME EXTERNAL ERROR Invalid priority Permanent
348 ESME EXTERNAL ERROR Invalid replace flag Permanent
349 ESME EXTERNAL ERROR Request failed Permanent
350 ESME EXTERNAL ERROR Invalid delivery report request Temporary
360 ESME EXTERNAL ERROR Message queue full Temporary
361 ESME EXTERNAL ERROR External error Report to Sinch Temporary
362 ESME EXTERNAL ERROR External error Report to Sinch Temporary
370 ESME EXTERNAL ERROR Cannot find information Temporary
399 ESME EXTERNAL ERROR Unknown Temporary

SMPP Encoding

Default SMSC encoding

Data Coding
0x00 Default GSM 7 bit encoding
0x01 US-ASCII
0x02 Binary
0x03 ISO8859-1 (Latin-1), only characters within GSM-7 character table can be parsed to handset
0x04 Binary
0x08 UCS2/UTF-16BE
>0xF0 Same as DCS value. See SMPP v3.4 Issue1.2 specification

GSM 7 bit default alphabet and extension table

3GPP TS 23.038 / GSM 03.38

x0 x1 x2 x3 x4 x5 x6 x7 x8 x9 xA xB xC xD xE xF
0x @ £ $ ¥ è é ù ì ò Ç LF Ø ø CR Å å
1x Δ _ Φ Γ Λ Ω Π Ψ Σ Θ Ξ ESC Æ æ ß É
2x SP ! # ¤ % & ( ) * + , - . /
3x 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
4x ¡ A B C D E F G H I J K L M N O
5x P Q R S T U V W X Y Z Ä Ö Ñ Ü §
6x ¿ a b c d e f g h i j k l m n o
7x p q r s t u v w x y z ä ö ñ ü à
1B 0x FF
1B 1x ^
1B 2x { } \
1B 3x [ ~ ]
1B 4x |
1B 5x
1B 6x
1B 7x

ISO/IEC 8859–1 table, Latin-1

ISO/IEC8859-1

x0 x1 x2 x3 x4 x5 x6 x7 x8 x9 xA xB xC xD xE xF
0x
1x
2x SP ! # $ % & ( ) * + , - . /
3x 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
4x @ A B C D E F G H I J K L M N O
5x P Q R S T U V W X Y Z [ \ ] ^ _
6x ` a b c d e f g h i j k l m n o
7x p q r s t u v w x y z { { } ~
8x
9x
Ax NBSP ¡ ¢ £ ¤ ¥ ¦ § ¨ © ª « ¬ SHY ® ¯
Bx ° ± ² ³ ´ µ · ¸ ¹ º » ¼ ½ ¾ ¿
Cx À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï
Dx Ð Ñ Ò Ó Ô Õ Ö × Ø Ù Ú Û Ü Ý Þ ß
Ex à á â ã ä å æ ç è é ê ë ì í î ï
Fx ð ñ ò ó ô õ ö ÷ ø ù ú û ü ý þ ÿ

US-ASCII

x0 x1 x2 x3 x4 x5 x6 x7 x8 x9 xA xB xC xD xE xF
0x LF FF CR
1x ESC
2x SP ! # $ % & ( ) * + , . /
3x 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
4x @ A B C D E F G H I J K L M N O
5x P Q R S T U V W X Y Z [ \ ] ^ _
6x ` a b c d e f g h i j k l m n o
7x p q r s t u v w x y z { | } ~