Self Hosted SMS API API

Documentation for the SMS Queue and App Version APIs

Download Collection Download Environment

Quick Start

Download both files above
Open Postman and click Import
Import both the Collection and Environment files
Select "SelfHostedSMS" environment from the top-right dropdown
Edit the environment variables with your API token and base URL
Start making requests!

Authentication

SMS Queue endpoints require authentication via an API token passed in the URL path:

/api/{your-api-token}/endpoint

You can find your 64-character API token in your dashboard settings.

Note: App Version endpoints (/api/app-version, /api/app-versions, /download/*) are public and do not require authentication.

Rate Limiting

API requests are limited to 60 requests per minute per API token.

Endpoints

App Version (Public)

These endpoints are public and do not require authentication.

GET /api/app-version

Get the currently active app version information.

Response (200 OK)

{
  "version": "1.2.0",
  "versionCode": 5,
  "downloadUrl": "https://selfhostedsms.com/download/app.apk",
  "releaseNotes": "- Bug fixes\n- Performance improvements",
  "fileSize": 15728640,
  "publishedAt": "2026-01-26T12:00:00+00:00"
}

Response (404 Not Found)

{
  "error": "No active version available",
  "code": "no_active_version"
}

GET /api/app-versions

List all published app versions, sorted by version code (newest first).

Response (200 OK)

{
  "versions": [
    {
      "version": "1.2.0",
      "versionCode": 5,
      "isActive": true,
      "downloadUrl": "https://selfhostedsms.com/api/download/5",
      "releaseNotes": "- Bug fixes",
      "fileSize": 15728640,
      "publishedAt": "2026-01-26T12:00:00+00:00"
    }
  ]
}

GET /download/app.apk

Download the currently active APK file.

Response Headers

`Content-Type`	application/vnd.android.package-archive
`Content-Disposition`	attachment; filename="app-v1.2.0.apk"

Note: Returns the binary APK file for direct download. Each download increments the download counter.

GET /api/download/{version_code}

Download a specific APK version by its version code.

URL Parameters

Parameter	Required	Description
`version_code`	Yes	Numeric version code (e.g., 5)

Response (404 Not Found)

{
  "error": "Version not found",
  "code": "version_not_found"
}

SMS Queue (Authenticated)

These endpoints require API token authentication.

POST /api/{api_token}/queue

Add one or more SMS messages to the queue.

Request Body

[
  {
    "phone": "+1234567890",
    "message": "Hello, this is a test message"
  },
  {
    "phone": "0712345678",
    "message": "Another test message"
  }
]

Validation Rules

Field	Required	Rules
`phone`	Yes	6-20 digits, optionally starting with `+`
`message` or `text`	Yes	Max 1000 characters

Response (200 OK)

{
  "ok": true,
  "queued": 2,
  "failed": 0,
  "items": [
    { "index": 0, "hash": "a1b2c3d4e5f67890", "phone": "+1234567890" },
    { "index": 1, "hash": "f8e7d6c5b4a32109", "phone": "0712345678" }
  ],
  "errors": []
}

GET /api/{api_token}/get_messages

Retrieve pending SMS messages from the queue. Messages are returned in FIFO order and automatically marked as "initiated".

Query Parameters

Parameter	Required	Default	Description
`limit`	No	20	Number of messages to retrieve (max 200)

Response (200 OK)

[
  {
    "phone": "+1234567890",
    "text": "Hello, this is a test message",
    "hash": "a1b2c3d4e5f67890"
  }
]

Note: Once retrieved, messages are marked as "initiated" (status 1). Use the /status endpoint to report delivery success or failure.

POST /api/{api_token}/status

Update the delivery status of one or more SMS messages.

Request Body

{
  "device": "MyPhone",
  "messages": [
    { "hash": "a1b2c3d4e5f67890", "status": 2 },
    { "hash": "f8e7d6c5b4a32109", "status": 3 }
  ]
}

Request Fields

Field	Required	Description
`device`	No	Device name that sent the messages (max 15 chars)
`messages`	Yes	Array of status updates
`messages[].hash`	Yes	Message hash from queue
`messages[].status`	Yes	Status code (2 = success, 3 = fail)

Status Codes

Status	Meaning
`0`	New (default, cannot set via API)
`1`	Initiated (set automatically on retrieval)
`2`	Success - Message delivered
`3`	Fail - Message failed to deliver

Response (200 OK)

{
  "ok": true,
  "updated": 2
}

Error Responses

401 Unauthorized

{ "error": "Invalid API token" }

403 Forbidden - No Subscription

{
  "error": "No active subscription",
  "code": "subscription_required"
}

429 Too Many Requests - SMS Limit

{
  "error": "SMS limit exceeded for this month",
  "code": "limit_exceeded",
  "limit": 1000,
  "used": 1000
}

422 Unprocessable Entity - Validation Error

{
  "ok": false,
  "queued": 0,
  "failed": 1,
  "items": [],
  "errors": [
    { "index": 0, "error": "Invalid phone format" }
  ]
}