List all messages

    This API retrieves a list of Message Detail Records (MDR) based on a filter criteria over the last 30 days.

    Note: The default rate limit for this API is 20 requests per minute. If the rate limit is exceeded, the following error would be thrown: "too many requests"

    API Endpoint

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

    Arguments

    subaccount string

    Filters for

    • Outbound messages sent using a specific subaccount’s Auth Token.
    • Inbound messages received on a phone number associated with a specific subaccount.
    Note: The subaccount filter is implicitly applied when a subaccount’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

    Filters the results by message direction. Allowed values: inbound, outbound

    message_time

    Filters outbound and inbound messages based on the time the message was initiated or received.

    Timestamps are expected to be in YYYY-MM-DD HH:MM[:ss[.uuuuuu]] format, and are considered to be in UTC time zone.

    If you do not specify this attribute, the MDR for the last 24 hours will be retrived by default.

    The filter can be used in five forms:

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

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

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

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

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

    Note: You can combine the above filters to get messages that were sent or received in a particular time range.
    message_state string

    Filter results by the current status of a message.

    Allowed values: queued, sent, failed, delivered, undelivered, received, rejected

    message_type string

    Filter results by the type of message.

    Allowed values: sms, mms

    error_code string

    Filter results by a standard Plivo error code.

    powerpack_uuidstring

    Filter results based on messages sent using a specific Power pack.

    limit integer

    Denotes 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.

    Returns

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

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

    • limit: 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 (deprecated)
    • 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": "b98c3dfa-c86c-11eb-b9e8-0242ac110005",
        "meta": {
            "limit": 2,
            "next": "/v1/Account/{auth_id}/Message/?limit=2&offset=2",
            "offset": 0,
            "previous": null,
        },
        "objects": [
            {
                "carrier_fees": "0.00000",
                "error_code": "000",
                "from_number": "17087654321",
                "mcc": "312",
                "message_direction": "outbound",
                "message_state": "delivered",
                "message_time": "2021-07-13 13:04:06.799021+05:30",
                "message_type": "sms",
                "message_uuid": "b48d95dc-e3ac-11eb-a9c2-0242ac110005",
                "mnc": "650",
                "powerpack_id": "1d5f3dd8-b207-4738-b59f-3c2ac7d3461c",
                "resource_uri": "/v1/Account/{auth_id}/Message/b48d95dc-e3ac-11eb-a9c2-0242ac110005/",
                "to_number": "12401234567",
                "total_amount": "0.00140",
                "total_rate": "0.00140",
                "units": 1
             },
            {
                "carrier_fees": "0.00000",
                "error_code": "000",
                "from_number": "17087654321",
                "mcc": "312",
                "message_direction": "outbound",
                "message_state": "delivered",
                "message_time": "2021-07-14 13:41:19.566564+05:30",
                "message_type": "sms",
                "message_uuid": "11cca016-e47b-11eb-9a69-0242ac110004",
                "mnc": "650",
                "powerpack_id": "null",
                "resource_uri": "/v1/Account/{auth_id}/Message/11cca016-e47b-11eb-9a69-0242ac110004/",
                "to_number": "12401234567",
                "total_amount": "0.00140",
                "total_rate": "0.00140",
                "units": 1 
             },
        ]
    }
    

    Example Request

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    
    import plivo
    
    client = plivo.RestClient('<auth_id>','<auth_token>')
    response = client.messages.list(
        limit=5,
        offset=0,
        subaccount='subaccount_auth_id',
        )
    print(response)
    #prints only the message_uuid
    print(response.message_uuid)
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    
    require "plivo"
    include Plivo
    
    api = RestClient.new("<auth_id>","<auth_token>")
      response = api.messages.list(
        limit: 5,
        offset: 0,
        subaccount: "subaccount_auth_id",
      )
      puts response
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    
    var plivo = require('plivo');
    
    (function main() {
        'use strict';
        var client = new plivo.Client("<auth_id>","<auth_token>");
        client.messages.list(
            {
                limit: 5,
                offset: 0,
                subaccount:"subaccount_auth_id",
            }
          ).then(function (response) {
              console.log(response);
              //Prints only the message_uuid
              console.log(response.messageUuid);
          },);
        })();
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    
    <?php
    require 'vendor/autoload.php';
    use Plivo\RestClient;
    
    $client = new RestClient("<auth_id>","<auth_token>");
    $response = $client->messages->list(
      [
        'limit' => 5,
        'offset' => 0,
        'subaccount' =>'subaccount_auth_id'
      ]
    );
    print_r($response);
    // Prints only the message_uuid
    print_r($response->getmessageUuid(0));
    ?>
    
    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
    
    import java.io.IOException;
    
    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;
    
    
    class GetAllMessageList
    {
        public static void main(String [] args)
        {
            Plivo.init("<auth_id>","<auth_token>");
            try
            {
                ListResponse<Message> response = Message.lister()
                        .subaccount("subaccount_auth_id")
                        .limit(5)
                        .offset(0)
                        .list();
                System.out.println(response);
                // Prints only the message_uuid
                System.out.println(response.getMessageUuid());
            }
            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
    
    using System;
    using System.Collections.Generic;
    using Plivo;
    
    namespace PlivoExamples
    {
        internal class Program
        {
            public static void Main(string[] args)
            {
                var api = new PlivoApi("<auth_id>","<auth_token>");
    
                    var response = api.Message.List(
                        limit:10,
                        offset:0,
                        subaccount:"subaccount_auth_id"
                    );
                    Console.WriteLine(response);
                    // Prints the message_uuid
                    Console.WriteLine(response.MessageUuid[0]);
            }
        }
    }
    
    1
    2
    
    curl -i --user auth_id_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
    22
    23
    24
    25
    
    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 {
    			fmt.Print("Error", err.Error())
    			return
    		}
    	response, err := client.Messages.List(
    		plivo.MessageListParams{
    			Limit:  5,
    			Offset: 0,
    		},
    	)
    	if err != nil {
    			fmt.Print("Error", err.Error())
    			return
    		}
    	fmt.Printf("Response: %#v\n", response)
    	// Prints only the message_uuid
    	fmt.Printf("Response: %#v\n", response.MessageUUID)
    }