Sms on Rails provides your app with instant SMS integration
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.



Sms on Rails provides an interface and ORM framework for sending and storing SMS messages through Email Gateway or with Clickatell HTTPS

The models and underlying architecture extend and include a ton of modules and are designed to be configured if necessary. If you do not wish to run the vanilla configuration, copy the vendor/plugins/sms_on_rails/lib/models to your local models directory or copy vendor/plugins/sms_on_rails/lib/service_providers to lib/service_providers.

A lot of care has gone into the locking mechanism to prevent double sends. This is a precursor to mass Smsing machine. Further detailed configuration is necessary. Contact if you love grapes.


Install Gem

Add to environment.rb

config.gem 'smsonrails', :source  => ''
config.gem 'clickatell' #If using Clickatell

Vendor the Gem

rake gems:install
rake gems:unpack

Quick Setup (after Install)

script/generate sms_on_rails setup --default-service-provider=[provider]

rake gems:install or rake gems:unpack (if using Clickatell)

rake db:migrate

Alternate Install

Directly Install Gem

gem sources -a
sudo gem install blythedunham-sms_on_rails


script/plugin install git://

Edit SMS configuration details in config/environment.rb. Sign up for clickatell at and/or update your mail settings for use with the email gateways.

Example Setup

The following creates a new rails project dog and adds the Sms On Rails plugin. As seen at RailsConf2009

rails dog --database=mysql
mysqladmin -uroot create dog_development
cd dog
script/plugin install git://
script/generate sms_on_rails setup --default-service-provider=clickatell
rake db:migrate
mate config/environment.rb

Run Setup Generator

script/generate sms_on_rails setup --default-service-provider=[provider]

Running the generator performs several setup steps:

  • copy image and stylesheet assets to your public directory

  • generates 3 database migrations (the 2nd and 3rd have a 2 and 3 appended)

  • installs clickatell gem and static_record_cache plugin (for email carriers caching)

  • insert configuration skeleton into environment.rb


Three files are created with different timestamps in db/migrate

  • Email Carrier information (email addresses for each carrier like

  • Phone Number setup.

  • Draft and Outbound tables

Check them out and then run:

rake db:migrate

Configure settings

After running the generator, open up config/environment.rb in your rails application. Update the configuration hash maps, added by the generator, with your settings.

  • email gateways - SmsOnRails::ServiceProviders::EmailGateway.config. Standard ActionMailer configuration is required for the Email Gateway.

  • clickatell http - SmsOnRails::ServiceProviders::Clickatell.config. Sign up for an account at

Ensure that the correct default provider is selected. Should be :email_gateway or :clickatell

SmsOnRails::ServiceProviders::Base.set_default_service_provider :clickatell

Also make sure that the correct default provider is selected.

Added to environment.rb

SmsOnRails::ServiceProviders::Clickatell.config = {
  :api_id => 'api_key',
  :user_name => 'user_name',
  :password => 'password'

SmsOnRails::ServiceProviders::EmailGateway.config = {
  :sender => 'youremail address',
  :subject => 'Default Subject Text'
  #:bcc => nil,
  #:mailer_klass => nil,

SmsOnRails::ServiceProviders::Base.set_default_service_provider = :email_gateway

Avoiding Collisions with existing PhoneNumber class

If you already have a PhoneNumber ActiveRecord class and phone_number database table, you might experience a collision with the SMSOnRails engine. To avoid this, the generator will take the following measures.

PhoneNumber Migration

Instead of creating a new table, the phone number migration created by the generator will add only the columns needed by SMSOnRails. Please make sure to check out the migration for errors.

PhoneNumber ActiveRecord Class Changes

The generator will update PhoneNumber and add SmsOnRails::PhoneNumber

PhoneNumber app/models/sms_on_rails/phone_number.rb This file is added and used to point SmsOnRails::PhoneNumber point to PhoneNumber

PhoneNumber app/models/phone_number.rb The following two modules are included on your PhoneNumber class:

  • SmsOnRails::ModelSupport::PhoneNumber - basic functionality

  • SmsOnRails::ModelSupport::PhoneNumberAssociations - associations for PhoneNumber

These modules are defined in:


Please manually modify your PhoneNumber class to change the associations if you must.


You will need to configure ActionMailer in environment.rb if you wish to use the Email Gateway. Refer to the Troubleshooting section for more information.

By default, SmsMailer inherits the ActionMailer settings. If your SMS Mailer settings differ from the default ActionMailer settings, you can define the new settings in enviroment.rb with:

SmsOnRails::ServiceProviders::EmailGatewaySupport::SmsMailer.smtp_settings ={}

Default SMS Routes

Default Links in Your Application

Send Messages

Access Service Providers Directly

All service providers are singletons and can be accessed by their instance

To send a message without validation use send_message

SmsOnRails::ServiceProviders::<Provider>.instance.send_message '12065551234', 'my message', options

To send a message with validation use send_to_phone_number with a string or SmsOnRails::PhoneNumber instance

 SmsOnRails::ServiceProviders<Provider>.instance.send_to_phone_number(number, message, options)

To send an sms (+Outbound+) (with validation)
 SmsOnRails::ServiceProviders<Provider>.instance.send_sms(sms, options)
However, it is preferred to use the locking mechanism to prevent double messages from being sent

ORM examples:

Clickatell does not need a carrier

SmsOnRails::Outbound.create_sms 'Send this test message', '11234567890', :send_immediately => true

Email gateway needs a carrier specified

sms = SmsOnRails::Outbound.create_sms 'Send this test message', '12065551234',  :carrier => :att



Install Clickatell gem If you are using clickatell, please install the clickatell gem with either command:

sudo rake gems:unpack
sudo rake gems:install
sudo gem install clickatell

Possible Error messages:

  • Missing these required gems: clickatell

  • Cannot set default provider to clickatell. Check that support for clickatell exists.

Email Gateway

ActionMailer If you are using the email gateways, make sure that your ActionMailer settings are configured properly in environment.rb. A good test is to send a normal email.

You can also test your settings by adding the line below to your environment.rb file.

ActionMailer::Base.delivery_method = :test

The message should be print to the log file log/development.rb like below:

Subject: Default Subject Text
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8

This is my test message




This is MartiniWare. Buy yourself a martini if you like this software! If you like any software that uses this plugin you should also buy yourself a martini. Manhattans are ok too.

Copyright © 2009 Blythe Dunham, released under the MIT license