Integrating SMS services into RubyOnRails applications using BulkSMS gateway
Pull request Compare This branch is 10 commits ahead of Shuntyard:master.
Latest commit 3221a84 Apr 14, 2014 @samlown Merge pull request #2 from sjkatz/master
Iconv and Ruby 2.0 compatibility.



BulkSMS is a Ruby library that allows you to easily integrate SMS services into your Ruby or Ruby on Rails applications.

It has support for all BulkSMS international sites, including the UK, USA, South Africa, Spain and Europe.

To use the library, you will need an account from and some credits.


Simply set using the configuration object provided by the Bulksms module:

Bulksms.config do |config|
  config.username = 'testuser'
  config.password = 'zepass' = :uk

If Rails is available, the library can be configured using the standard environment configs:

SomeRails::Application.configure do

  # set config in one go
  config.bulksms do |c|
    c.username = 'testuser'
    c.password = 'zepass'

  # single config options = :es



Sending a quick message is very simple:

Bulksms.deliver(:message => 'Hello, I hope you like my message!', :recipient => '44799123456')

Multiple messages

Provide an array of hashes and multiple messages will be sent via the same HTTP connection:

Bulksms.deliver([{:message => 'Test Message', :recipient => "44342134131"}, {:message => "Another Msg", :recipient => "4441234354254"}])

Additional message options

If you prefer more control, the Service and Message objects are also available for direct usage:

s =
m = => "Test Message", :recipient => "34901123123")
m.routing_group = 1
m.want_report = 1


All messages will be converted to ISO-8859-15 before being sent to the Bulksms servers. Some special characters, including the euro symbol, will be converted and prepended with a special escape character, suitable for GSM-7, so that they will be received correctly. For more details on character encoding, checkout the Bulksms API:

Checking your account balance

Use the main module to request the current user's balance:


A Bulksms::AccountError will be raised if there is a problem.


This library currently only implements a small portion of the API, allowing you to send messages and check your account balance. Further parts of the BulkSMS API may be implemented in the future such as the ability to receive messages and status reports and manage the address book provided by BulkSMS.


Rspec from the console:

rspec spec

Tests still need a bit more work to cover all cases.


The Original work on “ruby-bulksms” was made by Luke Redpath ( Modifications were added by Basayel Said (

The latest version, “bulksms”, with a simpler interface, rspec testing, and an easier configuration was written by Sam Lown (

Modifications include:

  • simple helper module for direct access to classes

  • DRYer support libraries

  • Railtie support for configuration

  • Encoding messages correctly