API reference

Send a message

The headline endpoint. Returns 202 immediately; the message is processed by a background worker within ~50ms.

POST/v1/messages

Authenticate with X-Raven-Key: rk_live_.... The tenant is implied by the key.

Request

curl

curl -X POST https://api-raven-cloud.autotribes.app/v1/messages \
  -H "X-Raven-Key: rk_live_a3f7b2c1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+254722000000",
    "body": "Hi Ada, your order #AC-1042 is on its way."
  }'

Body parameters

Field	Type	Notes
`channel`	required	`sms` · `email` · `push` · `whatsapp`
`to`	required	E.164 phone for SMS, or email address for email. 1–200 chars.
`body`	SMS · required	1–4096 chars. Auto-segments at 160 chars per SMS.
`from`	email · required	RFC5322 from address, e.g. `noreply@mail.acme.co.ke`
`subject`	email · required	Email subject line
`bodyHtml`	email · recommended	HTML email body
`bodyText`	email · recommended	Plain-text fallback. Improves deliverability when sent alongside `bodyHtml`.
`externalId`	optional	Your own reference ID

Response

202 Accepted

json

{
  "id": "8ad4f7c2-9e3b-4a1c-bc2f-1d8e3a9b7c4d",
  "status": "queued",
  "channel": "sms",
  "to": "+254722000000",
  "enqueuedAt": "2026-05-01T10:23:18.114Z"
}

ASYNC BY DESIGN

We return 202 the moment the message is persisted and queued. The actual provider call happens in a worker, usually within 50ms. Use GET /v1/admin/messages/:id to check final status, or configure provider webhooks for real-time delivery events.

Errors

Status	When
`400`	Missing required field, or no provider configured for the channel
`401`	Invalid or expired API key
`403`	Tenant suspended
`409`	Idempotency key already used with a different payload
`429`	Rate limit hit — backoff per `Retry-After`