Status & priority

Track a message from the moment it's queued to final delivery, and control how quickly it's processed with priority settings. This page covers checking status, message history, retries, and the priority levels that trade off speed against cost.

Checking message status

Fetch the current status of a message by its id.

GET/messages/{id}
curl https://api.tryzend.com/messages/{id} \
  -H "x-api-key: YOUR_API_KEY"

{
  "id": "6884da240f0e633b7b979bff",
  "status": "delivered",
  "channel_used": "whatsapp",
  "to": "+233593152134",
  "body": "Your verification code is: 123456",
  "total_cost": 0.008,
  "delivery_attempts": [
    {
      "channel": "whatsapp",
      "status": "delivered",
      "attempted_at": "2024-01-15T10:30:00Z",
      "cost": 0.008
    }
  ],
  "created_at": "2024-01-15T10:29:55Z",
  "sent_at": "2024-01-15T10:30:00Z",
  "delivered_at": "2024-01-15T10:30:05Z"
}

The delivery_attempts array records each channel Zend tried, which is useful when you rely on channel fallback.

Status values

A message moves through these statuses over its lifetime:

StatusMeaning
pendingQueued and awaiting processing.
sentHanded off to the channel provider.
deliveredConfirmed delivered to the recipient.
failedDelivery failed on all attempted channels.

Message history

List past messages, filtering by status, channel, and paginating with limit and offset.

GET/messages
curl "https://api.tryzend.com/messages?limit=50&offset=0&status=delivered&channel=whatsapp" \
  -H "x-api-key: YOUR_API_KEY"

{
  "messages": [
    {
      "id": "6884da240f0e633b7b979bff",
      "status": "delivered",
      "channel_used": "whatsapp",
      "to": "+233593152134",
      "total_cost": 0.008,
      "created_at": "2024-01-15T10:29:55Z"
    }
  ],
  "total": 150,
  "page": 1,
  "pages": 3
}

Retrying a failed message

Requeue a failed message for another delivery attempt using its id.

PUT/messages/{id}/retry
curl -X PUT https://api.tryzend.com/messages/{id}/retry \
  -H "x-api-key: YOUR_API_KEY"

{
  "id": "6884da240f0e633b7b979bff",
  "status": "pending",
  "estimated_cost": 0.02,
  "message": "Message queued for retry"
}

Note

To be notified of status changes without polling, subscribe to webhooks.

Priority levels

Set a message's priority to control how quickly it's processed. Higher priority means faster processing.

PriorityDescriptionProcessing time
lowNon-urgent messages5-10 minutes
normalStandard messages1-2 minutes
highImportant messages30 seconds
urgentCritical messagesImmediate

Delivery priority

Alongside priority, delivery_priority tunes how Zend chooses a channel — optimizing for speed, cost, or reliability.

{
  "to": "+233593152134",
  "body": "URGENT: System outage detected",
  "preferred_channels": ["sms", "whatsapp"],
  "priority": "urgent",
  "delivery_priority": "speed"
}

Request fields

prioritystring
Processing priority: low, normal, high, or urgent.
delivery_prioritystring
Optimization goal when selecting a channel: speed, cost, or reliability.
PreviousSchedulingNext Errors & rate limits