Developers
API
Base URL
All endpoints are served over HTTPS from https://otpgmail.com. Requests and responses are JSON unless stated otherwise.
Authentication
Catalog and price endpoints are public. Account endpoints accept either the session cookie set by /api/v1/auth/login, or an API key as Authorization: Bearer <key>. Keys are shown once when created and stored only as a hash, so a lost key must be replaced rather than recovered.
Rate limits
Requests are limited per key. When the limit is reached the response is 429 with a Retry-After header giving the seconds to wait — honour it rather than retrying immediately, or the wait gets longer.
Errors
Failures return a JSON body with a stable code and a human-readable message. Integrate against the code, never the message text, which may be reworded. Common codes: VALIDATION, UNAUTHENTICATED, INSUFFICIENT_FUNDS, OUT_OF_STOCK, RATE_LIMITED.
Money values
Prices and balances are decimal strings, not floating point numbers — for example "0.2100". Parse them with a decimal type. Reading them as a binary float will eventually produce a balance that disagrees with ours by a fraction of a cent, and the disagreement compounds.
Endpoints
| Method | Path | Description | Status |
|---|---|---|---|
| GET | /api/v1/prices | Live price and stock per service and country, with the markup applied.service, country, search, sort, minStock, limit, offset | Live |
| GET | /api/v1/services | Services that currently have numbers in stock.search | Live |
| GET | /api/v1/countries | Countries that currently have numbers in stock.search | Live |
| GET | /health | Service liveness and how recently the catalog was refreshed. | Live |
| POST | /api/v1/auth/login | Exchange email and password for a session cookie. | Live |
| GET | /api/v1/wallet | Current balance for the authenticated account. | Live |
| GET | /api/v1/wallet/entries | Ledger history: every deposit, hold, capture and refund.limit, offset | Live |
| POST | /api/v1/activations | Buy a number for a service and country. | Planned |
| GET | /api/v1/activations/{id} | Poll an activation for its received code. | Planned |
| GET | /stubs/handler_api.php | sms-activate compatible interface, so existing tools work unchanged. | Planned |
Example
The twenty cheapest Telegram numbers currently in stock:
curl "https://otpgmail.com/api/v1/prices?service=telegram&sort=price-asc&limit=20"
Each row carries serviceSlug, countrySlug, price, and stock. Use the slugs, not the display names — names are presentation and may be reformatted, slugs are stable.
Questions
Integration questions go to support. If you are building against the planned purchase endpoints, say so — the interface is easier to keep stable when we know who depends on it.