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

# Sender breakdown metrics

> Learn how to compare delivery performance across your largest campaigns and sub-accounts.

## What sender breakdown metrics measure

Sender breakdown metrics return aggregate delivery counts grouped by sender. Each entry includes the sender `name`
along with `processed`, `delivered`, `dropped`, and `bounced` totals over the queried window.

Choose how to group results with the `sender_type` path parameter:

* `campaigns`: group results by campaign.
* `sub-accounts`: group results by sub-account.

Use these metrics to identify your largest senders, flag campaigns or sub-accounts with deliverability issues, and
spot sub-accounts that are approaching their sending limits.

<Note>
  Senders with no processed messages in the queried window are excluded from the response.
</Note>

## Parameters

Unlike the other metric categories, sender breakdown returns an aggregate (not a time series) and does not accept
`campaign_id` or `interval`. The supported parameters are:

* `start_time` and `end_time`: ISO 8601 timestamps that restrict the query to a time range. If omitted, `start_time` defaults
  to one month ago and `end_time` defaults to the current time.
* `limit`: maximum number of senders to return per page (default `10`, max `1000`).
* `offset`: number of senders to skip from the start of the result set (default `0`).
* `sort_order`: `asc` or `desc`. Sorting is applied to the total number of messages (`processed` + `dropped`). Defaults to `desc`.

## Example query

The example below requests the top 50 campaigns by total messages (`processed` + `dropped`) for January 2026, sorted
in descending order.

<CodeGroup>
  ```bash cURL theme={null}
  #!/usr/bin/env bash
  # Retrieve the top 50 campaigns by total messages (processed + dropped) for January 2026.
    set -u
    : "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"

  curl -G "https://api.mailchannels.net/tx/v1/metrics/senders/campaigns" \
    -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
    --data-urlencode "start_time=2026-01-01T00:00:00Z" \
    --data-urlencode "end_time=2026-01-31T23:59:59Z" \
    --data-urlencode "limit=50" \
    --data-urlencode "offset=0" \
    --data-urlencode "sort_order=desc"
  ```

  ```javascript Node.js theme={null}
  import { MailChannels } from "mailchannels-sdk";

  const { MAILCHANNELS_API_KEY } = process.env;
  if (!MAILCHANNELS_API_KEY) throw new Error("Set MAILCHANNELS_API_KEY before running");

  const mailchannels = new MailChannels(MAILCHANNELS_API_KEY);

  const { data, error } = await mailchannels.metrics.senders("campaigns", {
    startTime: "2026-01-01T00:00:00Z",
    endTime: "2026-01-31T23:59:59Z",
  });

  if (error) {
    console.error("Get senders metrics failed:", error);
    process.exit(1);
  }
  console.log(data);
  ```

  ```python Python theme={null}
  import os
  import sys

  import mailchannels

  if not os.environ.get("MAILCHANNELS_API_KEY"):
      sys.exit("Set MAILCHANNELS_API_KEY before running")

  # Retrieve the top 50 campaigns by total messages (processed + dropped) for January 2026.
  response = mailchannels.Metrics.senders(
      "campaigns",
      start_time="2026-01-01T00:00:00Z",
      end_time="2026-01-31T23:59:59Z",
      limit=50,
      offset=0,
      sort_order="desc",
  )

  print(response)
  ```

  ```php PHP theme={null}
  <?php

  require_once __DIR__ . '/vendor/autoload.php';

  use MailChannels\Client;

  $api_key = getenv('MAILCHANNELS_API_KEY') or exit("Error: MAILCHANNELS_API_KEY is not set\n");

  $client = new Client(apiKey: $api_key);

  // Retrieve the top 50 campaigns by total messages (processed + dropped) for January 2026.
  $response = $client->metrics->senders(
      senderType: 'campaigns',
      startTime:  '2026-01-01T00:00:00Z',
      endTime:    '2026-01-31T23:59:59Z',
      limit:      50,
      offset:     0,
      sortOrder:  'desc',
  );

  print_r($response->toArray());
  ```
</CodeGroup>