Ruby-implementation of the SMPP protocol, based on EventMachine.
Clone or download




Ruby-SMPP is a Ruby implementation of the SMPP v3.4 protocol. It is suitable for writing gateway daemons that communicate with SMSCs for sending and receiving SMS messages.

The implementation is based on the Ruby/EventMachine library.

NOTE: Breaking change from 0.1.2 to 0.1.3. See below.

For help please use the Google group here:


  • SMSC: SMS Center. Mobile operators normally operate an SMSC in their network. The SMSC stores and forwards SMS messages.

  • MO: Mobile Originated SMS: originated in a mobile phone, ie. sent by an end user.

  • MT: Mobile Terminated SMS: terminated in a mobile phone, ie. received by an end user.

  • DR: Delivery Report, or delivery notification. When you send an MT message, you should receive a DR after a while.

  • PDU: Protcol Base Unit, the data units that SMPP is comprised of. This implementation does not implement all SMPP PDUs.


The SMPP 3.4 protocol spec can be downloaded here:

Testing/Sample Code

Logica provides an SMPP simulator that you can download from You can also sign up for a demo SMPP account at one of the many bulk-SMS providers out there.

For a quick test, download smscsim.jar and smpp.jar from the Logica site, and start the simulator by typing:

java -cp smscsim.jar:smpp.jar com.logica.smscsim.Simulator

Then type 1 (start simulation), and enter 6000 for port number. The simulator then starts a server socket on a background thread. In another terminal window, start the sample sms gateway from the ruby-smpp/examples directory by typing:

ruby sample_gateway.rb

You will be able to send MT messages from the sample gateway terminal window by typing the message body. In the simulator terminal window you should see SMPP PDUs being sent from the sample gateway.

You can also send MO messages from the simulator to the sample gateway by typing 7 (log to screen off) and then 4 (send message). MO messages received by the sample gateway will be logged to ./sms_gateway.log.


  • Implements only typical client subset of SMPP 3.4 with single-connection Transceiver.

  • Contributors are encouraged to add missing PDUs.


Start the transceiver. Receive delegate callbacks whenever incoming messages or delivery reports arrive. Send messages with Transceiver#send_mt.

# connect to SMSC
tx = EventMachine::run do
  $tx = EventMachine::connect(
  config,             # a property hash
  delegate            # delegate class that will receive callbacks on MOs and DRs and other events

# send a message
tx.send_mt(id, from, to, body)

As of 0.1.3 the delegate method signatures are as follows:

  • mo_received(transceiver, deliver_sm_pdu)

  • delivery_report_received(transceiver, deliver_sm_pdu)

  • message_accepted(transceiver, mt_message_id, submit_sm_response_pdu)

  • message_rejected(transceiver, mt_message_id, submit_sm_response_pdu)

  • bound(transceiver)

  • unbound(transceiver)

Where 'pdu' above is the actual actual instance of the Smpp:Pdu

class created.

For a more complete example, see examples/sample_gateway.rb


  • Eventmachine >= 0.10.0


sudo gem install ruby-smpp


Copyright © 2008 Apparat AS Released under the MIT license.