Vorbal API Documentation

A Message represents one outbound SMS. The API tracks sending progress separately from delivery:

sending_status reports the latest confirmed sending milestone: queued or sent.
delivery_status reports what the platform knows about delivery: pending, delivered, failed, or unknown.

queued means that the SMS provider accepted the message into its queue.

After the provider switch described in the API changelog, newly accepted messages stay queued/pending until delivery monitoring closes as unknown after 72 hours. Confirmed sending and delivery reports require further integration work. Handle unknown explicitly and do not resend an SMS automatically because delivery is unconfirmed.

Sending and delivery evidence can arrive independently. A delivery report can skip the intermediate sent milestone, so do not infer delivery from sending_status. unknown means that monitoring ended without conclusive delivery evidence. It does not mean that delivery failed.

Use Get message status to retrieve the latest snapshot after a missed event.

Methods

List messages

List messages returns retained SMS messages, newest first.

Lifecycle events

The 202 Accepted response confirms acceptance and includes message_uuid and sending_status: "queued". Acceptance does not emit a webhook.

Message events report subsequent sending milestones and final observed delivery outcomes. Every event contains aud, event, message_uuid, channel, direction: "outbound", and an RFC 3339 UTC timestamp.

Provider evidence can skip message.sent. Process each event independently, and use GET /v1/messages/{message_uuid} to reconcile the latest state after a missed event.

message.sent

Fires when the provider reports onward submission. A later delivery report can arrive without this intermediate event. The event also contains from and to.

Field	Type	Description
`aud`	string	Application UUID that identifies the intended recipient. Required
`event`	string	Always `"message.sent"`. Required
`message_uuid`	string	Stable Message identifier. Required
`channel`	string	Always `"sms"`. Required
`direction`	string	Always `"outbound"`. Required
`from`	string	Authorized SMS identity. Required
`to`	string	Destination in canonical E.164 format. Required
`timestamp`	string	RFC 3339 / ISO 8601 UTC event time with a `Z` suffix. Required

{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "message.sent",
  "message_uuid": "msg_550e8400-e29b-41d4-a716-446655440000",
  "channel": "sms",
  "direction": "outbound",
  "from": "Example",
  "to": "+972500000000",
  "timestamp": "2026-08-28T12:00:02.000Z"
}

message.delivery_status

Fires when delivery succeeds, fails conclusively, or remains unknown after monitoring ends.

Field	Type	Description
`aud`	string	Application UUID that identifies the intended recipient. Required
`event`	string	Always `"message.delivery_status"`. Required
`message_uuid`	string	Stable Message identifier. Required
`channel`	string	Always `"sms"`. Required
`direction`	string	Always `"outbound"`. Required
`delivery_status`	string	`delivered`, `failed`, or `unknown`. Required
`timestamp`	string	RFC 3339 / ISO 8601 UTC event time with a `Z` suffix. Required

An SMS delivery event has this shape:

{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "message.delivery_status",
  "message_uuid": "msg_550e8400-e29b-41d4-a716-446655440000",
  "channel": "sms",
  "direction": "outbound",
  "delivery_status": "delivered",
  "timestamp": "2026-08-28T12:00:08.000Z"
}

unknown means that the 72-hour monitoring window ended without conclusive evidence. It is terminal for platform monitoring and does not mean delivery failed.

All webhook deliveries use the shared authentication, retry, deduplication, and ordering behavior described in Event delivery.