Get a list's details | Brevo API Documentation

import { BrevoClient } from "@getbrevo/brevo";
async function main() {
    const client = new BrevoClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.contacts.getList(1, {});
}
main();

{
  "id": 12,
  "name": "Newsletter_Weekly",
  "totalBlacklisted": 63,
  "totalSubscribers": 6533,
  "uniqueSubscribers": 6596,
  "createdAt": "2016-02-26T11:56:08Z",
  "folderId": 1,
  "campaignStats": [
    {
      "campaignId": 15,
      "stats": {
        "appleMppOpens": 10,
        "clickers": 789,
        "complaints": 0,
        "delivered": 6632,
        "hardBounces": 4,
        "opensRate": 29.54,
        "sent": 6645,
        "softBounces": 34,
        "trackableViews": 5661,
        "uniqueClicks": 701,
        "uniqueViews": 3442,
        "unsubscriptions": 4,
        "viewed": 4322,
        "deferred": 0
      }
    },
    {
      "campaignId": 45,
      "stats": {
        "appleMppOpens": 10,
        "clickers": 788,
        "complaints": 1,
        "delivered": 4078,
        "hardBounces": 2,
        "opensRate": 29.54,
        "sent": 4334,
        "softBounces": 18,
        "trackableViews": 5661,
        "uniqueClicks": 654,
        "uniqueViews": 987,
        "unsubscriptions": 4,
        "viewed": 1555,
        "deferred": 0
      }
    }
  ],
  "dynamicList": false,
  "endDate": "2024-04-10T00:00:00Z",
  "startDate": "2023-10-10T00:00:00Z"
}

Retrieve the details of a specific contact list by its ID, including its name, folder ID, creation date, subscriber counts, and campaign statistics. You can optionally filter campaign statistics by providing startDate and endDate parameters (both must be used together in YYYY-MM-DD format).

import { BrevoClient } from "@getbrevo/brevo";
async function main() {
    const client = new BrevoClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.contacts.getList(1, {});
}
main();

{
  "id": 12,
  "name": "Newsletter_Weekly",
  "totalBlacklisted": 63,
  "totalSubscribers": 6533,
  "uniqueSubscribers": 6596,
  "createdAt": "2016-02-26T11:56:08Z",
  "folderId": 1,
  "campaignStats": [
    {
      "campaignId": 15,
      "stats": {
        "appleMppOpens": 10,
        "clickers": 789,
        "complaints": 0,
        "delivered": 6632,
        "hardBounces": 4,
        "opensRate": 29.54,
        "sent": 6645,
        "softBounces": 34,
        "trackableViews": 5661,
        "uniqueClicks": 701,
        "uniqueViews": 3442,
        "unsubscriptions": 4,
        "viewed": 4322,
        "deferred": 0
      }
    },
    {
      "campaignId": 45,
      "stats": {
        "appleMppOpens": 10,
        "clickers": 788,
        "complaints": 1,
        "delivered": 4078,
        "hardBounces": 2,
        "opensRate": 29.54,
        "sent": 4334,
        "softBounces": 18,
        "trackableViews": 5661,
        "uniqueClicks": 654,
        "uniqueViews": 987,
        "unsubscriptions": 4,
        "viewed": 1555,
        "deferred": 0
      }
    }
  ],
  "dynamicList": false,
  "endDate": "2024-04-10T00:00:00Z",
  "startDate": "2023-10-10T00:00:00Z"
}

Authentication

api-keystring

The API key should be passed in the request headers as api-key for authentication.

Path parameters

listIdlongRequired

Id of the list

Query parameters

startDatestringOptional

Mandatory if endDate is used. Starting (urlencoded) UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to aggregate the sent email campaigns for a specific list id. Prefer to pass your timezone in date-time format for accurate result

endDatestringOptional

Mandatory if startDate is used. Ending (urlencoded) UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to aggregate the sent email campaigns for a specific list id. Prefer to pass your timezone in date-time format for accurate result

Response

List informations

idlong

ID of the list

namestring

Name of the list

totalBlacklistedlong

Number of blacklisted contacts in the list

totalSubscriberslong

Number of contacts in the list

uniqueSubscriberslong

Number of unique contacts in the list

createdAtstring

Creation UTC date-time of the list (YYYY-MM-DDTHH:mm:ss.SSSZ)

folderIdlong

ID of the folder

campaignStatslist of objects

dynamicListboolean

Status telling if the list is dynamic or not (true=dynamic, false=not dynamic)

Errors

400

Bad Request Error

404

Not Found Error

1	import { BrevoClient } from "@getbrevo/brevo";
2
3	async function main() {
4	const client = new BrevoClient({
5	apiKey: "YOUR_API_KEY_HERE",
6	});
7	await client.contacts.getList(1, {});
8	}
9	main();

1	{
2	"id": 12,
3	"name": "Newsletter_Weekly",
4	"totalBlacklisted": 63,
5	"totalSubscribers": 6533,
6	"uniqueSubscribers": 6596,
7	"createdAt": "2016-02-26T11:56:08Z",
8	"folderId": 1,
9	"campaignStats": [
10	{
11	"campaignId": 15,
12	"stats": {
13	"appleMppOpens": 10,
14	"clickers": 789,
15	"complaints": 0,
16	"delivered": 6632,
17	"hardBounces": 4,
18	"opensRate": 29.54,
19	"sent": 6645,
20	"softBounces": 34,
21	"trackableViews": 5661,
22	"uniqueClicks": 701,
23	"uniqueViews": 3442,
24	"unsubscriptions": 4,
25	"viewed": 4322,
26	"deferred": 0
27	}
28	},
29	{
30	"campaignId": 45,
31	"stats": {
32	"appleMppOpens": 10,
33	"clickers": 788,
34	"complaints": 1,
35	"delivered": 4078,
36	"hardBounces": 2,
37	"opensRate": 29.54,
38	"sent": 4334,
39	"softBounces": 18,
40	"trackableViews": 5661,
41	"uniqueClicks": 654,
42	"uniqueViews": 987,
43	"unsubscriptions": 4,
44	"viewed": 1555,
45	"deferred": 0
46	}
47	}
48	],
49	"dynamicList": false,
50	"endDate": "2024-04-10T00:00:00Z",
51	"startDate": "2023-10-10T00:00:00Z"
52	}