SMS fallback & priority

Make sure important messages get through. Zend can automatically fall back to WhatsApp or voice when SMS can't be delivered, let you tune the delivery trade-off between cost, speed, and reliability, and schedule sends for later — all on the same POST /messages request.

POST/messages

Automatic fallback

Set fallback_enabled to true and list the channels to try, in order, in preferred_channels. Zend attempts each channel in turn until the message is delivered.

curl -X POST https://api.tryzend.com/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+233593152134",
    "body": "Important notification: Your order has been shipped!",
    "preferred_channels": ["sms", "whatsapp"],
    "fallback_enabled": true,
    "delivery_priority": "reliability"
  }'

In this example Zend tries SMS first; if it fails, it falls back to WhatsApp.

Request fields

preferred_channelsstring[]required
Ordered list of channels to attempt, e.g. ["sms", "whatsapp"] or ["sms", "voice"]. The first channel is tried first.
fallback_enabledboolean
When true, Zend advances to the next channel in preferred_channels if the current one fails. Defaults to false.
delivery_prioritystring
Optimization strategy: cost, speed, or reliability.

Note

The channel that actually delivered a message is reported as channel_used when you check status. See SMS delivery & webhooks.

Delivery priority

delivery_priority tells Zend how to optimize when choosing and ordering channels:

PriorityOptimizes forUse when
costLowest priceNon-urgent, high-volume messages like statements or receipts
speedFastest deliveryTime-sensitive alerts where latency matters
reliabilityHighest chance of deliveryCritical messages such as OTPs and shipping updates

Pair reliability with fallback_enabled for messages that must arrive:

{
  "to": "+233593152134",
  "body": "Your verification code is: 123456",
  "preferred_channels": ["sms", "whatsapp", "voice"],
  "fallback_enabled": true,
  "delivery_priority": "reliability"
}

Message priority

priority controls how quickly a message is picked up from the queue for processing — independent of delivery_priority, which governs channel selection.

{
  "to": "+233593152134",
  "body": "URGENT: System maintenance in 30 minutes",
  "preferred_channels": ["sms"],
  "priority": "urgent"
}

Levels, from lowest to highest: low, normal, high, urgent.

Scheduling

Set scheduled_for to an ISO 8601 timestamp to send a message at a specific time instead of immediately.

{
  "to": "+233593152134",
  "body": "Reminder: Your appointment is in 1 hour",
  "preferred_channels": ["sms"],
  "scheduled_for": "2024-01-15T13:00:00Z"
}

Request fields

prioritystring
Queue priority: low, normal, high, or urgent. Defaults to normal.
scheduled_forstring
ISO 8601 timestamp (UTC) for when the message should be sent. Omit to send immediately.

Cost optimization

To minimize spend, optimize for cost and turn fallback off so a message is never re-attempted on a more expensive channel.

{
  "to": "+233593152134",
  "body": "Your monthly statement is ready",
  "preferred_channels": ["sms"],
  "delivery_priority": "cost",
  "fallback_enabled": false
}

Tips for keeping SMS costs down:

  • Disable fallback for non-critical messages so they stay on SMS only.
  • Keep messages under 160 characters — each additional part is billed at the full SMS rate.
  • Use delivery_priority: "cost" so Zend favors the cheapest viable path.
  • Reserve reliability and multi-channel fallback for messages that genuinely justify the extra cost, like OTPs.

Next steps

PreviousOverviewNext Delivery & webhooks