SMS Gateway API

Use your Android device to send SMS through the phone's SIM card, receive delivery notifications via webhooks, and forward newly received SMS to your server.

✅ User-device based setup. Install the app on an Android device, generate an API key, and start sending SMS through that device.

🧪 Try the SMS Tester

Authentication

SMS Gateway API supports two authentication methods. We recommend V2 (Bearer token) for all new integrations.

V2 — Bearer Token (Recommended)

Pass your API key in the Authorization header:

HTTP Header

Authorization: Bearer YOUR_API_KEY

V1 — X-API-Key Header (Legacy)

Pass your API key in the X-API-Key header:

HTTP Header

X-API-Key: YOUR_API_KEY

ℹ️ Your API key is generated in the SMS Gateway API Android app under API Gateway → Generate API Key. Keep it secret — anyone with your key can send SMS from your device.

Base URL

All API requests are sent to Firebase Cloud Functions:

Base URL

https://europe-west1-sms-gateway-api-simpapp\
  .cloudfunctions.net

Endpoint	Version	Auth
/api_v2_sms_send	V2 ✨	Bearer token
/api_sms_send	V1	X-API-Key header

Quick Start

Send your first SMS in under 60 seconds:

curl

curl -X POST \
  https://europe-west1-sms-gateway-api-simpapp\
    .cloudfunctions.net/api_v2_sms_send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -d '{
    "phoneNumber": "+40712345678",
    "message": "Hello from SMS Gateway API!"
  }'

⚠️ The Android app must be running on a device with an active SIM and internet connection for SMS to be delivered.

Send SMS — V2 (Recommended)

POST /api_v2_sms_send

curl

curl -X POST \
  https://europe-west1-sms-gateway-api-simpapp\
    .cloudfunctions.net/api_v2_sms_send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "phoneNumber": "+40712345678",
    "message": "Your verification code is 1234"
  }'

Request Body

Parameter	Type	Required	Description
phoneNumber	string	Required	Recipient phone number in E.164 format (e.g. +40712345678)
message	string	Required	SMS message text. Max 160 chars for single SMS; longer messages are auto-concatenated.

Response

JSON — 200 OK

{
  "success": true,
  "messageId": "sms_abc123xyz",
  "status": "queued"
}

Status Codes

200 SMS queued successfully

400 Missing or invalid parameters

401 Invalid or missing API key

429 Rate limit exceeded (upgrade to PRO)

500 Internal error — device offline or SIM issue

Send SMS — V1 (Legacy)

Identical to V2 but uses X-API-Key header instead of Authorization: Bearer.

POST /api_sms_send

curl

curl -X POST \
  https://europe-west1-sms-gateway-api-simpapp\
    .cloudfunctions.net/api_sms_send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "phoneNumber": "+40712345678",
    "message": "Hello!"
  }'

ℹ️ V1 and V2 have identical functionality. We recommend migrating to V2 for all new projects.

Webhook — Delivery Status

When you configure a webhook URL in the app, delivery status updates are automatically POSTed to your endpoint after each SMS is sent.

ℹ️ Configure your webhook URL in the app under API Gateway → Webhook URL.

Payload sent to your webhook

JSON — POST to your endpoint

{
  "type":       "delivery_status",
  "id":         "sms_abc123xyz",
  "phoneNumber": "+40712345678",
  "status":     "delivered",  // queued | sent | delivered | failed
  "timestamp":  1714000000
}

Status	Meaning
queued	SMS accepted and queued by the app
sent	Handed to the carrier
delivered	Confirmed delivered to recipient
failed	Delivery failed (SIM error, no signal, etc.)

Expected Response

Return HTTP 200 to acknowledge. Any other status will be logged as a webhook failure.

Webhook — Incoming SMS Forwarding

When the app receives an SMS, it forwards it to your configured endpoint URL (set in Incoming SMS Forwarding screen).

Payload sent to your endpoint

JSON — POST to your endpoint

{
  "type":       "incoming_sms",
  "sender":     "+40799888777",
  "message":    "What are your opening hours?",
  "timestamp":  1714000000
}

Field	Type	Description
type	string	Always incoming_sms
sender	string	Sender phone number
message	string	SMS message text
timestamp	number	Unix timestamp (seconds)

Auto-Reply via Webhook

Your endpoint can respond with a JSON body containing sms_text and the app will automatically send an SMS reply back to the sender.

Your server responds with:

HTTP/1.1 200 OK
Content-Type: application/json

{ "sms_text": "We're open Mon–Fri 9:00–17:00. How can we help?" }

To send no reply, return HTTP 200 with an empty body (or without sms_text):

No reply

HTTP/1.1 200 OK

(empty body)

✅ This allows a user-controlled workflow to return an optional SMS reply from the same Android device.

Error Codes

JSON — Error Response

{
  "success": false,
  "error":   "Invalid API key",
  "code":    401
}

HTTP Code	Error	Fix
400	Missing phoneNumber or message	Include both fields in request body
401	Invalid or missing API key	Check your Authorization header or X-API-Key
403	Subscription required	Upgrade to PRO in the app
429	Rate limit exceeded	Slow down requests or upgrade to PRO
503	Device offline	Ensure Android app is running and connected

Rate Limits

Plan	Limit
Free Trial	Limited SMS per day
PRO Monthly / Yearly	Unlimited API calls*

* Actual SMS delivery is limited by your carrier and SIM plan, not the API.

Code Examples

Python

Python (requests)

import requests

API_KEY = "sk_live_YOUR_API_KEY"
BASE = "https://europe-west1-sms-gateway-api-simpapp"
URL = BASE + ".cloudfunctions.net/api_v2_sms_send"

response = requests.post(URL,
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "phoneNumber": "+40712345678",
        "message": "Hello from Python!"
    }
)
print(response.json())

Node.js

Node.js (fetch)

const URL =
  "https://europe-west1-sms-gateway-api-simpapp" +
  ".cloudfunctions.net/api_v2_sms_send";

const response = await fetch(URL,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer sk_live_YOUR_API_KEY"
    },
    body: JSON.stringify({
      phoneNumber: "+40712345678",
      message: "Hello from Node.js!"
    })
  }
);
const data = await response.json();
console.log(data);

PHP

PHP (curl)

$apiKey = "sk_live_YOUR_API_KEY";
$url    = "https://europe-west1-sms-gateway-api-simpapp"
        . ".cloudfunctions.net/api_v2_sms_send";
$payload = json_encode([
    "phoneNumber" => "+40712345678",
    "message"     => "Hello from PHP!"
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Content-Type: application/json",
        "Authorization: Bearer {$apiKey}"
    ]
]);
$result = curl_exec($ch);
echo $result;

Ready to test your API key?

🧪 Open SMS Tester →