Send an SMS

POST /v1/messages/send sends one SMS to a Malawi number. To send to many numbers, use send-bulk.

POST https://api.smsyanu.com/v1/messages/send
Authorization: Bearer yanu_live_YOUR_KEY
Content-Type: application/json

Request body

Field	Type	Required	Meaning
`to`	string	Yes	Malawi number, for example `+265990000000`.
`text`	string	Yes	The message. Long text is split into segments. See encoding.
`sender_id`	string	No	Sender name or number, up to 11 letters and digits. It must be approved on your account. Without it, the route default is used.
`schedule_mode`	string	No	`now` (default) or `scheduled`.
`scheduled_at`	string	When scheduled	ISO 8601 time with a time zone. At least 5 minutes and at most 7 days ahead.
`flash`	boolean	No	Show on the screen without saving on the phone. Same price.
`validity_period`	integer	No	Minutes (1 to 4320) the network keeps trying before the message expires.

{
  "to": "+265990000000",
  "text": "Your order 1042 is ready for collection.",
  "sender_id": "YANU"
}

Response

HTTP 200:

{
  "id": "6f1c2b9e-1d2a-4c55-9a0e-2b7f0c1d3e4f",
  "status": "submitted",
  "segments": 1,
  "encoding": "GSM-7",
  "recipients": 1,
  "price_per_sms": 20.0,
  "cost": 20.0,
  "cost_currency": "MWK",
  "balance_after": 4980.0,
  "scheduled_at": null
}

Field	Meaning
`id`	Message id. Use it to look up the message and to match webhooks.
`status`	`submitted` (sent to the network), `scheduled`, or `failed`.
`segments`	Number of parts. You pay per segment.
`encoding`	`GSM-7` or `UCS-2`.
`cost`, `cost_currency`	What your balance was charged.
`balance_after`	Your balance after this message.

SMS to Malawi costs K20 per segment. Your dashboard shows the price for your account.

Send each message once

Network problems can make you retry a request. Add an Idempotency-Key header with a unique value per message, for example your order id:

Idempotency-Key: order-1042-ready

If you send the same key again, you get the first result back. You are not charged twice.

Message status

Status	Meaning
`queued`	Accepted, waiting to go out.
`scheduled`	Waiting for its scheduled time.
`submitted`	Handed to the network.
`delivered`	The phone received it.
`failed`	Not delivered. If it never left SMS YANU, the charge is refunded.
`cancelled`	A scheduled message you cancelled.

Rules that apply

Malawi numbers only. Other countries get HTTP 422 code destination_not_allowed.
Your balance must cover the full message. If not, HTTP 402 code insufficient_balance.
A number that replied STOP to you is refused with HTTP 403 code recipient_opted_out.
The default rate limit is 20 requests per second per client. Above it, HTTP 429 code rate_limited.

Price before you send

POST /v1/messages/rate takes to and text and returns the encoding, segment count and total cost. Nothing is sent and nothing is charged.

To be confirmed

The send endpoint exists in the current code. The exact response fields, the encoding labels, the optional fields and the rate limit may change before launch. The destination_not_allowed rule is part of the agreed contract.