← Back to home

Partner API

Integrate with this platform from your own server. All responses are JSON. Your base URL for the examples below is https://mail.smsx.site (detected from this request; use your production domain in live environments).

Authentication. Every request must include your API key, either as Authorization: Bearer <your_key> or X-API-Key: <your_key>. The operator issues this key; keep it on your backend only (never in public web pages or mobile apps).

HTTPS. Use TLS in production. Server-to-server calls from your backend are recommended so the key stays secret.

How to get an API key

If you are integrating as a developer: This site does not expose a “sign up for API key” screen yet. You receive a key from the site operator (business owner)—usually after wallet/agreement setup—via support email, ticket, or dashboard message. Treat it like a password.

If you run this site: You create keys on the server, then give each partner their own secret:

Recommended: Set environment variable PORTAL_SMS_API_KEY to one secret, or several separated by commas (rotation / multiple clients).
Local testing only: In portal_api_sms_config.php, uncomment the line that appends a key string—use a long random value and remove it before production.

To generate a random secret (example): OpenSSL: openssl rand -hex 32; or any password manager “random string” (~32+ characters).

1. Outbound SMS

Sends a text message to a handset via the operator’s outbound provider (Twilio when configured). This is separate from renting virtual numbers for OTP.

POST https://mail.smsx.site/api/sms-send.php

Body (JSON):

{
  "to": "+15551234567",
  "message": "Your verification code is 123456"
}

HTTP	Meaning
200	`{"ok":true}` — message accepted by the gateway
400	Invalid JSON, `to`, or `message`
401	Missing or wrong API key
405	Method not POST
501	`outbound_sms_not_configured` — operator must set Twilio env on the server
502	Provider error (see `error` string)
503	Server has no API keys configured

Example (curl)

curl -sS -X POST "https://mail.smsx.site/api/sms-send.php" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"to":"+15551234567","message":"Hello"}'

2. Virtual numbers (OTP inbox)

Rent a temporary number, poll for the SMS code, or cancel—same catalogue and wallet rules as the website. CORS is enabled for browser preflight; still prefer server-side calls.

https://mail.smsx.site/api/virtual-numbers.php?action=…

Read-only (GET)

action	Description
`balance`	Upstream SMSBower-style balance for the resolved provider (`smsbower_balance`, `api_id`).
`wallet`	Wallet balance on this platform for the configured partner user (requires `PARTNER_VIRTUAL_USER_ID` on server).
`countries`	List of countries (JSON array under `countries`).
`services`	List of services (JSON under `services`).
`prices`	Optional query `&service=CODE&country=ID`. Returns `prices` plus `upstream_action`.
`status`	Query param `&id=<activation_id>`. Responses include `status`: `waiting`, `received` (with `otp`), or `cancelled`. May return `unknown` with truncated `raw` from upstream.

Write (POST + JSON)

action (query)	Body
`rent_number`	`{"service":"SERVICE_CODE","country":22}` — optional `"api_id":123` to pick a specific SMSBower row. Returns `activation_id` and `phone`.
`cancel`	`{"id":"ACTIVATION_ID"}`

Renting numbers, polling status, and cancel require the operator to set server env PARTNER_VIRTUAL_USER_ID (a wallet user ID on this site). Without it you will receive partner_user_not_configured (HTTP 503). Optional PARTNER_VIRTUAL_API_ID selects which SMSBower provider row to use by default.

Example: catalogue → rent → poll

# Countries
curl -sS "https://mail.smsx.site/api/virtual-numbers.php?action=countries" \
  -H "X-API-Key: YOUR_API_KEY"

# Rent number
curl -sS -X POST "https://mail.smsx.site/api/virtual-numbers.php?action=rent_number" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"service":"tg","country":22}'

# Poll (repeat until status is received or cancelled)
curl -sS "https://mail.smsx.site/api/virtual-numbers.php?action=status&id=ACTIVATION_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Support

Operators: virtual-number API actions also need PARTNER_VIRTUAL_USER_ID (wallet user) on the server. Outbound SMS needs Twilio env vars. Billing and quotas are between you and your users—this page only describes the HTTP API.