Getting started

Textbelt is an SMS API that is built for developers who just want to send and receive SMS. Sending an SMS is a simple thing. Our goal is to provide an API that is correspondingly simple, without requiring account configuration, logins, or extra recurring billing.

Send an SMS using HTTP POST

The https://textbelt.com/text endpoint accepts a POST request with the following parameters:

  • phone: A phone number. If you're in the U.S. or Canada, you can just send a normal 10-digit phone number with area code. Outside the U.S., it is best to send the phone number in E.164 format with your country code.

  • message: The content of your SMS.

  • key: Your API key (use textbelt to send a free message).

Every programming language has a way to send an HTTP POST request. Instead of installing a special Textbelt library, just send a POST request using your preferred method. Below are some examples in common languages.

Examples

Bash
Python
Ruby
Node
Javascript
PHP
C#
Java
Go
PSH
Bash
curl -X POST https://textbelt.com/text \
--data-urlencode phone='5555555555' \
--data-urlencode message='Hello world' \
-d key=textbelt
Python

Using the popular requests library:

import requests
resp = requests.post('https://textbelt.com/text', {
'phone': '5555555555',
'message': 'Hello world',
'key': 'textbelt',
})
print(resp.json())
Ruby
require 'net/http'
require 'uri'
uri = URI.parse("https://textbelt.com/text")
Net::HTTP.post_form(uri, {
:phone => '5555555555',
:message => 'Hello world',
:key => 'textbelt',
})
Node

Using the popular request or axios libraries:

// Using request
const request = require('request');
request.post('https://textbelt.com/text', {
form: {
phone: '5555555555',
message: 'Hello world',
key: 'textbelt',
},
}, (err, httpResponse, body) => {
console.log(JSON.parse(body));
});
// Using axios
const axios = require('axios');
axios.post('https://textbelt.com/text', {
phone: '5555555555',
message: 'Hello world',
key: 'textbelt',
}).then(response => {
console.log(response.data);
})
Javascript

Using the browser Fetch API and a CORS request:

fetch('https://textbelt.com/text', {
method: 'post',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
phone: '5555555555',
message: 'Hello world',
key: 'textbelt',
}),
}).then(response => {
return response.json();
}).then(data => {
console.log(data);
});
PHP
$ch = curl_init('https://textbelt.com/text');
$data = array(
'phone' => '5555555555',
'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);
C#
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", "5555555555" },
{ "message", "Hello world" },
{ "key", "textbelt" },
});
string result = System.Text.Encoding.UTF8.GetString(response);
}
Java

Using the popular Apache HttpComponents library:

final NameValuePair[] data = {
new BasicNameValuePair("phone", "5555555555"),
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);
Go
import (
"net/http"
"net/url"
)
func main() {
values := url.Values{
"phone": {"5555555555"},
"message": {"Hello world"},
"key": {"textbelt"},
}
http.PostForm("https://textbelt.com/text", values)
}
PSH
$body = @{
"phone"="5555555555"
"message"="Hello World"
"key"="textbelt"
}
$submit = Invoke-WebRequest -Uri https://textbelt.com/text -Body $body -Method Post

Response

The /text endpoint will respond with JSON:

  • success: Whether the message was successfully sent (true/false).

  • quotaRemaining: The amount of credit remaining on your key.

  • textId: The ID of the sent message, used for looking up its status. Only present when success=true. Use this to check SMS delivery status.

  • error: A string describing the problem. Only present when success=false.

An example of a message successfully sent:

{"success": true, "quotaRemaining": 40, "textId": 12345}

Here's an example of when you've run out of quota:

{"success": false, "quotaRemaining": 0, "error": "Out of quota"}

Or when you're missing a required variable such as phone, message, or key:

{"success": false, "error": "Incomplete request"}

If you're getting the above message even though you're specifying the variable, you should make sure that you're sending the request correctly as an HTTP POST request.

Testing this API

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. However, credit will not be deducted from your account.

Receiving SMS replies

U.S. phone numbers only: Textbelt lets you receive replies to SMS you've sent. Replies are sent by webhook, meaning you will have to set up an HTTP or HTTPS route on your website that will process inbound SMS.

Add a replyWebhookUrl parameter to your send message request. This is the same as the examples above, except it includes replyWebhookUrl. For example:

curl -X POST https://textbelt.com/text \
--data-urlencode phone='5555555555' \
--data-urlencode message='Hello?' \
-d replyWebhookUrl='https://my.site/api/handleSmsReply' \
-d key=textbelt

This will send an SMS. If the recipient responds, Textbelt will send an HTTP POST request to the specified endpoint (in this case, https://my.site/api/handleSmsReply).

The reply is application/json encoded. Your server must interpret it like any other HTTP POST request with a JSON payload. The JSON payload contains the following:

  • fromNumber: The phone number of the user that sent the reply (you can use this, for example, to send them a response depending on their reply).

  • text: The content of their reply

Here's an example payload:

{
"fromNumber": "+1555123456",
"text": "Here is my reply"
}

Get an API key

Create an API key to start sending and receiving SMS!