smsdora Developer Documentation

Overview

smsdorais a device-based SMS gateway that lets you send SMS messages through real Android devices. Instead of relying on expensive SMS provider APIs, you use your own phone(s) as the sending infrastructure — paying only your carrier's standard SMS rates.

Here's the idea in a nutshell:

You install our Android app on a phone and keep it connected.
You create an API key from the dashboard.
Your application calls our API endpoint with the recipient number and message.
The backend dispatches the SMS job to your phone, which sends it natively and reports the delivery status back.

Getting Started

Send your first SMS in under 5 minutes:

Step 1

Create an Account

Step 2

Connect Your Android Phone

Install the smsdora app from the Play Store. Log in with your account and grant SMS permissions. Your device will appear in the dashboard automatically.

Step 3

Create an API Key

Go to Dashboard → API Keys and create a new key. Make sure the messages:send scope is enabled. Copy and save the key — it's only shown once.

Step 4

Send Your First SMS

Make an API call to our send endpoint:

Send SMSbash

curl -X POST https://sms-backend-three-nu.vercel.app/messages/send \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+1234567890",
    "message": "Hello from smsdora!"
  }'

API Keys

API keys are how your application authenticates with smsdora. You create them from the API Keys page in the dashboard.

Store Your Key Securely

The full API key is only shown oncewhen you create it. We store a hashed version — we can't retrieve the original for you. Treat it like a password.

How to Use Your API Key

Include the key in the request header using either method:

Option 1 — x-api-key header (recommended)http

x-api-key: smsgw_ab12cd34_e7f8a9b0c1d2e3f4...

Option 2 — Authorization headerhttp

Authorization: Bearer smsgw_ab12cd34_e7f8a9b0c1d2e3f4...

Key Features

Rate limiting — You can set a per-minute request limit per key
Expiration — Optionally set an expiry date for automatic deactivation
Revoke — Instantly deactivate a key if compromised
Rotate — Generate a new secret while keeping the same key settings

Never use API keys in client-side code

Don't embed your API key in mobile apps, browser JavaScript, or any public-facing code. Always make API calls from your backend server to keep the key secret.

Sending SMS

Send an SMS with a single POST request:

POSThttps://sms-backend-three-nu.vercel.app/messages/send

Headers

Header	Value
`x-api-key`	Your API key
`Content-Type`	`application/json`

Request Body

Field	Type	Required	Description
`recipient`	string	Yes	Phone number in E.164 format (e.g. `+1234567890`)
`message`	string	Yes	SMS text content (1–1600 characters)

Example Request

cURLbash

curl -X POST https://sms-backend-three-nu.vercel.app/messages/send \
  -H "x-api-key: smsgw_ab12cd34_e7f8a9b0c1d2e3f4..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+212600000000",
    "message": "Your verification code is 4829"
  }'

Success Response

201 Createdjson

{
  "statusCode": 201,
  "message": "SMS queued for delivery",
  "data": {
    "id": "64a...",
    "recipient": "+212600000000",
    "message": "Your verification code is 4829",
    "status": "dispatching",
    "device": {
      "id": "64b...",
      "deviceName": "My Samsung S24"
    }
  }
}

Automatic device selection

You don't need to specify which phone sends the SMS. The backend automatically picks the best available device from your account — one that is online, active, and most recently seen.

Message Status

After sending, your message progresses through these statuses:

queueddispatchingsendingsentdelivered

Status	What it means
queued	Message received by our backend
dispatching	Job sent to your Android device via push notification
sending	Your phone is actively sending the SMS
sent	SMS handed off to the carrier network
delivered	Carrier confirmed delivery to the recipient
failed	SMS could not be sent or delivered

You can track the status of any message from the Messages page in the dashboard.

Error Handling

If something goes wrong, the API returns a JSON error with an HTTP status code:

Error Responsejson

{
  "statusCode": 400,
  "message": "No eligible device available",
  "error": "Bad Request"
}

Common Errors

Code	Cause	What to do
400	No eligible device available	Make sure at least one device is online and active
400	Invalid phone number or message	Check the recipient format and message length
401	Invalid, expired, or revoked API key	Check your API key or create a new one
403	Rate limit exceeded	Wait and retry, or increase your key's rate limit
403	Missing `messages:send` scope	Create a new key with the correct scope

Rate Limits

Each API key can have a configurable rate limit (requests per minute). You set this when creating the key in the dashboard.

If no rate limit is set, the key has unlimited requests per minute
Exceeding the limit returns 403 Forbidden
The rate limit resets on a rolling 60-second window

Plan-based limits

Your subscription plan also determines the monthly SMS volume and number of devices you can connect. Check the Pricing page for details.

Code Examples

Ready-to-use examples for sending an SMS. Replace YOUR_API_KEY with your actual key.

cURL

cURLbash

curl -X POST https://sms-backend-three-nu.vercel.app/messages/send \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+1234567890",
    "message": "Hello from smsdora!"
  }'

JavaScript / Node.js

Node.js (fetch)javascript

const response = await fetch(
  "https://sms-backend-three-nu.vercel.app/messages/send",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      recipient: "+1234567890",
      message: "Hello from smsdora!",
    }),
  }
);

const data = await response.json();
console.log(data);

Python

Python (requests)python

import requests

response = requests.post(
    "https://sms-backend-three-nu.vercel.app/messages/send",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "recipient": "+1234567890",
        "message": "Hello from smsdora!",
    },
)

print(response.json())

PHP

PHP (cURL)php

<?php
$ch = curl_init("https://sms-backend-three-nu.vercel.app/messages/send");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "x-api-key: YOUR_API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "recipient" => "+1234567890",
        "message" => "Hello from smsdora!",
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

C# / .NET

C# (HttpClient)csharp

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var payload = new {
    recipient = "+1234567890",
    message = "Hello from smsdora!"
};

var response = await client.PostAsJsonAsync(
    "https://sms-backend-three-nu.vercel.app/messages/send",
    payload
);

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Frequently Asked Questions

Ready to get started?

Create your free account, connect a phone, and start sending SMS in minutes.

Get Started Free Contact Support

smsdora Integration Guide