Overview Retrieve detailed information about a specific SMS message, including per-recipient delivery status and related metadata. This endpoint is useful for tracking message delivery and debugging issues.
Endpoint curl --request GET \ "https://sms.lamah.com/api/sms/messages/a3a7b9a2-9d3f-4a7e-9b4e-13b1e9b1f2aa?message_id=a3a7b9a2-9d3f-4a7e-9b4e-13b1e9b1f2aa" \ --header "Authorization: Bearer YOUR_API_TOKEN"
Path Parameters Parameter Type Required Description message_idstring (UUID) ✅ The unique identifier of the message
Query Parameters Parameter Type Required Description message_idstring (UUID) ✅ UUID of the message (same as path parameter)
The message_id is required both in the URL path and as a query parameter for additional validation.
Response Success Response (200 OK) [ { "short_message" : "تم تأكيد موعد معاينة العقار غدًا الساعة 5 مساءً في قرقارش، طرابلس." , "message_type" : "sms" , "send_type" : "single" , "contact_group_id" : null , "message_consumption" : 1 , "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" } ] } ] Response Fields Field Type Description short_messagestring The message content message_typestring Always sms for SMS messages send_typestring single or multiplecontact_group_idstring Contact group UUID if applicable message_consumptioninteger SMS parts consumed for this message receiverarray List of receipt objects (one per recipient)
Receipt Status Values Status Description pendingMessage is queued for sending sentMessage has been sent to the carrier deliveredMessage has been delivered to the recipient failedMessage delivery failed
Receipt Fields Field Type Description numberstring Recipient phone number sent_atstring When the message was sent delivered_atstring When the message was delivered statusstring Delivery status for this recipient delivery_reportstring Raw delivery report if available
Error Responses 404 Not Found { "message" : "Message not found" } 401 Unauthorized { "message" : "Unauthenticated." } 403 Forbidden { "message" : "Message does not belong to your project" } Message Status Tracking Status Flow Typical Timeline
pending (0-5 seconds): Message is queuedsent (5-30 seconds): Message sent to carrierdelivered (30 seconds - 5 minutes): Message delivered to device
Use Cases
Delivery Confirmation Confirm that important messages were delivered
Debugging Failed Messages Investigate why messages failed to deliver
Audit Trail Maintain records of all sent messages
Cost Tracking Track costs for individual messages
Polling for Status Updates Status Polling
Status Polling
const pollMessageStatus = async ( messageId , maxAttempts = 10 ) => { for ( let attempt = 1 ; attempt <= maxAttempts ; attempt ++ ) { try { const res = await fetch ( `https://sms.lamah.com/api/sms/messages/ ${ messageId } ?message_id= ${ messageId } ` , { headers: { 'Authorization' : 'Bearer YOUR_API_TOKEN' , 'Accept' : 'application/json' } }); const arr = await res . json (); const msg = Array . isArray ( arr ) ? arr [ 0 ] : arr ; const receivers = msg . receiver || []; const statuses = receivers . map ( r => r . status ); const allDelivered = statuses . length > 0 && statuses . every ( s => s === 'delivered' ); const anyFailed = statuses . some ( s => s === 'failed' || s === 'rejected' || s === 'expired' ); console . log ( `Attempt ${ attempt } : ${ JSON . stringify ( statuses ) } ` ); if ( allDelivered || anyFailed ) { console . log ( 'Final state reached' ); return msg ; } await new Promise ( r => setTimeout ( r , 5000 )); } catch ( e ) { console . error ( `Polling attempt ${ attempt } failed:` , e ); } } console . log ( 'Max polling attempts reached' ); return null ; }; // Usage const message = await pollMessageStatus ( 'a3a7b9a2-9d3f-4a7e-9b4e-13b1e9b1f2aa' );
Webhook Alternative For real-time status updates, consider setting up webhooks instead of polling. Webhooks provide immediate notifications when message status changes.
Instead of polling, you can configure webhooks to receive automatic status updates:
{ "event" : "message.delivered" , "message_id" : "msg_123456789" , "status" : "delivered" , "delivered_at" : "2024-01-15T10:30:15Z" , "delivery_report" : { "carrier" : "Verizon" , "country" : "US" } } Error Handling Error Handling
Error Handling
const getMessageDetails = async ( messageId ) => { try { const response = await fetch ( `https://sms.lamah.com/api/sms/messages/ ${ messageId } ?message_id= ${ messageId } ` , { headers: { 'Authorization' : 'Bearer YOUR_API_TOKEN' , 'Accept' : 'application/json' } }); if ( ! response . ok ) { const error = await response . json (); if ( error . code === 'MESSAGE_NOT_FOUND' ) { console . error ( 'Message not found:' , messageId ); } else if ( error . code === 'ACCESS_DENIED' ) { console . error ( 'Access denied for message:' , messageId ); } else { console . error ( 'Failed to get message details:' , error . error ); } return null ; } const message = await response . json (); return message ; } catch ( error ) { console . error ( 'Network error:' , error ); return null ; } };
