Recipient Behaviour method 📊 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.

Usage

modular.ts

import { MailChannelsClient, Metrics } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const metrics = new Metrics(mailchannels)

const { data, error } = await metrics.recipientBehaviour()

full.ts

import { MailChannels } from 'mailchannels-sdk'

const mailchannels = new MailChannels('your-api-key')

const { data, error } = await mailchannels.metrics.recipientBehaviour()

Params

• options MetricsOptions optional: Optional filter options.
  • startTime string optional: 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.
  • endTime string optional: 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.
  • campaignId string optional: The ID of the campaign to filter metrics by. If not provided, metrics for all campaigns will be returned.
  • interval "hour" | "day" | "week" | "month" optional: The interval for aggregating metrics data. Defaults to day.

Response

• data MetricsRecipientBehaviour | null nullable
  • buckets object guaranteed: A series of metrics aggregations bucketed by time interval (e.g. hour, day).
    • unsubscribeDelivered MetricsBucket[] guaranteed
      • count number guaranteed: The number of events or occurrences aggregated within this time period.
      • periodStart string guaranteed: The starting date and time of the time period this bucket represents.
    • unsubscribed MetricsBucket[] guaranteed
      • count number guaranteed: The number of events or occurrences aggregated within this time period.
      • periodStart string guaranteed: The starting date and time of the time period this bucket represents.
  • endTime string guaranteed: The end of the time range for retrieving recipient behaviour metrics (exclusive).
  • startTime string guaranteed: The beginning of the time range for retrieving recipient behaviour metrics (inclusive).
  • unsubscribeDelivered number guaranteed: 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.
  • unsubscribed number guaranteed: Count of unsubscribed events by recipients.
• error ErrorResponse | null nullable: Error information if the operation failed.
  • message string guaranteed: A human-readable description of the error.
  • statusCode number | null nullable: The HTTP status code from the API, or null if the error is not related to an HTTP request. This field is intended for diagnostic use only and should not be relied upon.
  • type string guaranteed: A string identifier for the type of error. This field is intended for diagnostic use only and should not be relied upon.

Type declarations

Signature

async function recipientBehaviour (options?: MetricsOptions): Promise<MetricsRecipientBehaviourResponse>

Response type declarations

interface ErrorResponse {
  message: string;
  statusCode: number | null;
  type: ErrorType;
}

type DataResponse<T> = {
  data: T;
  error: null;
} | {
  data: null;
  error: ErrorResponse;
};

Shared metrics type declarations

interface MetricsOptions {
  startTime?: string;
  endTime?: string;
  campaignId?: string;
  interval?: "hour" | "day" | "week" | "month";
}

interface MetricsBucket {
  count: number;
  periodStart: string;
}

Recipient Behaviour type declarations

interface MetricsRecipientBehaviour {
  buckets: {
    unsubscribeDelivered: MetricsBucket[];
    unsubscribed: MetricsBucket[];
  };
  endTime: string;
  startTime: string;
  unsubscribeDelivered: number;
  unsubscribed: number;
}

type MetricsRecipientBehaviourResponse = DataResponse<MetricsRecipientBehaviour>;

Source

Source • Playground • Docs • Tests