SMPP specifications

The Short Message Peer to Peer Protocol (SMPP) is the de-facto standard for SMS sending and receiving for telecommunication operators, SMS aggregators and network operators to exchange SMS messages between Short Message Service Centers (SMSC) and/or External Short Messaging Entities (ESME). SMPP is a level-7 TCP/IP protocol that enables SMS messages to be sent quickly.

The connection between the application and the seven.io SMPP server is SMPP version 3.4 - versions 3.3 or 5.0 are not supported.

SMPP Version 3.4 Issue 1.2 Specifications

You can create an SMPP access yourself in the dashboard under Developer > API access.

Host and port

Each of our SMPP servers allows you the regular connection (plaintext) or an encrypted connection via TLS. If you need a tunneled connection via VPN, please contact us.

HostnamePortTLS Port
smpp0.seven.io27752776

Supported PDUs

The following Packet Data Units (PDU) are supported:

  • bind_transmitter
  • bind_receiver
  • bind_transceiver
  • unbind
  • submit_sm
  • deliver_sm
  • enquire_link

Bind and throughput

Depending on the configuration of your SMPP access, several binds are possible. By default, we allow a maximum connection of 2 sessions and 5 SMS/s per session.

You have three options for establishing a connection via SMPP. To be able to receive status reports, you must set up a bind as transceiver or receiver.

  • transmitter - send short messages to the SMSC and receive replies from the SMSC
  • receiver - receive status reports from the SMSC and return the corresponding replies
  • transceiver - send and receive messages to and from the SMSC via a single SMPP session

Bind Parameter

An SMPP bind_receiver, bind_transceiver or bind_transmitter PDU request has a fixed set of fields. Some fields are irrelevant or are ignored by our server.

  • Name
    system_id
    Type
    string
    Description

    Username - will be provided to you

  • Name
    password
    Type
    string
    Description

    Password - will be provided to you

  • Name
    system_type
    Type
    string
    Description

    Will be ignored

  • Name
    interface_version date
    Type
    timestamp
    Description

    3.4

  • Name
    addr_ton
    Type
    timestamp
    Description

    Will be ignored

  • Name
    addr_npi
    Type
    timestamp
    Description

    Will be ignored

  • Name
    address_range
    Type
    string
    Description

    Will be ignored

Status reports

SMPP status reports are sent in the following format:

  • Name
    id
    Type
    string
    Description

    The ID of the message assigned by our server

  • Name
    sub
    Type
    string
    Description

    The number of SMS originally sent

  • Name
    dlvrd
    Type
    string
    Description

    The number of SMS delivered

  • Name
    submit date
    Type
    timestamp
    Description

    Date and time when the SMS was originally sent

  • Name
    done date
    Type
    timestamp
    Description

    Date and time of the final status report username.

  • Name
    stat
    Type
    string
    Description

    Final status report of the SMS. See table below.

  • Name
    err
    Type
    integer
    Description

    If necessary, this may contain a network-specific error code or an SMSC error code.

  • Name
    text
    Type
    timestamp
    Description

    The first 20 characters of the short message

Example status report

id:c0296bc5-e4d2-4ed7-bcc9-9e9b502dd302
sub:001
dlvrd:001
submit date:221206094424
done date:22106094426
stat:DELIVRD
err:000
text:

Example status report

    id:IIIIIIIIII sub:SSS dlvrd:DDD submit date:YYMMDDhhmm
    done date:YYMMDDhhmm stat:DDDDDDD err:E text:
For load balancing purposes, the status reports may not be sent to the same bind that sent the SMS, but to the bind that currently has the least traffic. Please take this into account when implementing status reports if you are using multiple binds.

Status codes

DLRDescription
DELIVRDMessage has been delivered to destination
ACCEPTDMessage accepted by SMSC
EXPIREDSMS validity period expired
DELETEDMessage has been deleted
UNDELIVMessage could not be delivered
UNKNOWNStatus of SMS unknown
REJECTDMessage was rejected

Error codes

DecHexError codeDescription
00x000000ESME_ROKOk - Message accepted
10x000001ESME_RINVMSGLENInvalid message length
20x000002ESME_RINVCMDLENInvalid command length
30x000003ESME_RINVCMDIDInvalid Command ID
40x000004ESME_RINVBNDSTSInvalid bind status
50x000005ESME_RALYBNDBind attempt if already bound
60x000006ESME_RINVPRTFLGInvalid priority flag
70x000007ESME_RINVREGDLVFLGInvalid registered-delivery flag
80x000008ESME_RSYSERRSMSC System Error
100x00000aESME_RINVSRCADRInvalid source address
110x00000bESME_RINVDSTADRInvalid destination address
120x00000cESME_RINVMSGIDInvalid message-id
130x00000dESME_RBINDFAILGeneral bind error
140x00000eESME_RINVPASWDInvalid password
150x00000fESME_RINVSYSIDInvalid system ID
170x0000011ESME_RCANCELFAILAbort error
190x0000013ESME_RREPLACEFAILReplace error
200x0000014ESME_RMSGQFULToo many messages in the queue
220x0000016ESME_RINVSERTYPInvalid services type
510x0000033ESME_RINVNUMDESTSInvalid destination address number
520x0000034ESME_RINVDLNAMEInvalid name
640x0000040ESME_RINVDESTFLAGInvalid destination flag option
660x0000042ESME_RINVSUBREPInvalid who for submit with replace option
670x0000043ESME_RINVESMCLASSInvalid value for esm_class field
680x0000044ESME_RCNTSUBDLCannot send to a distribution list
690x0000045ESME_RSUBMITFAILGeneral transmission error
720x0000048ESME_RINVSRCTONInvalid type of source number
730x0000049ESME_RINVSRCNPIInvalid flag for the numbering plan of the source
740x000004aESME_RINVDSTTONInvalid type of number for the destination
750x000004bESME_RINVDSTNPIInvalid flag for the numbering plan of the destination address
770x000004dESME_RINVSYSTYPInvalid esm type
780x000004eESME_RINVREPFLAGInvalid submit with replace flag option
850x0000055ESME_RINVNUMMSGSInvalid number of messages
880x0000058ESME_RtdROTTLEDSMSC throttles incoming messages
980x0000062ESME_RINVEXPIRYInvalid validity date
1030x0000067ESME_RQUERYFAILquery_sm request failed
1940x00000c2ESME_RINVPARLENInvalid parameter length
1950x00000c3ESME_RMISSINGOPTPARAMMissing optional parameters
1960x00000c4ESME_RINVOPTPARAMVALInvalid optional parameter value
2540x00000feESME_RDELIVERYFAILUREGeneric delivery error
2550x00000ffESME_RUNKNOWNERRUnknown error

Specific error codes

In addition to the standardized SMPP error codes, we send our own specific error codes:

DecHexError CodeDescription
10350x0000040bESME_RINVBALANCECredit not sufficient to send the SMS
Last updated: 4 minutes ago