Skip to main content

​
Overview

Retrieve a paginated list of SMS messages sent from your project. This endpoint supports filtering by date range and pagination to help you manage and analyze your message history.

​
Endpoint

curl --request GET \
  "https://sms.lamah.com/api/sms/messages?page=1&per_page=20&from=2024-01-01&to=2024-01-31" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Accept: application/json"

​
Request Parameters

ParameterTypeRequiredDescription
pageinteger❌Page number for pagination (default: 1)
per_pageinteger❌Number of messages per page (default: 20, max: 100)
fromstring❌Start date for filtering (YYYY-MM-DD format)
tostring❌End date for filtering (YYYY-MM-DD format)

​
Parameter Details

The page number for pagination.
  • Default: 1
  • Minimum: 1
  • Type: Positive integer
Number of messages to return per page.
  • Default: 20
  • Minimum: 1
  • Maximum: 100
  • Recommended: 20-50 for optimal performance
Start date for filtering messages.
  • Format: YYYY-MM-DD (e.g., “2024-01-01”)
  • Timezone: UTC
  • Inclusive: Messages from this date are included
End date for filtering messages.
  • Format: YYYY-MM-DD (e.g., “2024-01-31”)
  • Timezone: UTC
  • Inclusive: Messages up to this date are included

​
Response

​
Success Response (200 OK)

{
  "data": {
    "current_page": 1,
    "data": [
      {
        "short_message": "تم تأكيد موعد معاينة العقار غدًا الساعة 5 مساءً في قرقارش، طرابلس.",
        "message_type": "sms",
        "send_type": "single",
        "contact_group_id": null,
        "message_consumption": 1,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z",
        "receiver": [
          {
            "number": "00218912345678",
            "sent_at": "2024-01-15T10:30:02Z",
            "delivered_at": "2024-01-15T10:30:15Z",
            "status": "delivered",
            "delivery_report": null,
            "created_at": "2024-01-15T10:30:00Z",
            "updated_at": "2024-01-15T10:30:15Z"
          }
        ]
      }
    ],
    "per_page": 20,
    "last_page": 5,
    "total": 95
  }
}

​
Response Fields

FieldTypeDescription
dataobjectLaravel paginator with message records

​
Message Object Fields

FieldTypeDescription
short_messagestringMessage content
message_typestringAlways sms for SMS messages
send_typestringsingle or multiple
contact_group_idstringContact group UUID if applicable
message_consumptionintegerSMS parts consumed for this message
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp
receiverarrayList of receipt objects for each recipient

​
Pagination Object Fields

FieldTypeDescription
current_pageintegerCurrent page number
per_pageintegerMessages per page
last_pageintegerTotal number of pages
totalintegerTotal number of messages matching filters

​
Summary Object Fields

FieldTypeDescription
total_costnumberTotal cost of all messages in the filtered results
total_messagesintegerTotal number of messages
deliveredintegerNumber of delivered messages
failedintegerNumber of failed messages
pendingintegerNumber of pending messages

​
Error Responses

​
400 Bad Request

{
  "error": "Invalid date format",
  "code": "INVALID_DATE_FORMAT",
  "details": {
    "field": "from",
    "value": "2024/01/01",
    "expected_format": "YYYY-MM-DD"
  }
}

​
401 Unauthorized

{
  "error": "Invalid API token",
  "code": "UNAUTHORIZED"
}

​
Pagination Examples

​
Basic Pagination

const getAllMessages = async () => {
  let allMessages = [];
  let currentPage = 1;
  let hasNextPage = true;
  
  while (hasNextPage) {
    const url = new URL('https://sms.lamah.com/api/sms/messages');
    url.searchParams.set('page', String(currentPage));
    url.searchParams.set('per_page', '50');
    const response = await fetch(url, {
      headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
    });
    
    const data = await response.json();
    allMessages = allMessages.concat(data.data.data);
    
    hasNextPage = data.data.current_page < data.data.last_page;
    currentPage++;
    
    console.log(`Fetched page ${currentPage - 1}, total messages: ${allMessages.length}`);
  }
  
  return allMessages;
};

​
Date Range Filtering

const getMessagesForMonth = async (year, month) => {
  const from = `${year}-${month.toString().padStart(2, '0')}-01`;
  const to = `${year}-${month.toString().padStart(2, '0')}-31`;
  
  const response = await fetch('https://sms.lamah.com/api/sms/messages', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      page: 1,
      per_page: 100,
      from: from,
      to: to
    })
  });
  
  const data = await response.json();
  console.log(`Found ${data.summary.total_messages} messages for ${year}-${month}`);
  console.log(`Total cost: $${data.summary.total_cost}`);
  
  return data;
};

// Get messages for January 2024
const januaryMessages = await getMessagesForMonth(2024, 1);

​
Use Cases

Message History

Review all messages sent from your project

Cost Analysis

Analyze messaging costs over time periods

Delivery Reports

Generate delivery reports for specific date ranges

Audit Trail

Maintain compliance records of all communications

​
Best Practices

Pagination: Use reasonable page sizes (20-50) to balance performance and data transfer.
Date Ranges: Avoid very large date ranges without pagination to prevent timeouts.

​
Performance Tips

  1. Use date filters to limit the result set
  2. Implement pagination for large datasets
  3. Cache results when appropriate
  4. Use appropriate page sizes based on your use case

​
Error Handling

const getMessages = async (filters = {}) => {
  try {
    const url = new URL('https://sms.lamah.com/api/sms/messages');
    Object.entries(filters).forEach(([k, v]) => url.searchParams.set(k, String(v)));
    const response = await fetch(url, { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } });

    if (!response.ok) {
      const error = await response.json();
      console.error('Failed to get messages:', error.error);
      return null;
    }

    const data = await response.json();
    return data;
    
  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
};