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

# Recipient behavior metrics

> Learn how to track unsubscribe activity across your MailChannels Email API campaigns.

## What recipient behavior metrics measure

Recipient behavior metrics report actions that signal recipient sentiment toward your mail. They currently cover
unsubscribe activity:

* `unsubscribed`: recipients who unsubscribed.
* `unsubscribe_delivered`: recipients of delivered messages that include an unsubscribe link or unsubscribe header. Because the unsubscribe feature requires exactly one recipient per message, this also equals the total number of delivered messages with unsubscribe enabled.

You can use the paired values to compute an unsubscribe rate. A rising rate can indicate content fatigue, frequency
issues, or an audience mismatch.

## Example query

The example below requests weekly unsubscribe activity for a single campaign.

<CodeGroup>
  ```bash cURL theme={null}
  #!/usr/bin/env bash
  # Retrieve weekly unsubscribe activity for a single campaign.
    set -u
    : "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"

  curl -G "https://api.mailchannels.net/tx/v1/metrics/recipient-behaviour" \
    -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
    --data-urlencode "campaign_id=weekly_newsletter" \
    --data-urlencode "interval=week"
  ```

  ```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.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);
  ```

  ```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 weekly unsubscribe activity for a single campaign.
  response = mailchannels.Metrics.recipient_behaviour(
      campaign_id="weekly_newsletter",
      interval="week",
  )

  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 weekly unsubscribe activity for a single campaign.
  $response = $client->metrics->recipientBehaviour(
      campaignId: 'weekly_newsletter',
      interval:   'week',
  );

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