Message

A Message represents one outbound SMS. The API tracks two independent state dimensions:

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

unknown means that monitoring ended without conclusive delivery evidence. It does not mean that delivery failed. Provider evidence can also skip the intermediate sent milestone, so do not infer delivery from sending_status.

Use Get message status to reconcile state after a missed event. Treat the returned resource as the latest snapshot.

Methods

• Send an outbound message
• List messages
• Get message status

Lifecycle events

Message events report provider sending milestones and the final platform-observed recipient-delivery outcome. All events contain aud, event, message_uuid, channel: "sms", direction: "outbound", and an RFC 3339 UTC timestamp.

Send an outbound message produces the Message that these events describe.

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.queued

Fires after the SMS provider positively acknowledges queueing and the platform persists the Message. This is the provider’s queue, not an internal platform queue. The event also contains from and to.

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

message.sent

Fires only when the provider reports positive evidence that it sent the SMS onward. A later delivery report can arrive without this intermediate event. The event also contains from and to.

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

message.delivery_status

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

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

unknown means monitoring ended without conclusive evidence. It is terminal, but it is not a delivery failure.

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