Getting Started

httpSMS is an open-source service that converts your Android phone into an SMS Gateway so you can send and receive SMS messages using an intuitive HTTP API with support for end-to-end encryption.

Authentication

API requests to httpSMS are authenticated using API keys in the x-api-key header. Any request that doesn't include an API key will return a 401 (Unauthorized) response.

You can get your API key from the dashboard at https://httpsms.com/settings

Install the Android App

To send and receive SMS messages using your android phone, you will need to download and install our android app on your phone so it can be triggered to send an SMS message when you make a request to the HTTP SMS API.

Android App 👉 https://github.com/NdoleStudio/httpsms/releases/latest/download/HttpSms.apk

Send an SMS

To send an SMS message using an android phone, send an authenticated POST request to the https://api.httpsms.com/v1/messages/send endpoint.

Send a new SMS message

Add a new SMS message to be sent by the android phone

POSThttps://api.httpsms.com/v1/messages/send

Authorization

ApiKeyAuth

Body

application/json

PostSend message request payload

contentstring

Example: "This is a sample text message"

encryptedboolean

Encrypted is used to determine if the content is end-to-end encrypted. Make sure to set the encryption key on the httpSMS mobile app

Example: false

fromstring

Example: "[phone]"

request_idstring

RequestID is an optional parameter used to track a request from the client's perspective

Example: "153554b5-ae44-44a0-8f4f-7bbac5657ad4"

send_atstring

SendAt is an optional parameter used to schedule a message to be sent at a later time

Example: "2022-06-05T14:26:09.527976+03:00"

tostring

Example: "[phone]"

Response

200400401422500

OK

Body

application/json

dataentities.Message (object)

messagestring

Example: "item created successfully"

statusstring

Example: "success"

Request

JavaScriptCurlPython

const response = await fetch('https://api.httpsms.com/v1/messages/send', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400401422500

{
  "data": {
    "can_be_polled": false,
    "contact": "[phone]",
    "content": "This is a sample text message",
    "created_at": "2022-06-05T14:26:02.302718+03:00",
    "delivered_at": "2022-06-05T14:26:09.527976+03:00",
    "encrypted": false,
    "expired_at": "2022-06-05T14:26:09.527976+03:00",
    "failed_at": "2022-06-05T14:26:09.527976+03:00",
    "failure_reason": "UNKNOWN",
    "id": "32343a19-da5e-4b1b-a767-3298a73703cb",
    "last_attempted_at": "2022-06-05T14:26:09.527976+03:00",
    "max_send_attempts": 1,
    "order_timestamp": "2022-06-05T14:26:09.527976+03:00",
    "owner": "[phone]",
    "received_at": "2022-06-05T14:26:09.527976+03:00",
    "request_id": "153554b5-ae44-44a0-8f4f-7bbac5657ad4",
    "request_received_at": "2022-06-05T14:26:01.520828+03:00",
    "scheduled_at": "2022-06-05T14:26:09.527976+03:00",
    "scheduled_send_time": "2022-06-05T14:26:09.527976+03:00",
    "send_attempt_count": 0,
    "send_time": 133414,
    "sent_at": "2022-06-05T14:26:09.527976+03:00",
    "sim": "DEFAULT",
    "status": "pending",
    "type": "mobile-terminated",
    "updated_at": "2022-06-05T14:26:10.303278+03:00",
    "user_id": "WB7DRDWrJZRGbYrv2CKGkqbzvqdC"
  },
  "message": "item created successfully",
  "status": "success"
}

PHP

// initialize guzzle client https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client();

$apiKey = "Get API Key from https://httpsms.com/settings";

$res = $client->request('POST', 'https://api.httpsms.com/v1/messages/send', [
  'headers' => [
    'x-api-key' => $apiKey,
  ],
  'json'    => [
    'content' => 'This is a sample text message',
    'from'    => "[phone]",
    'to'      => '[phone]'
  ]
]);

echo $res->getBody(); 

Javascript

let apiKey = "Get API Key from https://httpsms.com/settings";

fetch('https://api.httpsms.com/v1/messages/send', {
    method: 'POST',
    headers: {
        'x-api-key': apiKey,
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "content": "This is a sample text message",
        "from": "[phone]",
        "to": "[phone]"
    })
})
.then(res => res.json())
.then((data) => console.log(data));

Python

import requests
import json

api_key = "Get API Key from https://httpsms.com/settings"

url = 'https://api.httpsms.com/v1/messages/send'

headers = {
    'x-api-key': api_key,
    'Accept': 'application/json',
    'Content-Type': 'application/json'
}

payload = {
    "content": "This is a sample text message",
    "from": "[phone]",
    "to": "[phone]"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))

print(response.json())

curl

curl --location --request POST 'https://api.httpsms.com/v1/messages/send' \
--header 'x-api-key: Get API Key from https://httpsms.com/settings' \
--header 'Content-Type: application/json' \
--data-raw '{
    "from": "[phone]",
    "to": "[phone]",
    "content": "This is a sample text message"
}'

Go

import "github.com/NdoleStudio/httpsms-go"

client := htpsms.New(htpsms.WithAPIKey(/* API Key from https://httpsms.com/settings */))

client.Messages.Send(context.Background(), &httpsms.MessageSendParams{
    Content: "This is a sample text message",
    From:    "[phone]",
    To:      "[phone]",
})

c-sharp

var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", ""/* Get API Key from https://httpsms.com/settings */);

var response = await client.PostAsync(
    "https://api.httpsms.com/v1/messages/send",
    new StringContent(
        JsonSerializer.Serialize(new {
            from = "[phone]",
            To = "[phone]",
            Content = "This is a sample text message",
        }),
        Encoding.UTF8,
        "application/json"
    )
);

Console.WriteLine(await response.Content.ReadAsStringAsync());

Java

var client = HttpClient.newHttpClient();

var apiKey = "Get API Key from https://httpsms.com/settings";

JSONObject request = new JSONObject();
request.put("content", "This is a sample text message");
request.put("from", "[phone]")
request.put("to", "[phone]")

// create a request
var request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.httpsms.com/v1/messages/send"))
  .header("accept", "application/json")
  .header("x-api-key", apiKey)
  .setEntity(new StringEntity(request.toString()))
  .POST()
  .build();

// use the client to send the request
var response = client.send(request, new JsonBodyHandler<>(APOD.class));

// the response:
System.out.println(response.body().get());

Install

The best way to interact with the httpSMS API is by using one of our official SDK client libraries:

JavaScript

npm install httpsms
# or
yarn install httpsms

Go

# install the go package using the "go get" command
go get github.com/NdoleStudio/httpsms-go