Send an SMS immediately

Prepare the fields

POST /api/sms/v2/messages/ without send_at creates an immediate submission. The key needs sms.send. Add delivery.read for tracking.

Scroll horizontally if needed. Keyboard: Tab, then the left and right arrow keys.

Field	Rule
to	Madagascar mobile number in +2613XXXXXXXX format, without spaces
text	Non-empty text, limited to two segments
sender_name	Optional; an active name available to your organization

Unknown fields are rejected. Validating the number format does not prove it is active. The text field’s 320-character ceiling does not mean every text of that length is accepted: encoding and segments still determine admission.

Submit one business operation

Set BEFIANA_SMS_API_KEY as in the quickstart. Replace the number with your authorized recipient and ACME with an active sender in your organization. Omit the entire field to use the default selection.

curl --include --request POST 'https://api.befiana.cloud/api/sms/v2/messages/' \
  --header "Authorization: Bearer $BEFIANA_SMS_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-2026-0002-confirmation' \
  --data '{"to":"+261340000000","text":"Your order is confirmed.","sender_name":"ACME"}'

An idempotency key is required. Create and save it before submitting. If the connection drops, reuse the same body and key; a new key creates a new operation.

Interpret HTTP 201

The 201 response confirms provider acceptance. It contains id, to, sender_name, segments, status, send_at and delivery_time. The creation status is accepted and send_at is null.

The Location header supplies the relative path for message lookups. See the quickstart JSON response for a complete example.

Credits are accounted for according to segment count without waiting for delivery confirmation. Use the balance returned by the service; a delivery receipt is not a credit statement.

Track and retry

GET /api/sms/v2/messages/{message_id}/ provides the current status. Replaying the POST returns the original creation response even after the status changes.

Interpret a 409 using its code. A 502 with an unknown provider outcome does not mean “not sent”. Save message_id when supplied and consult errors, idempotency and recipes.

Send later or to multiple recipients

• For a future message, use scheduling with send_at and sms.schedule.
• For multiple recipients sharing a text and future timestamp, use a batch.