Retrieve Messages

Query and retrieve message details, history, and delivery status.

List Messages

Get a paginated list of messages with optional filtering.

Endpoint

GET /api/v1/messages

Authentication

Requires API Key via X-API-Key header.

Query Parameters

Parameter	Type	Required	Description
`channel`	string	No	Filter by channel: `sms`, `whatsapp`, `email`, `voice`
`status`	string	No	Filter by status: `queued`, `sent`, `delivered`, `failed`
`startDate`	string	No	ISO 8601 date (e.g., `2025-11-01T00:00:00Z`)
`endDate`	string	No	ISO 8601 date (e.g., `2025-11-30T23:59:59Z`)
`page`	number	No	Page number (default: 1)
`limit`	number	No	Results per page (default: 50, max: 100)

Try It Now

List Messages

API Key (required to test):

Your API key is stored locally and never sent to our servers. Get an API key →

Example Requests

cURLNode.jsPythonPHP

bash

# Get all messages
curl "https://api.yebolink.com/api/v1/messages" \
  -H "X-API-Key: ybk_live_your_api_key"

# Filter by channel and status
curl "https://api.yebolink.com/api/v1/messages?channel=sms&status=delivered&page=1&limit=20" \
  -H "X-API-Key: ybk_live_your_api_key"

# Filter by date range
curl "https://api.yebolink.com/api/v1/messages?startDate=2025-11-01T00:00:00Z&endDate=2025-11-30T23:59:59Z" \
  -H "X-API-Key: ybk_live_your_api_key"

javascript

const getMessages = async (filters = {}) => {
  const params = new URLSearchParams(filters);

  const response = await fetch(
    `https://api.yebolink.com/api/v1/messages?${params}`,
    {
      headers: {
        'X-API-Key': process.env.YEBOLINK_API_KEY
      }
    }
  );

  return await response.json();
};

// Usage examples
const allMessages = await getMessages();

const smsMessages = await getMessages({
  channel: 'sms',
  status: 'delivered',
  page: 1,
  limit: 20
});

const recentMessages = await getMessages({
  startDate: '2025-11-01T00:00:00Z',
  endDate: '2025-11-30T23:59:59Z'
});

python

import os
import requests
from typing import Optional

def get_messages(
    channel: Optional[str] = None,
    status: Optional[str] = None,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    page: int = 1,
    limit: int = 50
):
    params = {
        'page': page,
        'limit': limit
    }

    if channel:
        params['channel'] = channel
    if status:
        params['status'] = status
    if start_date:
        params['startDate'] = start_date
    if end_date:
        params['endDate'] = end_date

    response = requests.get(
        'https://api.yebolink.com/api/v1/messages',
        headers={'X-API-Key': os.environ.get('YEBOLINK_API_KEY')},
        params=params
    )

    return response.json()

# Usage
all_messages = get_messages()
sms_messages = get_messages(channel='sms', status='delivered')

php

<?php
function getMessages($filters = []) {
    $params = http_build_query(array_filter($filters));
    $url = "https://api.yebolink.com/api/v1/messages?$params";

    $curl = curl_init();

    curl_setopt_array($curl, [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . getenv('YEBOLINK_API_KEY')
        ]
    ]);

    $response = curl_exec($curl);
    curl_close($curl);

    return json_decode($response, true);
}

// Usage
$allMessages = getMessages();
$smsMessages = getMessages([
    'channel' => 'sms',
    'status' => 'delivered',
    'limit' => 20
]);
?>

Response

json

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "workspace_id": "workspace-id",
        "channel": "sms",
        "recipient": "+1234567890",
        "content": {
          "text": "Hello from YeboLink!"
        },
        "status": "delivered",
        "credits_used": 1,
        "provider_message_id": "SM1234567890",
        "error_message": null,
        "metadata": {
          "user_id": "12345",
          "purpose": "notification"
        },
        "created_at": "2025-11-02T12:00:00Z",
        "updated_at": "2025-11-02T12:01:30Z"
      }
    ],
    "pagination": {
      "total": 150,
      "page": 1,
      "pages": 8,
      "limit": 20
    }
  }
}

Get Single Message

Retrieve details for a specific message by ID.

Endpoint

GET /api/v1/messages/:id

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Message ID (UUID)

Example Requests

cURLNode.jsPythonPHP

bash

curl "https://api.yebolink.com/api/v1/messages/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: ybk_live_your_api_key"

javascript

const getMessage = async (messageId) => {
  const response = await fetch(
    `https://api.yebolink.com/api/v1/messages/${messageId}`,
    {
      headers: {
        'X-API-Key': process.env.YEBOLINK_API_KEY
      }
    }
  );

  if (!response.ok) {
    throw new Error('Message not found');
  }

  return await response.json();
};

// Usage
const message = await getMessage('550e8400-e29b-41d4-a716-446655440000');
console.log('Status:', message.data.message.status);

python

def get_message(message_id: str):
    response = requests.get(
        f'https://api.yebolink.com/api/v1/messages/{message_id}',
        headers={'X-API-Key': os.environ.get('YEBOLINK_API_KEY')}
    )

    if response.status_code == 404:
        raise Exception('Message not found')

    return response.json()

# Usage
message = get_message('550e8400-e29b-41d4-a716-446655440000')
print(f"Status: {message['data']['message']['status']}")

php

<?php
function getMessage($messageId) {
    $curl = curl_init();

    curl_setopt_array($curl, [
        CURLOPT_URL => "https://api.yebolink.com/api/v1/messages/$messageId",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . getenv('YEBOLINK_API_KEY')
        ]
    ]);

    $response = curl_exec($curl);
    $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);

    if ($httpCode === 404) {
        throw new Exception('Message not found');
    }

    return json_decode($response, true);
}

// Usage
$message = getMessage('550e8400-e29b-41d4-a716-446655440000');
echo "Status: " . $message['data']['message']['status'];
?>

Response

json

{
  "success": true,
  "data": {
    "message": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspace_id": "workspace-id",
      "channel": "sms",
      "recipient": "+1234567890",
      "content": {
        "text": "Hello from YeboLink!"
      },
      "status": "delivered",
      "credits_used": 1,
      "provider_message_id": "SM1234567890",
      "error_message": null,
      "metadata": {
        "user_id": "12345",
        "purpose": "notification"
      },
      "created_at": "2025-11-02T12:00:00Z",
      "updated_at": "2025-11-02T12:01:30Z",
      "delivered_at": "2025-11-02T12:01:30Z"
    }
  }
}

Message Statuses

Status	Description
`queued`	Message is queued for sending
`sent`	Message sent to carrier/provider
`delivered`	Message successfully delivered
`failed`	Message delivery failed

Polling for Status Updates

Use Webhooks Instead

For real-time status updates, use webhooks instead of polling. Webhooks are more efficient and provide instant notifications.

If you must poll, implement exponential backoff:

javascript

const pollMessageStatus = async (messageId, maxAttempts = 10) => {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const message = await getMessage(messageId);
    const status = message.data.message.status;

    if (status === 'delivered' || status === 'failed') {
      return message;
    }

    // Exponential backoff: 1s, 2s, 4s, 8s, ...
    const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
    await new Promise(resolve => setTimeout(resolve, delay));
  }

  throw new Error('Timeout waiting for message status');
};

Error Responses

Message Not Found (404)

json

{
  "success": false,
  "error": "not_found",
  "message": "Message not found"
}

Invalid Date Format (400)

json

{
  "success": false,
  "error": "validation_error",
  "message": "Invalid date format. Use ISO 8601 format."
}

Use Cases

Track Delivery Rate

javascript

const getDeliveryRate = async (startDate, endDate) => {
  const messages = await getMessages({
    startDate,
    endDate,
    limit: 100
  });

  const total = messages.data.messages.length;
  const delivered = messages.data.messages.filter(
    m => m.status === 'delivered'
  ).length;

  return {
    total,
    delivered,
    rate: (delivered / total * 100).toFixed(2) + '%'
  };
};

Export Message History

javascript

const exportMessages = async (filters) => {
  let allMessages = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await getMessages({ ...filters, page, limit: 100 });
    allMessages = allMessages.concat(response.data.messages);

    hasMore = page < response.data.pagination.pages;
    page++;
  }

  return allMessages;
};

Monitor Failed Messages

javascript

const getFailedMessages = async () => {
  const response = await getMessages({
    status: 'failed',
    limit: 100
  });

  return response.data.messages.map(msg => ({
    id: msg.id,
    recipient: msg.recipient,
    error: msg.error_message,
    timestamp: msg.updated_at
  }));
};

Next Steps

Send Messages
Setup Webhooks - Real-time status updates
Error Handling - Understand error codes

Retrieve Messages ​

List Messages ​

Endpoint ​

Authentication ​

Query Parameters ​

Try It Now ​

List Messages

Example Requests ​

Response ​

Get Single Message ​

Endpoint ​

Parameters ​

Example Requests ​

Response ​

Message Statuses ​

Polling for Status Updates ​

Error Responses ​

Message Not Found (404) ​

Invalid Date Format (400) ​

Use Cases ​

Track Delivery Rate ​

Export Message History ​

Monitor Failed Messages ​

Next Steps ​

Retrieve Messages

List Messages

Endpoint

Authentication

Query Parameters

Try It Now

Example Requests

Response

Get Single Message

Endpoint

Parameters

Example Requests

Response

Message Statuses

Polling for Status Updates

Error Responses

Message Not Found (404)

Invalid Date Format (400)

Use Cases

Track Delivery Rate

Export Message History

Monitor Failed Messages

Next Steps