List all messages

This API can be used to fetch a list of message detail records (MDRs) based on a filter criteria.

API Endpoint

GET https://api.plivo.com/v1/Account/{auth_id}/Message/

Arguments

subaccount string

Use this argument to filter for

  • Outbound messages sent using a specific sub-account's auth token.
  • Inbound messages received on a phone number associated with a specific sub-account.
Note: The sub-account filter is implicitly applied when a sub-account's API credentials are used to fire this API. This argument should be used only when the parent account's API credentials are used to fire this API.
message_direction string

Use this argument to filter the results by message direction. The valid inputs are inbound and outbound.

message_time

Forms of this parameter can be used to filter outbound/inbound messages based on the time the message was initiated/received.

The timestamps are expected to in YYYY-MM-DD HH:MM[:ss[.uuuuuu]] format, and are considered to be in UTC timezone.

The filter can be used in the following five forms:

  • message_time: Use this argument to filter for messages by the exact timestamp. The format expected is YYYY-MM-DD HH:MM:ss. Eg: To get all messages that were sent/received at 2012-03-21 11:47:30, use message_time=2012-03-21 11:47:30

  • message_time__gt: gt stands for greater than. Use this argument to filter for messages sent/received after a given time. Eg: To get all messages that were sent/received after 2012-03-21 11:47, use message_time___gt=2012-03-21 11:47

  • message_time__gte: gte stands for greater than or equal. Eg: To get all messages that were sent/received after or exactly at 2012-03-21 11:47[:30], use message_time___gte=2012-03-21 11:47[:30]

  • message_time__lt: lt stands for lesser than. Use this argument to filter for messages sent/received before a given time. Eg: To get all messages that were sent/received before 2012-03-21 11:47, use message_time___lt=2012-03-21 11:47

  • message_time__lte: lte stands for lesser than or equal. Eg: To get all messages that were sent/received before or exactly at 2012-03-21 11:47[:30], use message_time___lte=2012-03-21 11:47[:30]

Note: The above filters can be combined to get messages that were sent/received in a particular time range.
message_state string

Use this argument to filter by the current status of a message. This argument can be set to one of following states : queued, sent, failed, delivered, undelivered or rejected.

error_code string

Use this argument to filter results by a standard Plivo error code. Read more about Plivo SMS error codes here.

limit integer

Used to display the number of results per page. The maximum number of results that can be fetched is 20. Defaults to 20.

offset integer

Denotes the number of value items by which the results should be offset. Defaults to 0. Read more about offset based pagination here.

Returns

This API returns the list of Message Detail Records matching the filters specified in the request.

The API response also contains a meta field with the following fields:

  • limit: This the size of the page returned in the response.
  • offset: The offset for the page returned in the response.
  • total_count: The total number of records that match the specified filters.
  • next: The URL that points to the next page of results.
  • previous: The URL that points to the previous page of results.

Response

HTTP Status Code: 200

{
  "api_id": "88415194-6df0-11e6-b608-06a72a185e87",
  "meta": {
	"limit": 2,
	"next": "/v1/Account/{auth_id}/Message/?limit=20&error_code=200&offset=20",
	"offset": 0,
	"previous": null,
	"total_count": 22
  },
  "objects": [
	{
	  "error_code": "200",
	  "from_number": "18552828641",
	  "message_direction": "outbound",
	  "message_state": "failed",
	  "message_time": "2016-08-17 21:26:44+05:30",
	  "message_type": "sms",
	  "message_uuid": "85ce8068-6fab-4f0a-9dc7-d6c852cdde91",
	  "resource_uri": "/v1/Account/{auth_id}/Message/85ce8068-6fab-4f0a-9dc7-d6c852cdde91/",
	  "to_number": "19352326448",
	  "total_amount": "0.00000",
	  "total_rate": "0.00350",
	  "units": 1
	},
	{
	  "error_code": "200",
	  "from_number": "18552828641",
	  "message_direction": "outbound",
	  "message_state": "failed",
	  "message_time": "2016-08-17 21:22:36+05:30",
	  "message_type": "sms",
	  "message_uuid": "2a340179-e8a9-4b1d-ae2c-9f346e7b6d7d",
	  "resource_uri": "/v1/Account/{auth_id}/Message/2a340179-e8a9-4b1d-ae2c-9f346e7b6d7d/",
	  "to_number": "19352326448",
	  "total_amount": "0.00000",
	  "total_rate": "0.00350",
	  "units": 1
	}
  ]
}

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import plivo

client = plivo.RestClient("AUTH_ID","AUTH_TOKEN")
response = client.messages.list(
    limit=10,
    offset=0,
    subaccount='SUBACCOUNT_AUTH_ID',
    message_direction='outbound',
    message_state='delivered',
    message_time='2019-07-05 11:47:30',
    message_time__gt='2019-07-05 11:47:30',
    message_time__gte='2019-07-05 11:47:30',
    message_time__lt='2019-07-05 11:47:30',
    message_time__lte='2019-07-05 11:47:30',
    error_code=10,
    )
print(response)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
require "rubygems"
require "plivo"

include Plivo
include Plivo::Exceptions

api = RestClient.new("AUTH_ID", "AUTH_TOKEN")

begin
  response = api.messages.list(
    limit: 10,
    offset: 0,
    subaccount: "SUBACCOUNT_AUTH_ID",
    message_direction: "outbound",
    message_state: "undelivered",
    message_time: "2019-07-05 11:47:30",
    message_time__gt: "2019-07-05 11:47:30",
    message_time__gte: "2019-07-05 11:47:30",
    message_time__lt: "2019-07-05 11:47:30",
    message_time__lte: "2019-07-05 11:47:30",
    error_code: "10",
  )
  puts response
rescue PlivoRESTError => e
  puts "Exception: " + e.message
end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
var plivo = require('plivo');

(function main() {
    'use strict';
    var client = new plivo.Client("AUTH_ID", "AUTH_TOKEN");
    client.messages.list(
        {
            limit: 10,
            offset: 0,
            subaccount:"SUBACCOUNT_AUTH_ID",
            message_direction:"inbound",
            error_code: '10',
            message_state: 'undelivered',
            message_time:'2019-07-10 15:51:49',
            message_time__lt:'2019-07-05 11:47:30',
            message_time__lte:'2019-07-05 11:47:30',
            message_time__gt:'2019-07-05 11:47:30',
            message_time__gte:'2019-07-05 11:47:30',
        }
    ).then(function (response)
    {
        console.log(response);
    }, function (err)
    {
        console.error(err);
    });
})();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("AUTH_ID", "AUTH_TOKEN");

try {
    $response = $client->messages->list(
        [
        	'limit' => 10,
            'offset' => 0,
            'subaccount' =>'SUBACCOUNT_AUTH_ID',
            'message_state'=>'received',
            'message_direction' => 'inbound',
            'message_time' =>'2019-07-05 11:47:30',
            'message_time__gt'=>'2019-07-05 11:47:30',
            'message_time__gte'=>'2019-07-05 11:47:30',
            'message_time__lt'=>'2019-07-05 11:47:30',
            'message_time__lte'=>'2019-07-05 11:47:30',
            'error_code'=>'10'
        ]
    );
    print_r($response);
}
catch (PlivoRestException $ex) {
    print_r(ex);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import java.io.IOException;
import java.util.Date;

import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.message.Message;
import com.plivo.api.models.base.ListResponse;
import com.plivo.api.models.message.MessageDirection;
import com.plivo.api.models.message.MessageState;
import com.plivo.api.models.message.MessageLister;


class GetAllMessageList
{
    public static void main(String [] args)
    {
        Plivo.init("AUTH_ID","AUTH_TOKEN");
        try
        {
            ListResponse<Message> response = Message.lister()
                    .errorCode(10L)
                    .subaccount("SUBACCOUNT_AUTH_ID")
                    .messageDirection(MessageDirection.INBOUND)
                    .messageState(MessageState.DELIVERED)
                    .limit(10)
                    .offset(0)
                    .list();
            System.out.println(response);
        }
        catch (PlivoRestException | IOException e)
        {
            e.printStackTrace();
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
using System;
using System.Collections.Generic;
using Plivo;
using Plivo.Exception;

namespace PlivoExamples
{
    internal class Program
    {
        public static void Main(string[] args)
        {
            var api = new PlivoApi("AUTH_ID", "AUTH_TOKEN");
            try
            {
                var response = api.Message.List(
                    limit:10,
                    offset:0,
                    error_code:10,
                    message_state:"undelivered",
                    message_direction:"inbound"
                );
                Console.WriteLine(response);
            }
            catch (PlivoRestException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}
1
2
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Message/
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
package main

import "fmt"
import "github.com/plivo/plivo-go"

func main() {
	client, err := plivo.NewClient("AUTH_ID", "AUTH_TOKEN", &plivo.ClientOptions{})
	if err != nil {
		panic(err)
	}
	response, err := client.Messages.List(
		plivo.MessageListParams{
			Limit:  10,
			Offset: 0,
		},
	)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Response: %#v\n", response)
}