SMS outbox (provider-agnostic)

Use this flow when callers should not embed a catalog slug in the URL. You enqueue a request; any installed manual SMS app for the organization can claim and send it (first successful claim wins). Optional preferred_provider_slug pins routing to one catalog slug when multiple SMS apps are installed.

Behavior

• Queue — POST stores one outbound SMS per organization. Payload fields match the slugged send API (mobile, message, optional sender, datetime, preferred_provider_slug, idempotency_key, meta).
• Routing — Any installed manual SMS integration for the org may pick up a queued item. The first successful send finalizes the request. Optional preferred_provider_slug limits routing when several SMS apps are installed.
• Lifecycle — dispatch_status moves from pending to sending, then to sent or failed. A long‑stalled in‑progress send may end as dispatch_timeout.
• Retention — Completed rows (sent / failed) are removed after the server’s configured retention period. Old requests that were never dispatched may also be removed; do not rely on IDs as permanent audit keys.

Base path

/api/v1/sms/outbox

Enqueue

POST /api/v1/sms/outbox
Authorization: Bearer <token>
Content-Type: application/json

{
  "mobile": "966501234567",
  "message": "Your order is ready",
  "sender": "MyBrand",
  "datetime": "",
  "preferred_provider_slug": "",
  "idempotency_key": "order-123-notify",
  "meta": { "order_id": "123" }
}

Response:

{
  "id": "r…",
  "dispatch_status": "pending",
  "idempotent_replay": false
}

idempotency_key is optional; when set, duplicate enqueues for the same org return the existing row (idempotent_replay: true) with the current dispatch_status.

Poll status

GET /api/v1/sms/outbox/{id}
Authorization: Bearer <token>

Returns the queued request: dispatch_status (pending, sending, sent, failed), provider_slug, claimed_organization_app_id, response (provider JSON), error_message, timestamps, etc.

When to use slugged SMS providers API

• Outbox — integrations, backends, or clients that should not hard-code mora-sms vs twilio-sms.
• SMS providers API — operator UIs that already know which installed app to hit, or when you need balance, sender list, CSV bulk, or templates tied to a specific provider.

OpenAPI

The SMS outbox tag lives in the bundled spec: Swagger JSON or Swagger UI on your Linkit host.