Get messages over a period of time

This method allows you to retrieve all your messages in over a period of time.

GET

/messages

Query Parameters

date_start
required
 Add a filter to retrieve campaigns of which send date is after this date. Date format must be as follow: Y-m-d H:i:s
date_end
required
 Add a filter to retrieve campaigns of which send date is before this date. Date format must be as follow: Y-m-d H:i:s
destination Add a filter to retrieve campaigns that have this phone number as destination
message Add a filter to retrieve campaigns that contains this text in the content
type Add a filter for the type of message: message received (messages-in), sent message (messages-out). By default, all messages are returned
country Add a filter to retrieve messages on the sending country. Country format must be alpha2 : FR
status Add a filter on message status. Available status : delivered, sent, waiting, moderation, denied, not_sent, undelivered
start You can define the start record for pagination. Default 0
length You can define the number of records to retrieve per request. Default 100. Maximum 1000
sort You can sort by date, destination, sender, status. Add - to sort in descending order, for example -date

Examples


GET /messages?date_start=2023-09-01 00:00:00&date_end=2023-09-31 23:59:59 HTTP/1.1
Host: api.smsfactor.com
Accept: application/json
Authorization: Bearer your.token

Result Format


{
    "status": 1,
    "message": "OK",
    "totalRecords": 2,
    "totalDisplayRecords": 2,
    "messages": [
        {
            "campaign_id": 123,
            "client_id": 1,
            "client_message_id": "my id",
            "contact_list_id": "",
            "message": "Message via API",
            "message_length": 15,
            "cost": 1,
            "country": "FR",
            "destination": "33612345678",
            "message_id": 138,
            "sender": "",
            "date": "2024-12-21 12:44:05",
            "dlr_date": "2024-12-21 12:44:05",
            "status": "SENT",
            "status_details": "SENT",
            "type": "sms_mt"
        },
        {
            "campaign_id": 123,
            "client_id": 1,
            "client_message_id": "my id",
            "contact_list_id": "",
            "message": "An answer",
            "message_length": 9,
            "cost": 0,
            "country": "",
            "destination": "36000",
            "message_id": 256,
            "sender": "33612345678",
            "date": "2024-12-21 12:44:05",
            "dlr_date": "",
            "status": "incoming_message",
            "status_details": "",
            "type": "sms_mo"
        }
    ]
}
          
        

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>1</status>
    <message>OK</message>
    <totalRecords>2</totalRecords>
    <totalDisplayRecords>2</totalDisplayRecords>
    <messages>
        <campaign_id>123</campaign_id>
        <client_id>1</client_id>
        <client_message_id>my id</client_message_id>
        <contact_list_id></contact_list_id>
        <message>Message via API</message>
        <message_length>15</message_length>
        <cost>1</cost>
        <country>FR</country>
        <destination>33612345678</destination>
        <message_id>138</message_id>
        <sender></sender>
        <date>"2024-12-21 12:44:05"</date>
        <dlr_date>"2024-12-21 12:44:05"</dlr_date>
        <status>SENT</status>
        <status_details>SENT</status_details>
        <type>sms_mt</type>
    </messages>
    <messages>
        <campaign_id>123</campaign_id>
        <client_id>1</client_id>
        <client_message_id>my id</client_message_id>
        <contact_list_id></contact_list_id>
        <message>An answer</message>
        <message_length>9</message_length>
        <cost>0</cost>
        <country></country>
        <destination>36000</destination>
        <message_id>256</message_id>
        <sender>33612345678</sender>
        <date>"2024-12-21 12:44:05"</date>
        <dlr_date></dlr_date>
        <status>incoming_message</status>
        <status_details></status_details>
        <type>sms_mo</type>
    </messages>
</response>

Statuses

status Description
sent The message has been sent.
waiting The message is waiting to be sent (campaign scheduled in the future).
delivered The message has been received.
moderation The message is being moderated. A human action is required to validate or reject (in the case of fraud) the message.
denied The message was rejected.
not_sent The message was not sent (invalid number, unauthorised country, unauthorised times, anti-flood...).
undelivered The operator tells us that the message has not been received (unassigned number, network problem, phone off...).