API reference

Base URL https://sms.xash.network/api/v1 · Authorization: Bearer <key> · JSON in, JSON out.

POST /messages

Send a batch, or price one with dry_run.

Request

Field	Type	Notes
channel	string	sms. (telegram, whatsapp are reserved.)
to	string or array	E.164 numbers, +263 or +27 only. Up to 1,000.
body	string	Up to 5 segments.
reference	string, optional	Your label, up to 64 characters. Returned on lookups.
dry_run	bool, optional	Price without sending or billing.

Headers: optionally Idempotency-Key (6–64 chars) to make retries safe.

Response 202

{
  "batch_id": "9d2f7c1e-...",
  "accepted": 2,
  "rejected": [{ "to": "+14155550123", "code": "UNSUPPORTED_DESTINATION" }],
  "segments": 1,
  "total_cost": "0.0600",
  "currency": "USD",
  "balance_after": "4.94"
}

Dry runs answer 200 with "dry_run": true and no batch_id or balance_after.

GET /batches/{id}

The batch plus every recipient's outcome.

{
  "data": {
    "batch_id": "9d2f7c1e-...",
    "status": "completed",
    "channel": "sms",
    "reference": "outage-2026-08-30",
    "recipients": 2,
    "segments": 1,
    "total_cost": "0.0600",
    "refunded": "0.0000",
    "currency": "USD",
    "created_at": "2026-08-30T17:00:04+00:00",
    "messages": [
      {
        "message_id": "b3e6a9d0-...",
        "to": "+263771234567",
        "country": "ZW",
        "status": "delivered",
        "segments": 1,
        "cost": "0.0400",
        "sent_at": "2026-08-30T17:00:09+00:00",
        "delivered_at": "2026-08-30T17:00:31+00:00"
      }
    ]
  }
}

GET /messages/{id}

One message, same shape as the entries in a batch's messages array, plus failure_reason and refunded_at when set.

GET /balance

{ "balance": "4.94", "currency": "USD" }

GET /pricing

The live price book, coming-soon rows included.

{
  "data": [
    { "channel": "sms", "country": "ZW", "price_usd": "0.0190", "status": "coming_soon" },
    { "channel": "sms", "country": "ZW", "price_usd": "0.0400", "status": "active" },
    { "channel": "sms", "country": "ZA", "price_usd": "0.0200", "status": "active" }
  ],
  "currency": "USD"
}

Limits

• 60 requests per minute per account.
• 1,000 recipients per call.
• 5 segments per message.
• Errors are listed on the errors page, all in the same envelope.