June 17, 2019 · open source

Free SMS API with Textbelt Open Source

"Free SMS API" is a bit of a misnomer.  Services that offer free SMS sending are usually taking a loss in order to give users a "free trial" and charge them afterwards.  These trials tend to be restricted to test phone numbers to deter abuse by spammers.  Examples include Twilio and Plivo.

If you are an engineer trying to find a free SMS service, it is important to understand that every phone network charges money to deliver SMS.  No service is offering free SMS credit without some ulterior motive.

The hosted version of the Textbelt API provides one free SMS per day, which is useful if you want to send SMS only occasionally.

If you just want to send multiple private SMS without paying and without relying on 3rd-party services, there is another approach that may work for you.  Most phone carriers offer email-to-SMS gateways that deliver SMS.  These gateways avoid network charges by sending SMS through email.

The open source version of Textbelt uses these gateways to send SMS for free.  The software itself is available on Github under the permissive MIT license.  Textbelt was developed by Ian Webster in 2012 and uses email-to-SMS gateways to provide a free SMS API.  It includes a library of each carrier's free email/SMS gateways and uses them to deliver SMS.

There are caveats.  Gateways are not always reliable and emails are not always accepted by carriers.  However, if you host your own email and configure the Textbelt nodemailer  to use your own email solution (a private server or a service like Mailgun or Sendgrid), you should be able to deliver most of your SMS.  In general, you'll have less control over your SMS because some carriers will append notes like "sent via Email" to your message.  Note that there are a few minor carriers (such as Google Fi) that do not offer email-to-SMS gateways.

After setting up your Textbelt server, you can send SMS with a simple POST request:

curl -X POST http://my_textbelt_server/text \
   --data-urlencode number=5551234567 \
   --data-urlencode "message=I sent this message for free with Textbelt"

This example would look through the list of U.S. carriers and dispatch an SMS (via email gateway) to all relevant carriers.

Here's the same example in Python:

import requests
requests.post('https://textbelt.com/text', {
  'phone': '5551234567',
  'message': 'I sent this message for free with Textbelt',
})

SMS deliverability can be a challenge even for paid providers.  If you want assurance of SMS delivery or a way to check whether your message was delivered, you'll wind up having to pay the carriers.

Textbelt.com used to host this free SMS API, but after 5 years it was overrun by spammers, so now we've just provided the code online so anyone can set up their own private instance.  

There is a new paid offering for people who needed greater assurance of delivery versus the open-source free approach.  The API request is the same, except you provide a key parameter and you can use the textbelt.com endpoint:

curl -X POST https://textbelt.com/text \
   --data-urlencode number=5551234567 \
   --data-urlencode "message=I sent this message for free with Textbelt" \
   -d key=textbelt

Please reach out if you have any questions, whether about setting up the free Textbelt SMS API or using the paid version!