SMS API | Textbelt

A simple API for outgoing text messages

Textbelt is an SMS gateway API. There are two versions:

Since its creation, Textbelt has sent over 3 million texts from the command line and other software clients!

Send a text message with an HTTP request

Try it now. No client libraries, recurring billing, or account logins:

$ curl -X POST https://textbelt.com/text \
       --data-urlencode phone='5557727420' \
       --data-urlencode message='Hello world' \
       -d key=textbelt
Using the popular requests library:
import requests
requests.post('https://textbelt.com/text', {
  'phone': '5557727420',
  'message': 'Hello world',
  'key': 'textbelt',
})
require 'net/http'
require 'uri'

uri = URI.parse("https://textbelt.com/text")
Net::HTTP.post_form(uri, {
  :phone => '5557727420',
  :message => 'Hello world',
  :key => 'textbelt',
})
Using the popular request library:
var request = require('request');

request.post('https://textbelt.com/text', {
  form: {
    phone: '5555555555',
    message: 'Hello world',
    key: 'textbelt',
  },
}, function(err, httpResponse, body) {
  if (err) {
    console.error('Error:', err);
    return;
  }
  console.log(JSON.parse(body));
})
using System;
using System.Collections.Specialized;
using System.Net;

using (WebClient client = new WebClient())
{
  byte[] response = client.UploadValues("http://textbelt.com/text", new NameValueCollection() {
    { "phone", "5557727420" },
    { "message", "Hello world" },
    { "key", "textbelt" },
  });

  string result = System.Text.Encoding.UTF8.GetString(response);
}
$ch = curl_init('https://textbelt.com/text');
$data = array(
  'phone' => '5557727420',
  'message' => 'Hello world',
  'key' => 'textbelt',
);

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
Using the popular Apache HttpComponents library:
final NameValuePair[] data = {
    new BasicNameValuePair("phone", "5557727420"),
    new BasicNameValuePair("message", "Hello world"),
    new BasicNameValuePair("key", "textbelt")
};
HttpClient httpClient = HttpClients.createMinimal();
HttpPost httpPost = new HttpPost("https://textbelt.com/text");
httpPost.setEntity(new UrlEncodedFormEntity(Arrays.asList(data)));
HttpResponse httpResponse = httpClient.execute(httpPost);

String responseString = EntityUtils.toString(httpResponse.getEntity());
JSONObject response = new JSONObject(responseString);

Use the textbelt key to send an example text. You'll need your own key to send custom messages.

To text internationally, use the E.164 format (+ country code with numbers, no spaces). For example, a Brazilian phone number is +5511912345678 and a UK phone number is +447712345678.

The recipients of your texts should have opted in to receiving your messages. Textbelt shouldn't be used for bulk advertising or spam.

Success and Failure

Example success response:
{sending: true, quotaRemaining: 40, textId: 12345}
Example out-of-quota or invalid key response:
{sending: false, quotaRemaining: 0, error: 'Out of quota'}
Example response to request with phone, message, or key missing:
{sending: false, error: 'Incomplete request'}

Look up text delivery status

Using the textId given by a successful sent text, load /status/<textId>. For example, if your textId is 12345:
$ curl https://textbelt.com/status/12345

{status: 'DELIVERED'}

Possible return values include DELIVERED (received by target number), SENDING (sent to provider but receipt not confirmed), FAILED (not received), and UNKNOWN (could not determine status).

Checking your quota

Use /quota/<key> to view remaining quota. For example, if your key is abc123:
$ curl https://textbelt.com/quota/abc123

{success: true, quotaRemaining: 98}

Testing your key

If you want to validate your key without actually using your text quota, append "_test" to your key and you will receive a response from the /text endpoint confirming that a text would send:
{sending: true, quotaRemaining: 40, textId: -1, inTestMode: true}

Get started

Now you're ready to go. Fill out the form below to generate a key.

Generate a key to send texts

If you already have one, add funds to an existing key.

Get Key

Get in touch

Any questions? Email [email protected], text +1 (650) 332-4607, or read the FAQ.