API Documentation

Simple and straightforward API to integrate SMS sending into your applications.

Overview

SMS Nodes Gateway provides a simple API for sending SMS messages through registered Android devices. Each device acts as an SMS gateway and requires authentication to send messages.

Base URL

http://gateway.smsnodes.com:3000

Authentication

All API requests require device credentials. You need a registered device with a username and password to send SMS messages.

📱 Device Required

You need the SMS Nodes mobile app installed on an Android device to use this API. The device acts as your SMS gateway.

API Endpoints

Send SMS

POST/api/send-sms

Send SMS messages through your registered Android device.

Request Body

{
  "deviceUsername": "your_device_name",
  "password": "your_device_password",
  "phoneNumbers": ["+1234567890", "+0987654321"],
  "message": "Hello from SMS Nodes!",
  "priority": 1
}

Parameters

  • deviceUsername - Your device's username (required)
  • password - Your device's password (required)
  • phoneNumbers - Array of phone numbers to send to (required)
  • message - The SMS message text (required)
  • priority - Message priority 1-5 (optional, default: 1)

Response

{
  "message": "SMS queued successfully",
  "messageId": 123,
  "deviceOnline": true,
  "sentImmediately": true
}

Health Check

GET/api/health

Check if the SMS gateway server is running and get basic system information.

Response

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "ssl": false,
  "encryption": "AES-256-CBC with user-derived keys",
  "connectedDevices": 3
}

Code Examples

JavaScript/Node.js

const axios = require('axios');

const API_BASE = 'http://gateway.smsnodes.com:3000';

// Send SMS
async function sendSMS() {
  try {
    const response = await axios.post(`${API_BASE}/api/send-sms`, {
      deviceUsername: 'your_device',
      password: 'your_password',
      phoneNumbers: ['+1234567890'],
      message: 'Hello from SMS Nodes!',
      priority: 1
    });
    
    console.log('SMS sent:', response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

// Check server health
async function checkHealth() {
  try {
    const response = await axios.get(`${API_BASE}/api/health`);
    console.log('Server status:', response.data);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

sendSMS();

Python

import requests

API_BASE = 'http://gateway.smsnodes.com:3000'

def send_sms():
    url = f'{API_BASE}/api/send-sms'
    data = {
        'deviceUsername': 'your_device',
        'password': 'your_password',
        'phoneNumbers': ['+1234567890'],
        'message': 'Hello from SMS Nodes!',
        'priority': 1
    }
    
    try:
        response = requests.post(url, json=data)
        response.raise_for_status()
        print('SMS sent:', response.json())
    except requests.exceptions.RequestException as e:
        print('Error:', e)

def check_health():
    url = f'{API_BASE}/api/health'
    try:
        response = requests.get(url)
        response.raise_for_status()
        print('Server status:', response.json())
    except requests.exceptions.RequestException as e:
        print('Error:', e)

send_sms()

cURL

# Send SMS
curl -X POST http://gateway.smsnodes.com:3000/api/send-sms \
  -H "Content-Type: application/json" \
  -d '{
    "deviceUsername": "your_device",
    "password": "your_password",
    "phoneNumbers": ["+1234567890"],
    "message": "Hello from SMS Nodes!",
    "priority": 1
  }'

# Check health
curl http://gateway.smsnodes.com:3000/api/health

Error Handling

The API uses standard HTTP status codes and returns JSON error responses.

400 Bad Request

{
  "error": "Username and password are required"
}

401 Unauthorized

{
  "error": "Invalid credentials"
}

500 Internal Server Error

{
  "error": "Database error"
}

Ready to Start?

Get the SMS Nodes mobile app, register your device, and start sending SMS messages through our API.

Open DashboardBack to Home