NewsMAN API: list.subscribersEvolution

Sections

KB Newsman

HomeAPIListlist.subscribersEvolution

Newsman Api Method: list.subscribersEvolution

Prototype: list.subscribersEvolution(list_id, start_date, stop_date)

Description: Returns, for a list, the evolution of the subscribers during a certain period (grouped by days: no. total subscribers, no. eligible subscribers, no. unsubscribes, no. spam reports, no. hardbounces)

HTTP method: GET

Endpoint HTTP: /list.subscribersEvolution.json

Endpoint XML-RPC: list.subscribersEvolution

Return type: struct|array

Return info: struct Hash arrays, each representing a day in the period, each array item has: list_id, total_subscribers_count, eligible_subscribers_count, date, unsubscribes_count, spam_reports_count, hardbounces_count

Request parameters GET

Variable	Type	Description
list_id	string\|int	The ID of the list for which to get the evolution of the subscribers
start_date	string\|int	The start date of the period for which to fetch results (>=), UTC date, format: YYYY-MM-DD
stop_date	string\|int	The stop date of the period for which to fetch results (<=), UTC date, format: YYYY-MM-DD

Response parameters

Parameter	Description
date	A day in the period
total_subscribers_count	The total no. of subscribers in the list on the respective day
eligible_subscribers_count	The no. of eligible subscribers in the list on the respective day
unsubscribes_count	The no. of unsubscribes on the respective day
spam_reports_count	The no. of spam reports on the respective day
hardbounces_count	The no. of hard bounces on the respective day

Output example

[
    {
        "list_id": "my_list_id",
        "date": "2022-11-19",
        "total_subscribers_count": 18582,
        "eligible_subscribers_count": 13147,
        "unsubscribes_count": 15,
        "spam_reports_count": 2,
        "hardbounces_count": 0
    },
    {
        "list_id": "my_list_id",
        "date": "2022-11-20",
        "total_subscribers_count": 18590,
        "eligible_subscribers_count": 13150,
        "unsubscribes_count": 16,
        "spam_reports_count": 2,
        "hardbounces_count": 0
    },
    {
        "list_id": "my_list_id",
        "date": "2022-11-21",
        "total_subscribers_count": 18594,
        "eligible_subscribers_count": 13147,
        "unsubscribes_count": 18,
        "spam_reports_count": 2,
        "hardbounces_count": 0
    },
    {
        "list_id": "my_list_id",
        "date": "2022-11-22",
        "total_subscribers_count": 18600,
        "eligible_subscribers_count": 13144,
        "unsubscribes_count": 31,
        "spam_reports_count": 1,
        "hardbounces_count": 1
    },
    {
        "list_id": "my_list_id",
        "date": "2022-11-23",
        "total_subscribers_count": 18606,
        "eligible_subscribers_count": 13143,
        "unsubscribes_count": 20,
        "spam_reports_count": 3,
        "hardbounces_count": 0
    },
    {
        "list_id": "my_list_id",
        "date": "2022-11-24",
        "total_subscribers_count": 18610,
        "eligible_subscribers_count": 13142,
        "unsubscribes_count": 14,
        "spam_reports_count": 1,
        "hardbounces_count": 3
    },
    {
        "list_id": "my_list_id",
        "date": "2022-11-25",
        "total_subscribers_count": 18610,
        "eligible_subscribers_count": 13138,
        "unsubscribes_count": 76,
        "spam_reports_count": 1,
        "hardbounces_count": 141
    }
]

Response Errors

Code	Message	Description
407	Missing required param list_id	list_id param is required
407	Missing required param start_date	start_date param is required
407	Missing required param stop_date	stop_date param is required
14001	The period interval must be max 90 days	The period interval must be max 90 days
14002	The period interval is invalid	The interval defined by the start_date and stop_date is invalid (min 2 days, max 90 days, start_date < stop_date)

Error examples

{
    "err": true,
    "message": "Missing required param list_id",
    "code": 407
}

{
    "err": true,
    "message": "Missing required param start_date",
    "code": 407
}

{
    "err": true,
    "message": "Missing required param stop_date",
    "code": 407
}

{
    "err": true,
    "message": "The period interval must be max 90 days",
    "code": 14001
}

{
    "err": true,
    "message": "The period interval is invalid",
    "code": 14002
}

{
    "err": true,
    "message": "There was an error retrieving the data",
    "code": 14003
}