Developers Receive SMS codes
from code.

Base URL and authentication

https://app.mariosms.com/api/v1

Pass your API key (from your profile in the app) in the X-API-Key header, or as an api_key query parameter. All responses are JSON.

curl -H "X-API-Key: YOUR_KEY" https://app.mariosms.com/api/v1/balance
{ "balance": 100.00 }

Endpoints

The core loop

Rent a number for one verification, then poll until the code arrives:

# 1. Rent a US number for a Telegram verification
curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"country": "us", "service": "tg"}' \
  https://app.mariosms.com/api/v1/activation

{
  "id": "507f1f77bcf86cd799439011",
  "phone": "12025551234",
  "service": "tg",
  "country": "us",
  "price": 1.32,
  "status": "pending",
  "activationType": "SMS",
  "expiresAt": "2026-08-22T10:55:00Z"
}

# 2. Poll until status is "received"
curl -H "X-API-Key: YOUR_KEY" https://app.mariosms.com/api/v1/activation/507f1f77bcf86cd799439011

{
  "status": "received",
  "smsCode": "123456",
  "smsText": "Your Telegram code is 123456"
}

# 3. Or cancel before an SMS arrives for a full refund
curl -X POST -H "X-API-Key: YOUR_KEY" \
  https://app.mariosms.com/api/v1/activation/507f1f77bcf86cd799439011/cancel

{ "message": "activation cancelled", "refund": 1.32 }

activationType accepts SMS (default), CALL_VOICE, and CALL_FLASH; an optional operator field pins a specific carrier.

Client libraries and tutorials

• Python tutorial — full loop with requests
• Node.js tutorial — native fetch, zero dependencies
• Go tutorial — standard library client with context timeouts
• PHP tutorial — plain cURL, no framework

Compatibility API (handler_api protocol)

For scripts and tools written against the classic protocol used across the industry, MarioSMS exposes a compatibility endpoint. Most legacy integrations migrate with a base-URL change: same actions, same response formats.

https://app.mariosms.com/stubs/handler_api.php

Authentication is the api_key query parameter. Actions:

Renting and polling, classic style

# Balance
curl "https://app.mariosms.com/stubs/handler_api.php?api_key=KEY&action=getBalance"
ACCESS_BALANCE:44.60

# Rent a Telegram number (country accepts a numeric ID or ISO code)
curl "https://app.mariosms.com/stubs/handler_api.php?api_key=KEY&action=getNumber&country=48&service=tg"
ACCESS_NUMBER:8601705018416664:33774545375

# Voice call instead of SMS: add &activationType=2 (1 = flash call, 0 = SMS default)

# Poll for the code
curl "https://app.mariosms.com/stubs/handler_api.php?api_key=KEY&action=getStatus&id=8601705018416664"
STATUS_OK:877613

# Full SMS text
curl "https://app.mariosms.com/stubs/handler_api.php?api_key=KEY&action=getFullSms&id=8601705018416664"
FULL_SMS:[vk] 877613

# Finish (6) or cancel for refund (8)
curl "https://app.mariosms.com/stubs/handler_api.php?api_key=KEY&action=setStatus&id=8601705018416664&status=8"
ACCESS_CANCEL

getStatus responses

Error codes

Service codes

Both APIs identify services by short codes. The most-used ones:

The full live catalog (hundreds of services) with current codes comes from GET /api/v1/services, and per-country availability from action=getPrices. Country IDs come from action=getCountries; the REST API uses ISO codes (us, de, gb) directly.

HTTP status codes

Automation is welcome for QA, testing, and accounts you're entitled to create; bulk abuse is not. See the acceptable use policy.