# BulkSMS API

> Send SMS to Tanzanian and international numbers under your own approved sender ID (BulkSMS by OASIS TECH, Dar es
> Salaam). REST + JSON over HTTPS, Bearer API keys, pay-as-you-go credits (1 credit per SMS part per recipient).

Essentials for writing an integration:

- Base URL `https://bulksms.oasistech.co.tz`, version prefix `/v1` (`/api/...` is the same endpoint).
- Send: `POST /v1/sms` with `Authorization: Bearer <key>`, `Content-Type: application/json` and body
  `{"to": "+255712345678", "sender": "BULK SMS TZ", "message": "..."}`. There is no `/sms/send`.
- Outcome by HTTP status: 200 `sent` · 202 `pending` (most likely sent — do not resend) or `scheduled` · 502 `failed`
  (not charged). Errors are `{"error": "..."}` with 400/401/402/403/409/415/422/429.
- Allow a 180-second client timeout. Over 10,000 recipients the send is answered at once (202, `status: processing`,
  `background: true`, no per-recipient list) and goes out right after; follow `sms_log_id` in `GET /v1/logs`.
- Always send an `Idempotency-Key` (1–64 visible ASCII characters, new key per message). Retrying with the same key
  replays the original answer (`idempotent_replay: true`); the same key with a different request answers 422.
- Scopes: `messages:send` (send), `messages:read` (`GET /v1/logs`), `balance:read` (`GET /v1/balance`).
- Account needs approved KYC, an approved sender ID and credits before sending.

## Docs

- [Complete API reference for LLMs and developers](https://bulksms.oasistech.co.tz/llms-full.txt): every endpoint,
  field, response, error, idempotency rule, webhook and recipe in one Markdown file
- [API reference (web page)](https://bulksms.oasistech.co.tz/docs)
- [OpenAPI 3 specification](https://bulksms.oasistech.co.tz/openapi.json)
- [Postman collection](https://bulksms.oasistech.co.tz/postman.json)

## Optional

- [Interactive OpenAPI viewer](https://bulksms.oasistech.co.tz/openapi)
- [Support](https://bulksms.oasistech.co.tz/support)