Message Status

Check the delivery status of individual messages and batches.

Get message status

Retrieve the current delivery status of a single SMS message by its ID. Authenticates with an integration API key or JWT token.

GET /api/sms/status/{id}

Example

curl https://app.vendel.cc/api/sms/status/MESSAGE_ID \
  -H "X-API-Key: vk_your_api_key"

Response

{
  "id": "a1b2c3d4e5f6g7h",
  "batch_id": "x9y8z7w6v5u4t3s",
  "recipient": "+1234567890",
  "status": "delivered",
  "error_message": "",
  "device_id": "d3v1c31d000001",
  "created": "2024-01-15 10:30:00.000Z",
  "updated": "2024-01-15 10:30:05.000Z"
}

Get batch status

When you send to multiple recipients, the response includes a batch_id. Use this endpoint to retrieve the status of all messages in the batch, along with aggregate counts. 

GET /api/sms/batch/{batchId}

Example

curl https://app.vendel.cc/api/sms/batch/BATCH_ID \
  -H "X-API-Key: vk_your_api_key"

Response

{
  "batch_id": "x9y8z7w6v5u4t3s",
  "total": 3,
  "status_counts": {
    "delivered": 2,
    "sent": 1
  },
  "messages": [
    {
      "id": "msg001",
      "recipient": "+1234567890",
      "status": "delivered",
      "error_message": "",
      "created": "2024-01-15 10:30:00.000Z",
      "updated": "2024-01-15 10:30:05.000Z"
    },
    {
      "id": "msg002",
      "recipient": "+0987654321",
      "status": "delivered",
      "error_message": "",
      "created": "2024-01-15 10:30:00.000Z",
      "updated": "2024-01-15 10:30:06.000Z"
    },
    {
      "id": "msg003",
      "recipient": "+1122334455",
      "status": "sent",
      "error_message": "",
      "created": "2024-01-15 10:30:00.000Z",
      "updated": "2024-01-15 10:30:04.000Z"
    }
  ]
}

Authentication

Both endpoints accept either an integration API key or a JWT token:

# API key
-H "X-API-Key: vk_your_api_key"

# JWT token
-H "Authorization: Bearer YOUR_JWT_TOKEN"

Status values

Status Description
pending Created, no device assigned yet
assigned Device assigned, push notification sent
sending Being processed by device
sent Sent by device
delivered Confirmed delivered
failed Failed to send
received Incoming SMS from an external sender

Errors

// 401 Unauthorized
{
  "message": "Authentication required."
}

// 404 Not Found - message or batch does not exist (or belongs to another user)
{
  "message": "Message not found."
}

PocketBase collections API

You can also query messages directly via PocketBase's standard list API. This gives you access to filtering, sorting, and pagination over the sms_messages collection. 

GET /api/collections/sms_messages/records

Query parameters

Parameter Description
filter PocketBase filter syntax (e.g., status="sent")
sort Sort field (e.g., -created for newest first)
page Page number (default: 1)
perPage Results per page (default: 30, max: 500)

Example

curl "https://app.vendel.cc/api/collections/sms_messages/records?filter=status='delivered'&sort=-created&perPage=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Related