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-11 16:14:13",
"dlr_date": "2024-12-11 16:14:13",
"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-11 16:14:13",
"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-11 16:14:13"</date>
<dlr_date>"2024-12-11 16:14:13"</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-11 16:14:13"</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...). |