> ## 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 Recipient Behaviour Metrics

> Retrieve recipient behaviour metrics for messages sent from your account,
including counts of unsubscribed events.
Supports optional filters for time range, and campaign ID.




## OpenAPI

````yaml /email-api/api-reference/openapi.yaml get /metrics/recipient-behaviour
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/recipient-behaviour:
    get:
      tags:
        - Metrics
      summary: Retrieve Recipient Behaviour Metrics
      description: >
        Retrieve recipient behaviour metrics for messages sent from your
        account,

        including counts of unsubscribed events.

        Supports optional filters for time range, and campaign ID.
      parameters:
        - description: >
            The beginning of the time range for retrieving recipient behaviour
            metrics (inclusive).

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

            Defaults to one month ago if not provided.
          example: '2025-05-26'
          in: query
          name: start_time
          required: false
          schema:
            type: string
        - description: >
            The end of the time range for retrieving recipient behaviour metrics
            (exclusive).

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

            Defaults to the current time if not provided.
          example: '2025-05-31T15:16:17Z'
          in: query
          name: end_time
          required: false
          schema:
            type: string
        - description: |
            The ID of the campaign to filter metrics by.
            If not provided, metrics for all campaigns will be returned.
          in: query
          name: campaign_id
          required: false
          schema:
            type: string
        - description: |
            The interval for aggregating metrics data. Allowed values:
              - hour: Hourly breakdown
              - day: Daily breakdown (default)
              - week: Weekly breakdown
              - month: Monthly breakdown
          in: query
          name: interval
          required: false
          schema:
            default: day
            enum:
              - hour
              - day
              - week
              - month
            type: string
        - in: header
          name: X-Api-Key
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsRecipientBehaviour'
          description: |
            Successfully retrieved recipient behaviour metrics
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad 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.recipientBehaviour({
              startTime: "2026-01-01T00:00:00Z",
              endTime: "2026-01-31T23:59:59Z",
            });


            if (error) {
              console.error("Get recipient behaviour 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 weekly unsubscribe activity for a single campaign.
            response = mailchannels.Metrics.recipient_behaviour(
                campaign_id="weekly_newsletter",
                interval="week",
            )

            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 weekly unsubscribe activity for a single campaign.

            $response = $client->metrics->recipientBehaviour(
                campaignId: 'weekly_newsletter',
                interval:   'week',
            );


            print_r($response->toArray());
components:
  schemas:
    MetricsRecipientBehaviour:
      properties:
        buckets:
          description: >-
            A series of metrics aggregations bucketed by time interval (e.g.
            hour, day)
          properties:
            unsubscribe_delivered:
              items:
                $ref: '#/components/schemas/MetricsBucket'
              type: array
            unsubscribed:
              items:
                $ref: '#/components/schemas/MetricsBucket'
              type: array
          required:
            - unsubscribed
            - unsubscribe_delivered
          type: object
        end_time:
          description: >
            The end of the time range for retrieving recipient behaviour metrics
            (exclusive).
          format: date-time
          type: string
        start_time:
          description: >
            The beginning of the time range for retrieving recipient behaviour
            metrics (inclusive).
          format: date-time
          type: string
        unsubscribe_delivered:
          description: >
            Count of recipients of delivered messages that include at least one
            of the unsubscribe link

            or unsubscribe headers. Since the unsubscribe feature requires
            exactly one recipient per message,

            this count also represents the total number of delivered messages.
          minimum: 0
          type: integer
        unsubscribed:
          description: |
            Count of unsubscribed events by recipients.
          minimum: 0
          type: integer
      required:
        - unsubscribed
        - unsubscribe_delivered
        - buckets
      type: object
    ErrorResponse:
      properties:
        errors:
          description: >
            This is an array error objects that provide machine and human
            readable descriptions of the errors.
          items:
            type: string
          type: array
      type: object
    MetricsBucket:
      description: >
        Represents a time-based bucket for aggregating metrics data.

        Each bucket corresponds to a specific time interval, with the
        `period_start` indicating the beginning of that interval.

        The `count` field represents the number of events or occurrences that
        fall within that time period.
      properties:
        count:
          description: >-
            The number of events or occurrences aggregated within this time
            period.
          minimum: 0
          type: integer
        period_start:
          description: >-
            The starting date and time of the time period this bucket
            represents.
          format: date-time
          type: string
      required:
        - period_start
        - count
      type: object

````