Portal API

Everything the SMPP portal does goes through a JSON API. You can call it from your own tools.

Item	Value
Base URL	`https://smpp.smsyanu.com/api/v1`
Sign in	`POST /auth/login` with email and password returns an `access_token`. A yanu-auth session cookie on `.smsyanu.com` also works.
Send the token	`Authorization: Bearer <access_token>`
Format	JSON. One report is CSV.
Bind ids in paths	The bind's `system_id`
Errors	JSON `{"detail": "..."}` with a plain-language message

Too many wrong passwords on /auth/login block that sign-in for 15 minutes (HTTP 429).

Method	Path	What it does
`POST`	`/auth/login`	Body `email`, `password`. Returns `access_token` and `user`.
`GET`	`/auth/me`	Who you are and your role.
`POST`	`/auth/change-password`	Body `current_password`, `new_password` (at least 10 characters).
`POST`	`/auth/logout-everywhere`	Ends every session of your account.
`GET`	`/auth/needs-setup`	`true` only before the first admin exists.
`POST`	`/auth/setup`	Makes the first admin. Needs the server's bootstrap key. Works once.

Clients

Method	Path	What it does
`GET`	`/my/binds`	Your binds: `system_id`, countries, throughput, `balance_sms`, `smpp_host`, `smpp_port`, price in MWK and USD.
`POST`	`/my/binds/{system_id}/reset-password`	New 8-character password, returned once as `password`.
`PUT`	`/my/binds/{system_id}/ips`	Body `allowed_ips`: a list of addresses or networks. Returns the saved list.
`GET`	`/my/quote?system_id=...&amount=...&currency=MWK`	How many SMS an amount buys on a bind.
`POST`	`/my/topups`	Ask for a top-up. See below.
`GET`	`/my/topups`	Your top-up requests.
`GET`	`/my/ledger`	Every credit change on your binds.

Top-up request body:

{
  "system_id": "kwacha482913",
  "amount": 50000,
  "currency": "MWK",
  "method": "bank",
  "payer_reference": "FT26309XYZ12",
  "note": "November top-up"
}

method is bank, mobile_money or other. payer_reference is 4 to 120 characters. The price is locked when you submit. The smallest top-up is 100 SMS. A reference already used by a live request returns HTTP 409.

Reports

Method	Path	What it does
`GET`	`/reports/messages`	Messages. Filters `system_id`, `status`, `country`, `date_from`, `date_to` (like `2026-11-05`), `q` (part of a number), `limit` (up to 500), `offset`. Returns `total` and `messages`.
`GET`	`/reports/summary`	`totals`, `by_day` and `by_country` with messages, segments, delivered and failed.
`GET`	`/reports/messages.csv`	The same messages as CSV (up to 200,000 rows).
`GET`	`/bind-status`	Live bind status per bind: `connected`, `sessions`, `connected_since`, `last_disconnected_at`.

Without dates a report covers the last 7 days. A range can be up to 400 days. Clients see their own binds, resellers their clients' binds, admins everything.

Resellers

Method	Path	What it does
`GET`	`/reseller/me`	Your profile, and per country your wholesale price, retail price and pool (`balance_sms`).
`GET` / `POST`	`/reseller/clients`	List or add clients (`email`, `name`, optional `phone`, `company`).
`PATCH`	`/reseller/clients/{id}`	Change a client, or switch it off with `is_active`.
`GET` / `POST`	`/reseller/binds`	List or create client binds (`client_id`, `country_code`, `label`, `allowed_ips`, `throughput` 1 to 100).
`PATCH`	`/reseller/binds/{system_id}`	Change `label`, `throughput` or `is_active`.
`POST`	`/reseller/binds/{system_id}/reset-password`	New password, shown once.
`PUT`	`/reseller/binds/{system_id}/ips`	Set the allowed IP list.
`POST`	`/reseller/binds/{system_id}/transfer`	Move SMS from your pool to the bind. Body `sms`, `idempotency_key`, optional `note`.
`POST`	`/reseller/binds/{system_id}/reclaim`	Move unused SMS from the bind back to your pool. Same body.
`PUT`	`/reseller/prices/{cc}`	Your retail price for a country: `retail_mwk`, `retail_usd`. `cc` is a two-letter code like `MW`.
`GET`	`/reseller/ledger`	Every change to your pools.
`GET`	`/reseller/topups`	Your clients' top-up requests.
`POST`	`/reseller/topups/{id}/approve`	Approve. The SMS come from your pool. Optional `note`.
`POST`	`/reseller/topups/{id}/reject`	Reject with an optional `note`.

Use a new idempotency_key (8 to 120 characters) for each transfer. If you send the same key again, nothing moves twice.

Admins

Method	Path	What it does
`GET` / `POST`	`/admin/users`	Portal accounts. Create with `email`, `name`, `role` (`user`, `reseller`, `admin`), optional `password`, `parent_reseller_id`.
`PATCH`	`/admin/users/{id}`	Change an account or switch it off.
`GET` / `POST`	`/admin/binds`	All binds. Create with `owner_id`, `countries`, `label`, `allowed_ips`, `throughput` (1 to 500), optional `max_bindings`, `price_override`, `system_id`.
`GET` / `PATCH` / `DELETE`	`/admin/binds/{system_id}`	Read, change (countries, throughput, status, price) or delete a bind.
`POST`	`/admin/binds/{system_id}/reset-password`	New password, shown once.
`PUT`	`/admin/binds/{system_id}/ips`	Set the allowed IP list.
`POST`	`/admin/binds/{system_id}/credit`	Add (positive `sms`) or remove (negative `sms`) credit. Needs `idempotency_key`. Optional `amount`, `currency`, `reference`, `note`.
`GET`	`/admin/resellers`	All resellers with countries and pools.
`PUT`	`/admin/resellers/{id}/countries`	Set a reseller's countries, each with `country_code`, `wholesale_mwk` and `wholesale_usd`.
`POST`	`/admin/resellers/{id}/credit`	Add SMS to a reseller's pool: `country_code`, `sms`, `idempotency_key`, optional `amount`, `currency`, `reference`, `note`.
`GET`	`/admin/pricing/countries`	Every country with its price and on or off.
`PUT`	`/admin/pricing/countries/{cc}`	`enabled`, `price_mwk`, `price_usd`.
`GET`	`/admin/topups`	Direct clients' top-up requests.
`POST`	`/admin/topups/{id}/approve`	Approve. Optional `note`.
`POST`	`/admin/topups/{id}/reject`	Reject. Optional `note`.
`GET`	`/admin/ledger`	Every SMS movement.
`POST`	`/admin/ledger/{id}/settle`	Close a `reconcile` entry: `outcome` (`applied` or `failed`) and a `note`.
`GET`	`/admin/audit`	Audit log.
`GET`	`/admin/upstream`	Upstream settings (never the password), whether they are complete, and the live status.
`POST`	`/admin/upstream/sync`	Make the gateway match the upstream settings again.

Admins can call the reseller endpoints for one reseller by adding ?reseller_id=....

Public

Method	Path	What it does
`GET`	`/health`	Service health.
`GET`	`/public/countries`	The African countries the platform knows.
`GET`	`/public/pricing`	Public price list per country. No sign in needed.

Internal (server to server)

These need the X-Internal-Key header and are only for SMS YANU's own services.

Method	Path	What it does
`POST`	`/internal/credit`	A confirmed payment from the account service. Credits a bind or a reseller pool once per `reference`.
`POST`	`/internal/debit`	Reverses a credit by `reference`.
`GET`	`/internal/firewall/allowlist`	Plain-text list of allowed IPs for the server firewall.