> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailbreeze.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get List Stats

> Retrieve statistics for a contact list

Get aggregate statistics for a contact list including contact counts and engagement metrics.

## Path Parameters

<ParamField path="id" type="string" required>
  The unique list ID (e.g., `lst_abc123`).
</ParamField>

## Examples

<CodeGroup>
  ```typescript JavaScript theme={null}
  import { MailBreeze } from "mailbreeze";

  const mailbreeze = new MailBreeze({ apiKey: "sk_live_xxx" });

  const stats = await mailbreeze.lists.stats("lst_abc123");

  console.log(`Total contacts: ${stats.totalContacts}`);
  console.log(`Active: ${stats.activeContacts}`);
  console.log(`Unsubscribed: ${stats.unsubscribedContacts}`);
  console.log(`Bounced: ${stats.bouncedContacts}`);
  ```

  ```python Python theme={null}
  from mailbreeze import MailBreeze

  client = MailBreeze(api_key="sk_live_xxx")

  stats = await client.lists.stats("lst_abc123")

  print(f"Total contacts: {stats.total_contacts}")
  print(f"Active: {stats.active_contacts}")
  print(f"Unsubscribed: {stats.unsubscribed_contacts}")
  print(f"Bounced: {stats.bounced_contacts}")
  ```

  ```go Go theme={null}
  client := mailbreeze.NewClient("sk_live_xxx")

  stats, err := client.Lists.Stats(ctx, "lst_abc123")
  if err != nil {
      log.Fatal(err)
  }

  fmt.Printf("Total contacts: %d\n", stats.TotalContacts)
  fmt.Printf("Active: %d\n", stats.ActiveContacts)
  fmt.Printf("Unsubscribed: %d\n", stats.UnsubscribedContacts)
  fmt.Printf("Bounced: %d\n", stats.BouncedContacts)
  ```

  ```php PHP theme={null}
  $mailbreeze = new MailBreeze('sk_live_xxx');

  $response = $mailbreeze->lists->stats('lst_abc123');
  $stats = $response['data'];

  echo "Total contacts: " . $stats['totalContacts'] . "\n";
  echo "Active: " . $stats['activeContacts'] . "\n";
  echo "Suppressed: " . $stats['suppressedContacts'] . "\n";
  ```

  ```rust Rust theme={null}
  let client = Client::new("sk_live_xxx");

  let stats = client.lists().stats("lst_abc123").await?;

  println!("Total contacts: {}", stats.total_contacts);
  println!("Active: {}", stats.active_contacts);
  println!("Unsubscribed: {}", stats.unsubscribed_contacts);
  println!("Bounced: {}", stats.bounced_contacts);
  ```

  ```bash cURL theme={null}
  curl "https://api.mailbreeze.com/api/v1/contact-lists/lst_abc123/stats" \
    -H "Authorization: Bearer sk_live_xxx"
  ```
</CodeGroup>

## Response

<ResponseField name="totalContacts" type="integer">
  Total number of contacts in the list.
</ResponseField>

<ResponseField name="activeContacts" type="integer">
  Contacts eligible to receive emails.
</ResponseField>

<ResponseField name="suppressedContacts" type="integer">
  Contacts on the suppression list (bounced, complained, unsubscribed, etc.).
</ResponseField>

```json Example Response theme={null}
{
  "success": true,
  "data": {
    "totalContacts": 1523,
    "activeContacts": 1520,
    "suppressedContacts": 3
  },
  "meta": {
    "timestamp": "2025-12-27T13:47:56.974Z",
    "requestId": "afa9e391-43d4-4594-820f-cc5e6b3b0c22",
    "path": "/api/v1/contact-lists/694fc1669e63563857ae8d72/stats"
  }
}
```

## Understanding Contact States

| State          | Description                                             | Receives Email? |
| -------------- | ------------------------------------------------------- | --------------- |
| **Active**     | Eligible to receive emails                              | Yes             |
| **Suppressed** | On suppression list (bounced, complained, unsubscribed) | No              |

<Note>
  `totalContacts` = `activeContacts` + `suppressedContacts`
</Note>

## Errors

| Code        | HTTP Status | Description                     |
| ----------- | ----------- | ------------------------------- |
| `NOT_FOUND` | 404         | List with this ID doesn't exist |