SMPP Tangerine

Previous versions: SMPP Citron.

SMPP is an industry standard for sending and receiving SMSs. SMPP Tangerine is the current version of our high performance SMPP server, available to high volume customers on request. Please contact Support to enable this feature on your account.

Authentication

Ensure that your account password is no longer than 8 characters, to maintain compatibility with the SMPP specification.

Capabilities & Limitations

Binding

  • SMPP v3.4, including transmitter, receiver and transceiver bind operation
  • Both Asynchronous and synchronous mode are supported
  • Multiple concurrent connections for the same user are supported, and can be organised into groups
  1. SMPP access is only enabled on request and subject to certain conditions. Please contact us for more information on enabling access. Once this is done:
  2. Our SMPP service is available at smpp.bulksms.com on port 2775 (with TLS support on port 3550);
  3. Your system-ID will have been supplied by BulkSMS Support. It will be an integer (numeric), e.g. 200012345, and not your BulkSMS.com username;
  4. Your SMPP password is your normal BulkSMS password, but SMPP requires this password to be no longer than 8 characters. If your password is longer than 8 characters, please change your BulkSMS.com account to a shorter password before attempting to connect using SMPP. This is a technical limitation in the SMPP protocol standard.

Vendor-specific status codes

status code
UNKNOWN_STATUS 0x400
INVALID_MESSAGE_BODY 0x401

Vendor-specific optional parameters (TLV)

Linked MT SMS ID

If a deliver_sm contains an MO SMS which is in reply to a previously sent MT SMS, this optional parameter will be set to the message_id that was originally returned in the submit_sm_resp when the MT SMS was accepted.

Tag code 0x1400
Value data type C-Octet String (null-terminated)
Value Length variable

Mobile Terminating (MT) messages

  • Message encodings supported for single-part messages
    • 7-bit (text)
    • 8-bit (binary)
    • 16-bit (Unicode)
  • Message encodings supported for multipart-part (concatenated) messages (UDH concat only)
    • 7-bit (text)
    • 8-bit (binary)
    • 16-bit (Unicode)
  • Concatenated 7-bit and 16-bit messages to a given recipient are only delivered once all their parts are received.
  • The routing group can be selected using the service_type field. As per the SMPP 3.4 specification, this is a C-octet string, so for the three routing options, the value can be a literal string containing one of “1”, “2” or “3”. If unspecified or invalid, routing group 2 will be used.
  • Repliability is not settable on a per-message basis, but can be set as a global option on your account, if this is supported in your region. Please see your profile page on our web site for the “Default repliable” setting.
  • network_id as supported by some of our other APIs is currently not supported on our SMPP API.
  • Message scheduling is not supported
  • The following SUBMIT_SM limitations apply:
    • priority_flag is limited to the default setting
    • schedule_delivery_time is limited to the default setting
    • validity_period: maximum 21 days after submission time, but destination networks are likely to impose their own, more restrictive limits
    • replace_if_present_flag is limited to the default setting
    • sm_default_msg_id is limited to the default setting
    • registered_delivery supports:
      • 0x00 (no status reports)
      • 0x01 (final delivery status outcome of “success” or “failure”)
      • Other values will be interpreted as 0x01
    • user_message_reference is not currently used but may be used in the future, e.g. to allow customers to implement message duplication avoidance strategies
    • Any other optional parameters not mentioned here are generally ignored
  • source TON 0x05 (alphanumeric TON)
  • source NPI 0x00 (Unknown NPI)
  • source address alphanumeric or shortcode - must have been approved for the account per our standard procedure
  • source TON 0x01 (International TON)
  • source NPI 0x01 (ISDN NPI)
  • source address empty, or numeric in E.164 format (see validation rules below) The source address will normally be ignored and replaced with a number from a BulkSMS reply number pool, unless special arrangement are in place for customer-specified source numbers.
  • destination TON 0x01 (International TON)
  • destination NPI 0x01 (ISDN NPI)
  • destination address must be valid in E.164 format (see validation rules below)

E.164 format validation:

  • all digits (no leading “+” character)
  • no leading “0” digit
  • length: between 3 and 15 digits, inclusive

Mobile Originating (MO) messages

  • Once your account has been enabled for SMPP, all Mobile Originating (MO) SMSs are sent to your SMPP bind (even those MO SMSs that may be in reply to messages sent via other APIs).
  • Message encodings supported for single-part and multipart-part (concatenated) messages:
    • 7-bit (text)
    • 8-bit (binary)
    • 16-bit (Unicode)_

Limitations

  • Operations that are not supported at all include: SUBMIT_MULTI, DATA_SM, QUERY_SM, CANCEL_SM, ALERT_NOTIFICATION.
  • Transient status reports are not relayed
  • The ESME (SMPP client) is expected to either respond to LINK_ENQUIRE within 60 seconds, or issue its own LINK_ENQUIRE regularly (every 30 seconds recommended), failing which, the session will be dropped.

  • The BulkSMS SMSC will rate-limit received PDUs at 40 per second. Bursting above this rate into a limited-size buffer can occur but once the buffer is full, PDUs will initially be rejected with an ESME_RTHROTTLED (0x58) status. If the ESME persists in sending at an excessive rate, ignoring throttling responses, PDUs will be dropped without a response. At very high excessive rates, the session may be dropped completely.

  • Common strategies that an ESME (SMPP client) could use for dealing with the above rate-limiting measures include, in descending order of preference:
    • Waiting at least 25 milliseconds (0.025 seconds, being 1 divided by the rate limit of 40) between PDUs;
    • Limiting the number of outstanding requests, such that if too many requests are still awaiting response, no further PDUs are sent until responses arrive, reducing the number of outstanding requests, or the outstanding requests reach a timeout of e.g. 60 seconds. We recommend a maximum outstanding request count of no more than 20;
    • Suspending all sending for a couple of seconds on receipt of an ESME_RTHROTTLED (0x58) status.
  • Please contact us if you require a sustained sending rate above this limit.

Delivery Receipts

Status via SMPP Optional Parameters

The optional parameters message_state and receipted_message_id are available in deliver_sm PDUs.

Status via deliver_sm Body

Delivery Receipts are also available via the short_message parameter in deliver_sm PDUs. The format is based on the example format in Appendix B of the SMPP specification (which, while just an example in the specification, is widely in use). An example:

id:ab021099504969 stat:DELIVRD err:000 sub:001 dlvrd:001 submit date:1704181518 done date:0101010101 text:...
  • The only delivery receipts that are sent to your SMPP binds, are those produced from Mobile Terminating (MT) SMSs that were received via SMPP. You will not receive delivery reports for MT SMSs that were submitted via other APIs.
  • submit date and done date are in the UTC time zone.
  • done date is currently not available for many countries/networks. If unavailable, the field will be set to 0101010101.
  • text is currently always set to ....
  • err: the numeric values used are:
    • DELIVERED = 000
    • INSUFFICIENT_CREDITS = 025
    • INSUFFICIENT_QUOTA = 027
    • UNROUTABLE = 031
    • BLOCKED_TO_RECIPIENT = 032
    • BLOCKED_ABUSE = 034
    • FAILED = 050
    • FAILED_EXPIRED = 053
    • HANDSET_ERROR = 057
    • UNKNOWN = 070
  • INSUFFICIENT_CREDITS and INSUFFICIENT_QUOTA produce a delivery receipt with:
    • the optional parameter message_state set to 8 (REJECTED) (see SMPP spec §5.2.28);
    • a deliver_sm body which includes stat:REJECTD.

Bind Groups

Advanced usage: for the typical use case you can ignore this feature.

Multiple concurrent binds for the same account are enabled through the use of bind groups. This allows a customer, for example, to have two transmitter binds connected, with MOs and status reports received via a single third receiver bind. The scheme employed allows for various permutations and is controlled by the customer without intervention by BulkSMS.

Binds are grouped by SMPP system type specified by the ESME when binding. Typical ESME system types normally seen are “Logica”, “VMS” and “OTA”. This system type normally has no effect on the operation; the SMPP 3.4 specification describes it as used to “categorize the type of ESME”. In our implementation, the customer can optionally specify a system type that is a numeric string (with supported values from 0 to 99), to indicate which “bind group” this bind should fall under. All transmitter, receiver and transceiver binds using the same numeric system type are seen to form a single “bind group”. Status reports for messages received from transmitters in each bind group will be sent to receiver binds in that same bind group. Note that we limit the number of concurrent connections per user account, across all that user’s bind groups. The limit is currently set at 10; please contact us if this is a problem.

Example 1

For example, you have four transmitter binds (we’ll arbitrarily call them A, B, C and D) and two receiver binds (E and F), organised like this:

  1. transmitter A - system type “0”
  2. transmitter B - system type “0”
  3. transmitter C - system type “1”
  4. transmitter D - system type “1”
  5. receiver E - system type “0”
  6. receiver F - system type “1”

Delivery reports for messages received on A and B (bind group “0”) will be sent to E, because that is the receiver that is also in bind group “0”. Similarly, reports for messages from C and D will be sent to F. You can have as many bind groups as you need, but the system will limit the number of concurrent SMPP connections in total. You should, however, have at least one transmitter and one receiver/transceiver for each group. Transceivers are also supported, so a single transceiver bind is perfectly acceptable and is the most common configuration.

Any Mobile Originating (MO) messages routed to an SMPP user will always be sent to the “0” bind group, so users should at least have one receiver or transceiver bind in bind group “0”, or MO messages will queue until the system expires them.

Any bind which specifies a system type that is NOT numeric, e.g. “ABCDE”, or “Logica” will be treated as if it specified “0”. The same applies for a bind that doesn’t specify a system type (uses null). The effect of this is that customers who only need a single bind group (the most common case) can use their system’s default settings and their connections will be in group “0”, where it will receive any MO messages as well as all status reports.

A transceiver bind can serve the function of either a transmitter or receiver bind, or both. Consider the following example:

Example 2

  1. transmitter A - system type “0”
  2. transmitter B - system type “1”
  3. transceiver C - system type “0”
  4. transceiver D - system type “1”

In this example, all four binds are able to send mobile terminating (MT) messages, but only binds C and D can receive status reports (additionally, bind C can also receive MO messages). Status reports for messages sent via transmitter A as well as transceiver C will be sent to the only suitably-capable bind in bind group “0”, which is transceiver C. Status reports for B and D will be sent to D.

Limitations

The system currently only supports routing MO messages and status reports to one connection per bind group at a time, being the connection to bind and join the bind group last. As a result, load balancing of status reports or MO messages for the same bind group over more than one connection in parallel is currently not supported. Since MO messages are always sent to bind group 0, this means there can currently only be one active bind receiving MOs for a customer at any point in time.

For example, referring to the configuration used in example 1 above, again:

  1. transmitter A - system type “0”
  2. transmitter B - system type “0”
  3. transmitter C - system type “1”
  4. transmitter D - system type “1”
  5. receiver E - system type “0”
  6. receiver F - system type “1”

If an additional receiver “G” now connects after the above binds are connected and specifies system type / bind group “0”, then it will replace receiver E’s role and E will stop receiving status reports for group “0” as well as all MO messages. Any further status reports and MOs will now be sent to receiver G instead. Bind group “1” will be unaffected. If receiver E then disconnects and reconnects, still using group “0”, it once again becomes the receiver bind to most recently join group “0”, so status reports and MOs once again revert to E and bind G will no longer receive them.