SMPP Citron

This version is deprecated - please see the latest version here. See also: upgrading.


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

Capabilities & Limitations


  • 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. BulkSMS Support will have supplied you with the correct SMPP server name to use, e.g. or Please confirm that you’re connecting to the correct server;
  3. Our SMPP service is on port 2775;
  4. Your system-ID will have been supplied by BulkSMS Support. It will be an integer (numeric) and not your username;
  5. 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 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

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
    • 7-bit (text) only; UDH concat only
  • Only class 2 is supported, so flash SMS is unsupported
  • 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 and protocol_id as supported by our EAPI are currently not supported on our SMPP interface.
  • Message scheduling is not supported
  • The following SUBMIT_SM limitations apply:
    • protocol_id is limited to the default setting
    • 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

  • message encodings supported for single-part messages
    • 7-bit (text), except Greek characters and extended GSM characters
  • message encodings supported for multipart-part (concatenated) messages: none as yet


  • 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.

Bind Groups

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 (up to 13 characters in length), 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 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.


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. This limitation may be addressed in the future, based on demand.

Status Reports

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

Status reports 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. An example:

id:ab021099504969 stat:DELIVRD err:000 sub:001 dlvrd:001 submit date:1704181518 done date:0101010101 text:...
  • err: the numeric values used are the same as for the EAPI status reports see listing here, zero-padded to three digits. For stat:DELIVRD, err will be set to 000.
  • submit date and done date are in the time zone GMT+2.
  • 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 ....