SMSPM API Documentation

Version 2.0 | Last Updated: October 21, 2025

Introduction
Quick Start
Authentication
API Endpoint
Sending SMS Messages
Request Parameters
Response Format
Checking SMS Status and Details
Delivery Reports (Callbacks)
Message Encoding
Message Length & Splitting
Error Handling
Best Practices
Code Examples
Support

Introduction

The SMSPM API allows you to send SMS messages programmatically through simple HTTP requests. Our API supports both GET and POST methods, single and bulk messaging, and automatic Unicode detection for international characters.

Key Features

✅ Simple REST API with GET and POST support
✅ Send single or multiple SMS messages (up to 100 per request)
✅ Automatic Unicode detection and character encoding
✅ Automatic message splitting for long texts
✅ Real-time carrier and country detection
✅ Token-based authentication

Quick Start

1. Get Your Credentials

Before using the API, you need three things:

Hash - Your unique API hash identifier

Open the API page
You will see your hash displayed on the page

Token - Your API authentication token

Open the API page
Click the "Manage API Tokens" button
Generate a new token or use an existing one

Sender ID - The name or number that appears as the sender

To avoid fraud, most country carriers require Sender ID registration in advance
By default, smspm.com Sender ID is activated
To register additional Sender IDs:
- Go to the SMS page: https://app.smspm.com/app/sms
- Click the "Sender request" button on the right side
- Submit your Sender ID for approval

2. Send Your First SMS

curl "https://api.smspm.com?hash=YOUR_HASH&toNumber=37256789045&text=Hello%20World&fromNumber=SMSPM.com&token=YOUR_TOKEN"

Authentication

All API requests require two authentication parameters:

Parameter	Description	Example
`hash`	Your unique API hash	`52248aec022c6d53eabe30`
`token`	Your API authentication token	`A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6`

⚠️ Security Note: Keep your hash and token secure. Never expose them in client-side code or public repositories.

API Endpoint

Base URL: https://api.smspm.com

Supported Methods: GET, POST

Content-Type (for POST): application/json

Sending SMS Messages

Method 1: Single SMS via GET

Send a single SMS message using a simple GET request.

Endpoint: GET https://api.smspm.com

Example:

https://api.smspm.com?hash=YOUR_HASH&toNumber=37256789045&text=Hello+from+SMSPM.com&fromNumber=SMSPM&token=YOUR_TOKEN

Required Parameters:

hash: Your API hash
toNumber: Recipient phone number (international format without +)
text: Message content (URL encoded)
fromNumber: Sender ID (alphanumeric max 11 chars or numeric max 15 digits). Should be activated before.
token: Your API token

Method 2: Single SMS via POST

Send a single SMS using a POST request with JSON payload (recommended for security).

Endpoint: POST https://api.smspm.com

Headers:

Content-Type: application/json

Request Body:

{
  "hash": "YOUR_HASH",
  "toNumber": "37256789045",
  "text": "Hello from SMSPM",
  "fromNumber": "SMSPM.com",
  "token": "YOUR_TOKEN"
}

Example using cURL:

curl -X POST https://api.smspm.com \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "YOUR_HASH",
    "toNumber": "37256789045",
    "text": "Hello from SMSPM",
    "fromNumber": "SMSPM.com",
    "token": "YOUR_TOKEN"
  }'

Method 3: Multiple SMS via GET

Send the same message to multiple recipients using a GET request.

Endpoint: GET https://api.smspm.com

Example:

https://api.smspm.com?hash=YOUR_HASH&toNumber=[37256789045,37257788990,37258887766]&text=Hello+everyone&fromNumber=SMSPM.com&token=YOUR_TOKEN

Note: Pass recipient numbers as an array in square brackets, separated by commas.

Method 4: Multiple SMS via POST (Recommended for Bulk)

Send messages to multiple recipients (up to 100 per request) using a POST request.

Endpoint: POST https://api.smspm.com

Headers:

Content-Type: application/json

Request Body:

{
  "hash": "YOUR_HASH",
  "toNumber": ["37256789045", "37257788990", "37258887766"],
  "text": "Hello from SMSPM",
  "fromNumber": "SMSPM.com",
  "token": "YOUR_TOKEN"
}

Example using cURL:

curl -X POST https://api.smspm.com \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "YOUR_HASH",
    "toNumber": ["37256789045", "37257788990"],
    "text": "Hello from SMSPM",
    "fromNumber": "SMSPM.com",
    "token": "YOUR_TOKEN"
  }'

Request Parameters

Required Parameters

Parameter	Type	Description	Format/Constraints
`hash`	String	Your unique API hash identifier	Generated in your account
`toNumber`	String or Array	Recipient phone number(s)	International format without + Must be at least 5 digits Single: `"37256789045"` Multiple: `["37256789045", "37257788990"]`
`text`	String	SMS message content	URL encoded for GET requests Max 160 chars (standard) or 70 chars (Unicode)
`fromNumber`	String	Sender ID	Alphanumeric: max 11 characters Numeric: max 15 digits Must be pre-approved in your account
`token`	String	API authentication token	Generated in your account

Optional Parameters

Parameter	Type	Description	Format
`report`	String	Callback URL for delivery reports	Valid URL
`smsId`	String	Custom message identifier	Any unique string

Response Format

Success Response

When messages are successfully queued, you'll receive a JSON response:

{
  "messages": [
    {
      "id": "a7b3c4d5-e6f7-8a9b-0c1d-2e3f4a5b6c7d",
      "toNumber": "37256789045",
      "status": "Added to queue"
    },
    {
      "id": "b8c4d5e6-f7a8-9b0c-1d2e-3f4a5b6c7d8e",
      "toNumber": "37257788990",
      "status": "Added to queue"
    }
  ]
}

Response Fields:

id: Unique message identifier (UUID)
toNumber: Recipient phone number
status: Current message status

Error Response

When an error occurs, you'll receive:

{
  "error": "Error message describing what went wrong"
}

HTTP Status Codes:

200: Success - messages queued
400: Bad Request - validation error
405: Method Not Allowed - incorrect HTTP method

Checking SMS Status and Details

You can retrieve the status and details of sent SMS messages using the /smsdetails endpoint.

Get SMS Details via GET

Endpoint: GET https://api.smspm.com/smsdetails

Parameters:

id: The SMS message ID (received when sending the SMS)
hash: Your API hash

Example:

https://api.smspm.com/smsdetails?id=a7b3c4d5-e6f7-8a9b-0c1d-2e3f4a5b6c7d&hash=YOUR_HASH

Example using cURL:

curl "https://api.smspm.com/smsdetails?id=a7b3c4d5-e6f7-8a9b-0c1d-2e3f4a5b6c7d&hash=YOUR_HASH"

Get SMS Details via POST

Endpoint: POST https://api.smspm.com/smsdetails

Headers:

Content-Type: application/json

Request Body:

{
  "id": "a7b3c4d5-e6f7-8a9b-0c1d-2e3f4a5b6c7d",
  "hash": "YOUR_HASH"
}

Example using cURL:

curl -X POST https://api.smspm.com/smsdetails \
  -H "Content-Type: application/json" \
  -d '{
    "id": "a7b3c4d5-e6f7-8a9b-0c1d-2e3f4a5b6c7d",
    "hash": "YOUR_HASH"
  }'

SMS Details Response

Success Response:

{
  "id": "a7b3c4d5-e6f7-8a9b-0c1d-2e3f4a5b6c7d",
  "hash": "52248aec022c6d53eabe30",
  "price": 0.045,
  "country": "Estonia",
  "carrier": "Telia",
  "status": "delivered",
  "toNumber": "37256789045"
}

Response Fields:

id: Unique message identifier
hash: Your API hash
price: Cost of the SMS in EUR
country: Destination country
carrier: Mobile carrier
status: Current delivery status (queued, submitted, delivered, failed)
toNumber: Recipient phone number

Error Responses:

Missing parameters:

{
  "error": "Missing required parameters: id and hash are mandatory"
}

SMS not found:

{
  "error": "SMS not found or invalid credentials"
}

Status Values:

Added to queue: Message is waiting in queue
submitted: Message has been sent to carrier
delivered: Message successfully delivered
failed: Message delivery failed

Example: Track SMS Status

// Send SMS and save the ID
const sendResponse = await fetch("https://api.smspm.com", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    hash: "YOUR_HASH",
    token: "YOUR_TOKEN",
    toNumber: "37256789045",
    text: "Hello!",
    fromNumber: "SMSPM.com",
  }),
});

const sendData = await sendResponse.json();
const smsId = sendData.messages[0].id;

// Check SMS status after a delay
setTimeout(async () => {
  const statusResponse = await fetch("https://api.smspm.com/smsdetails", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      id: smsId,
      hash: "YOUR_HASH",
    }),
  });

  const statusData = await statusResponse.json();
  console.log("SMS Status:", statusData.status);
  console.log("Price:", statusData.price, "EUR");
}, 5000); // Check after 5 seconds

Delivery Reports (Callbacks)

To receive automatic delivery status updates, you can specify a callback URL when sending SMS messages.

Using Delivery Reports

Include the report parameter in your SMS sending request:

GET Request:

https://api.smspm.com?hash=YOUR_HASH&toNumber=37256789045&text=Hello&fromNumber=SMSPM.com&token=YOUR_TOKEN&report=https://yourdomain.com/sms-callback

POST Request:

{
  "hash": "YOUR_HASH",
  "token": "YOUR_TOKEN",
  "toNumber": "37256789045",
  "text": "Hello",
  "fromNumber": "SMSPM.com",
  "report": "https://yourdomain.com/sms-callback"
}

Callback Request

When the SMS delivery status changes, our system will make a GET request to your callback URL with the following parameters:

https://yourdomain.com/sms-callback?id=a7b3c4d5-e6f7-8a9b&status=delivered&toNumber=37256789045

Callback Parameters:

id: SMS message ID
status: Current delivery status
toNumber: Recipient phone number

Implementing a Callback Endpoint

PHP Example:

<?php
// sms-callback.php
$smsId = $_GET['id'];
$status = $_GET['status'];
$toNumber = $_GET['toNumber'];

// Log the delivery status
file_put_contents('sms-log.txt',
    date('Y-m-d H:i:s') . " - SMS $smsId to $toNumber: $status\n",
    FILE_APPEND
);

// Update database
// $db->update('sms_tracking', ['status' => $status], ['id' => $smsId]);

// Return 200 OK
http_response_code(200);
echo 'OK';
?>

Node.js/Express Example:

app.get("/sms-callback", (req, res) => {
  const { id, status, toNumber } = req.query;

  console.log(`SMS ${id} to ${toNumber}: ${status}`);

  // Update your database
  // db.updateSmsStatus(id, status);

  res.status(200).send("OK");
});

Important Notes:

Your callback endpoint must return HTTP 200 OK
The callback endpoint must be publicly accessible via HTTPS
Callbacks are sent when status changes (submitted, delivered, failed)
Keep your callback processing fast (< 1 second response time)

Message Encoding

Standard (GSM 7-bit) Encoding

Messages use GSM 7-bit encoding by default, which supports:

English alphabet (A-Z, a-z)
Numbers (0-9)
Common punctuation and symbols
Extended characters like €, [, ], {, }, |, ~, ^ (count as 2 characters each)

Character Limit: 160 characters per SMS

Unicode (UCS-2) Encoding

Unicode encoding is automatically detected when your message contains:

Non-Latin characters (Cyrillic, Arabic, Chinese, etc.)
Emoji 😊
Special symbols not in GSM 7-bit alphabet

Character Limit: 70 characters per SMS

Note: You don't need to specify encoding - the API detects it automatically.

Message Length & Splitting

Single SMS

Encoding	Max Length
GSM 7-bit	160 characters
Unicode	70 characters

Concatenated SMS (Long Messages)

When your message exceeds the single SMS limit, it's automatically split:

Encoding	Characters per Part	Header Overhead
GSM 7-bit	153 characters	7 characters
Unicode	67 characters	3 characters

Example:

A 350-character GSM message = 3 SMS parts (153 + 153 + 44)
A 150-character Unicode message = 3 SMS parts (67 + 67 + 16)

Important: You are charged for each SMS part sent.

Error Handling

Common Error Messages

Error Message	Cause	Solution
`At least one recipient number is required`	Missing or empty `toNumber`	Provide at least one valid phone number
`Message text is required`	Missing `text` parameter	Include message content
`Sender number is required`	Missing `fromNumber`	Provide a sender ID
`Hash is required`	Missing `hash` parameter	Include your API hash
`Token is required`	Missing `token` parameter	Include your API token
`Invalid phone number: [number]`	Phone number too short	Ensure number is at least 5 digits

Phone Number Validation

Phone numbers must:

Be in international format
Contain at least 5 digits
Include the country code

Examples:

✅ Correct: 37256789045 (Estonia)
✅ Correct: 447912345678 (UK)
❌ Incorrect: 56789045 (missing country code)

Automatic Phone Number Fixing

The API includes smart phone number correction:

Rule 1: If an 8-digit Estonian number starts with 5, the country code 372 is automatically added.

Input: 56789045 → Output: 37256789045

Best Practices

1. Use POST for Production

While GET requests are convenient for testing, use POST requests in production for:

Better security (credentials not in URL)
Support for longer messages
Proper handling of special characters

2. URL Encode GET Parameters

When using GET requests, always URL encode your parameters:

// JavaScript example
const text = "Hello! How are you?";
const encoded = encodeURIComponent(text); // "Hello!%20How%20are%20you%3F"

3. Handle Errors Gracefully

Always check the response status and handle errors:

const response = await fetch(apiUrl);
const data = await response.json();

if (data.error) {
  console.error("API Error:", data.error);
  // Handle error appropriately
} else {
  console.log("Messages queued:", data.messages);
}

4. Batch Multiple Recipients

When sending to multiple recipients, use a single request with an array rather than multiple individual requests:

{
  "toNumber": ["37256789045", "37257788990", "37258887766"]
}

Maximum: 100 recipients per request

5. Monitor Your Balance

Keep track of your account balance to ensure uninterrupted service. Check your balance in: User Account → Dashboard

6. Test with Approved Sender IDs

Ensure your fromNumber (Sender ID) is pre-approved in your account:

User Account → SMS → Sender request

Code Examples

JavaScript/Node.js (Single SMS)

// Using fetch API
async function sendSMS() {
  const response = await fetch("https://api.smspm.com", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      hash: "YOUR_HASH",
      toNumber: "37256789045",
      text: "Hello from SMSPM API",
      fromNumber: "SMSPM.com",
      token: "YOUR_TOKEN",
    }),
  });

  const data = await response.json();

  if (data.error) {
    console.error("Error:", data.error);
  } else {
    console.log("Success:", data.messages);
  }
}

sendSMS();

JavaScript/Node.js (Multiple SMS)

async function sendBulkSMS() {
  const recipients = ["37256789045", "37257788990", "37258887766"];

  const response = await fetch("https://api.smspm.com", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      hash: "YOUR_HASH",
      toNumber: recipients,
      text: "Bulk message to all recipients",
      fromNumber: "smspm.com",
      token: "YOUR_TOKEN",
    }),
  });

  const data = await response.json();
  console.log("Messages queued:", data.messages.length);
}

sendBulkSMS();

PHP (Single SMS)

<?php
$url = 'https://api.smspm.com';
$data = [
    'hash' => 'YOUR_HASH',
    'toNumber' => '37256789045',
    'text' => 'Hello from SMSPM API',
    'fromNumber' => 'SMSPM.com',
    'token' => 'YOUR_TOKEN'
];

$options = [
    'http' => [
        'header'  => "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($data)
    ]
];

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);

if (isset($response['error'])) {
    echo 'Error: ' . $response['error'];
} else {
    echo 'Success! Messages queued: ' . count($response['messages']);
}
?>

Python (Single SMS)

import requests
import json

url = 'https://api.smspm.com'
data = {
    'hash': 'YOUR_HASH',
    'toNumber': '37256789045',
    'text': 'Hello from SMSPM API',
    'fromNumber': 'SMSPM.com',
    'token': 'YOUR_TOKEN'
}

response = requests.post(url, json=data)
result = response.json()

if 'error' in result:
    print(f"Error: {result['error']}")
else:
    print(f"Success! Messages: {result['messages']}")

cURL (GET - Single SMS)

curl "https://api.smspm.com?hash=YOUR_HASH&toNumber=37256789045&text=Hello%20World&fromNumber=SMSPM.com&token=YOUR_TOKEN"

cURL (POST - Multiple SMS)

curl -X POST https://api.smspm.com \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "YOUR_HASH",
    "toNumber": ["37256789045", "37257788990"],
    "text": "Hello everyone!",
    "fromNumber": "smspm.com",
    "token": "YOUR_TOKEN"
  }'

Migration from v1.x

If you're migrating from the old API (v1.x), here are the key changes:

Create a New Account

Important: You need to create a new account in our new system at https://app.smspm.com/app

The new system uses different hashes and tokens, so you'll need to:

Register at https://app.smspm.com/app/register
Generate new API credentials
Update your integration with new hash and token

URL Change

Old: http://panel.smspm.com/gateway/{hash}/api.v1/send
New: https://api.smspm.com

Authentication

Old: Only hash required in URL path
New: Hash AND token required as parameters

Parameters

Old: sender parameter
New: fromNumber parameter (same functionality)

Response Format

Old: Simple text response
New: Structured JSON response with message details

Example Migration

Old API Call:

http://panel.smspm.com/gateway/OLD_HASH_HERE/api.v1/send?
  phone=37254515400&
  sender=SMSPM.com&
  message=Test&
  output=json

New API Call:

https://api.smspm.com?
  hash=NEW_HASH_HERE&
  toNumber=37254515400&
  fromNumber=SMSPM&
  text=Test&
  token=YOUR_NEW_TOKEN

Note: Make sure to use your NEW hash and token from the new system at https://app.smspm.com/app

Support

Documentation & Resources

API Dashboard: https://app.smspm.com/app/api
Account Management: https://app.smspm.com/app
GSM 7-bit Alphabet: https://www.smspm.com/7-bit-GSM-alphabet

Contact Information

Email: [email protected]
Phone: +372 5451 5400
Support Hours: Daily 08:00-18:00 (GMT +2)

Getting Help

When contacting support, please include:

Your account hash
Example request (with token removed)
Complete error message
Timestamp of the issue
Expected vs actual behavior

Document Version: 2.0
Last Updated: October 21, 2025
API Version: 2.0

SMSPM API Documentation

Table of Contents

Introduction

Key Features

Quick Start

1. Get Your Credentials

2. Send Your First SMS

Authentication

API Endpoint

Sending SMS Messages

Method 1: Single SMS via GET

Method 2: Single SMS via POST

Method 3: Multiple SMS via GET

Method 4: Multiple SMS via POST (Recommended for Bulk)

Request Parameters

Required Parameters

Optional Parameters

Response Format

Success Response

Error Response

Checking SMS Status and Details

Get SMS Details via GET

Get SMS Details via POST

SMS Details Response

Example: Track SMS Status

Delivery Reports (Callbacks)

Using Delivery Reports

Callback Request

Implementing a Callback Endpoint

Message Encoding

Standard (GSM 7-bit) Encoding

Unicode (UCS-2) Encoding

Message Length & Splitting

Single SMS

Concatenated SMS (Long Messages)

Error Handling

Common Error Messages

Phone Number Validation

Automatic Phone Number Fixing

Best Practices

1. Use POST for Production

2. URL Encode GET Parameters

3. Handle Errors Gracefully

4. Batch Multiple Recipients

5. Monitor Your Balance

6. Test with Approved Sender IDs

Code Examples

JavaScript/Node.js (Single SMS)

JavaScript/Node.js (Multiple SMS)

PHP (Single SMS)

Python (Single SMS)

cURL (GET - Single SMS)

cURL (POST - Multiple SMS)

Migration from v1.x

Create a New Account

URL Change

Authentication

Parameters

Response Format

Example Migration

Support

Documentation & Resources

Contact Information

Getting Help