preston/sms-easy

Allows you to send free SMS messages in a Ruby app using email-to-sms gateways provided by cell carriers.

SMSEasy (sms-easy)

SMSEasy allows you to send SMS messages from your Ruby application for free using email-to-text services provided by many carriers.

This is largely based on Brendan Lim's sms-fu for older apps. (https://github.com/brendanlim/sms-fu) If you're replacing sms-fu, SMSEasy is very similar, but not identical, and does not support legacy versions of activerecord.

Rails 5.2 integration is supported, though not required. Additionally, SMSEasy works perfectly well with background job processing gems such as Sidekiq and delayed_job.

Supported Carriers (US & International):

Alltel, Ameritech, AT&T, Bell Atlantic, BellSouth Mobility, Beeline(UA), BlueSkyFrog, Boost Mobile, BPL Mobile, Cellular South, Claro (Brazil, Nicaragua), Comcast, Du, E-Plus, Etisalat, Fido, kajeet, Mobinil, Mobitel, Movistar, Metro PCS, O2, Orange, Powertel, PSC Wireless, Qwest, Rogers, Southern Link, Sprint, Suncom, T-Mobile (US/UK/Germany), Telefonica, Tracfone, Virgin Mobile, Verizon Wireless, Vodafone (UK, Egypt, Italy, Japan, Spain), and many more ...

Some International carriers require that their users subscribe to an Email to SMS feature before they are able to receive SMS messages this way. If one your users mentions that they are not receiving their messages, chances are it is due to this limitation. Some of these carriers are include, Mobitel, Etisalat, T-Mobile (Netherlands).

Requirements

• SMSEasy requires the use of a recent version of 'action_mailer'. Only action_mailer 5.2+ is supported. If you have an older app, please try one of the older variants that supports action_mailer 3/4 and/or pony email agents.

Setup Instructions

Install the sms-easy gem:

gem install sms-easy

Numbers and Carriers

• You'll need 10-digit phone numbers, stripped of any non-numeric characters.

• As SMSEasy relies on free carrier-specific email-to-SMS gateways, you'll also need to know the carrier of the receiving phone number.

• Here are some of the default carrier values:

  Alltel Wireless => "alltel" AT&T/Cingular => "at&t" Boost Mobile => "boost" Sprint Wireless => "sprint" T-Mobile US => "t-mobile" T-Mobile UK => "t-mobile-uk" Virgin Mobile => "virgin" Verizon Wireless => "verizon" Vodafone Tokyo => "vodafone-jp-tokyo"

• Check sms-easy.yml for a complete list of supported carriers, including international carriers.

Usage

###Basic Rails Configuration

# Override the default "from" address with config/initializers/sms-easy.rb
SMSEasy::Client.config['from_address'] = "[email protected]"

# Or, you can completely copy sms-easy.yml to your app (http://github.com/preston/sms-easy/blob/master/templates/sms-easy.yml), change it to your liking, and override the default configuration with:

SMSEasy::Client.configure(YAML.load(...))

# Your apps existing ActionMailer configuration will be used. :)

# Create the client
easy = SMSEasy::Client.new

# Deliver a simple message.
easy.deliver("5551234567", "verizon", "Hey!")  

Basic Ruby (non-Rails) Use Case (non-Rails)

# SMSEasy will use actionmailer's default configuration, which can be overriden if needed:
ActionMailer::Base.smtp_settings = {
  :address        => 'smtp.example.com',
  # :port           => '587',
  :domain         => 'example.com',
  :enable_starttls_auto => false
}

# Configure SMSEasy's "from" address:
SMSEasy::Client.config['from_address'] = "[email protected]"

# Optionally override the carries list using your own data file.
# SMSEasy::Client.configure(YAML.load(...))

# Create the client
easy = SMSEasy::Client.new

# Deliver a simple message.
easy.deliver("5551234567", "verizon", "Hey!")

# To set a custom from e-mail per SMS message:
easy.deliver("5551234567", "verizon", "Sup.", :from => "[email protected]")

# You can set the maximum length of the SMS message, which is not set by default.  Most phones can only accept 128 characters.  To do this just specify the limit option.

easy.deliver("5551234567", "verizon", "Boo-yaa!", :limit => 128)

# You can retrieve just the formatted address to use in your own mailer.
SMSEasy::Client.sms_address("5558675309","at&t") # => "[email protected]"

View Helpers (Rails)

Include view helpers in application_helper.rb:

module ApplicationHelper
  include SMSEasyHelper
end

Retrieve a collection of all carriers

<%= carrier_collection %>

Display a select box with mobile carriers

<%= carrier_select %>

Display a custom select box with mobile carriers

<%= carrier_select('user[carrier_name]', "Please choose a carrier") %>

Special Thanks

I want to thank the following individuals with their help with adding some patches to SMS Fu:

• Brent Collier (brentmc79)
• Peter Boling (pboling)
• Mike (mic)
• chptung

Copyright (c) 2010 Brendan G. Lim, Intridea, Inc., released under the MIT license

Additional modifications, updates, refactorings etc. by Preston Lee 2013-2017.

sms-easy's Issues

SMSEasyException (Missing number or carrier)

Got it working great in development. In production on heroku, it throws this error:
SMSEasyException (Missing number or carrier)

I'd appreciate any suggestion you might have to help me troubleshoot!
Very new developer here.

Thanks!

Sidekiq? How?

The README says "SMSEasy works perfectly well with background job processing gems such as Sidekiq and delayed_job." But how?

An example on Sidekiq's Delayed Extensions makes me think I should do something like:

sms_sender = SMSEasy::Client.new
sms_sender.delay_until(10.seconds.from_now).deliver('18005551212', 'att, 'Hello world!')

But this results in undefined method 'delay_until' for #<SMSEasy::Client:0x007fcdf42f5598>.

Basically, I've tried every combination of cramming delay_until() wherever I thought I could, but I must be misunderstanding how to queue an SMSeasy delivery.

I should note that I'm a n00b when it comes to Sidekiq. I've been able to use delay_until() for ActionMailer just fine, though.

Cannot require sms-easy gem from a ruby script

Upon attempting to require the sms-easy gem into my ruby script I get the following issues

.rbenv/versions/2.2.3/lib/ruby/gems/2.2.0/gems/sms-easy-1.3.3/lib/sms/easy/easy.rb:5:in class:Client': private method load' called for Psych:Module (NoMethodError)

and this is how I am requiring it

require 'rubygems'
require 'sms-easy'

Any assistance with this is greatly appreciate it

How do you get the carrier?

Hi Preston,

Thanks for writing this gem! I was wondering, how do you get the carrier from a phone (on the javascript side)? Basically, what I want to do is to just ask the user to input their phone number rather than having to input both their phone number and carrier. Is there an example you can point to of using this gem that I could reference?

Thanks!
David

SMS easy does not seem to work with Rails 5.2

I have upgraded rails from 5.0 to 5.2. It appears that SMS-easy fails because rails is looking for a view that does not exist. I added the view just to test what will happen. And then SMS easy was actually trying to send a file.

Can someone please test on Rails 5.2? If not, please let me know how to contribute to this project. Should I create a PR?

carriers

It's more a question than an issue… Is there a way to add a carrier to the current list? I'm looking for others French carriers…