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

# Retrieve Sender Metrics

> Retrieves a list of senders, either sub-accounts or campaigns, with their associated message metrics.
Sorted by total # of sent messages (processed + dropped)
Supports optional filter for time range, and optional settings for limit, offset, and sort order.
Note: senders without any messages in the given time range will not be included in the results.
The default time range is from one month ago to now, and the default sort order is descending.




## OpenAPI

````yaml /email-api/api-reference/openapi.yaml get /metrics/senders/{sender_type}
openapi: 3.0.0
info:
  contact:
    email: support@mailchannels.com
    name: MailChannels Corporation
  description: >
    This is the API reference for Email API. Here, you'll find more detailed
    information on every endpoint, including parameters, response formats, and
    error codes.
  title: Email API
  version: 1.4.0
servers:
  - url: https://api.mailchannels.net/tx/v1
security: []
tags:
  - name: Send
  - name: DKIM
  - name: Metrics
  - name: Sub-accounts
  - name: Suppression
  - name: Webhooks
  - name: Usage
  - name: Custom Tracking
paths:
  /metrics/senders/{sender_type}:
    get:
      tags:
        - Metrics
      summary: Retrieve Sender Metrics
      description: >
        Retrieves a list of senders, either sub-accounts or campaigns, with
        their associated message metrics.

        Sorted by total # of sent messages (processed + dropped)

        Supports optional filter for time range, and optional settings for
        limit, offset, and sort order.

        Note: senders without any messages in the given time range will not be
        included in the results.

        The default time range is from one month ago to now, and the default
        sort order is descending.
      parameters:
        - in: path
          name: sender_type
          required: true
          schema:
            enum:
              - campaigns
              - sub-accounts
            type: string
        - description: >
            The beginning of the time range for retrieving top senders metrics
            (inclusive).

            Formats: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ

            Defaults to one month ago if not provided.
          in: query
          name: start_time
          required: false
          schema:
            type: string
        - description: >
            The end of the time range for retrieving top senders metrics
            (exclusive).

            Formats: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ

            Defaults to the current time if not provided.
          in: query
          name: end_time
          required: false
          schema:
            type: string
        - description: |
            The maximum number of senders to return
            The default is 10.
          in: query
          name: limit
          required: false
          schema:
            default: 10
            maximum: 1000
            minimum: 1
            type: integer
        - description: |
            The number of senders to skip before returning results.
          in: query
          name: offset
          required: false
          schema:
            default: 0
            minimum: 0
            type: integer
        - description: >
            The order in which to sort the results, based on total messages
            (processed + dropped).
          in: query
          name: sort_order
          required: false
          schema:
            default: desc
            enum:
              - asc
              - desc
            type: string
        - in: header
          name: X-Api-Key
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsSenderResponse'
          description: |
            Successfully retrieved top senders metrics
        '400':
          description: Invalid request
        '500':
          description: Internal server error
      x-codeSamples:
        - label: Node.js
          lang: javascript
          source: >-
            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);
        - label: Python
          lang: python
          source: >-
            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)
        - label: PHP
          lang: php
          source: >-
            <?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());
components:
  schemas:
    MetricsSenderResponse:
      properties:
        end_time:
          format: date-time
          type: string
        limit:
          type: integer
        offset:
          type: integer
        senders:
          items:
            $ref: '#/components/schemas/MetricsSender'
          type: array
        start_time:
          format: date-time
          type: string
        total:
          description: >
            The total number of senders in this category that sent messages in
            the given time range.
          type: integer
      required:
        - limit
        - offset
        - total
        - senders
      type: object
    MetricsSender:
      properties:
        bounced:
          minimum: 0
          type: integer
        delivered:
          minimum: 0
          type: integer
        dropped:
          minimum: 0
          type: integer
        name:
          maxLength: 255
          type: string
        processed:
          minimum: 0
          type: integer
      required:
        - name
        - processed
        - delivered
        - bounced
        - dropped
      type: object

````