Engagement method 📊 Metrics

Retrieve engagement metrics for messages sent from your account, including counts of open and click 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.engagement()

full.ts

import { MailChannels } from 'mailchannels-sdk'

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

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

Params

• options MetricsOptions optional: Optional filter options.
  • startTime string | Date optional: The beginning of the time range for retrieving message engagement metrics (inclusive). Formats: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ or a Date object. Defaults to one month ago if not provided.
  • endTime string | Date optional: The end of the time range for retrieving message engagement metrics (exclusive). Formats: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ or a Date object. 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 MetricsEngagement | null nullable
  • buckets object guaranteed: A series of metrics aggregations bucketed by time interval (e.g. hour, day).
    • click 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.
    • clickTrackingDelivered 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.
    • open 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.
    • openTrackingDelivered 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.
    • uniqueClick MetricsBucket[] optional
      • 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.
    • uniqueClickTrackingDelivered MetricsBucket[] optional
      • 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.
    • uniqueOpen MetricsBucket[] optional
      • 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.
    • uniqueOpenTrackingDelivered MetricsBucket[] optional
      • 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.
  • click number guaranteed: Count of click events by recipients.
  • clickTrackingDelivered number guaranteed: Count of recipients of delivered messages with HTML content that contains tracked click URLs, where click tracking is enabled in the send request.
  • endTime string guaranteed: The end of the time range for retrieving message engagement metrics (exclusive).
  • open number guaranteed: Count of open events by recipients.
  • openTrackingDelivered number guaranteed: Count of recipients of delivered messages with HTML content where open tracking was enabled in the send request.
  • startTime string guaranteed: The beginning of the time range for retrieving message engagement metrics (inclusive).
  • uniqueClick number optional: Count of distinct messages that had at least one click event. Unlike click, each message is counted at most once regardless of how many links were clicked or how many times. Use this to compute click rates without exceeding 100%.
  • uniqueClickTrackingDelivered number optional: Count of distinct messages delivered with click tracking enabled (message-level, not recipient-level). Use as the denominator when computing unique click rates.
  • uniqueOpen number optional: Count of distinct messages that had at least one open event. Unlike open, each message is counted at most once regardless of how many times its tracking pixel was fired. Use this to compute open rates without exceeding 100%.
  • uniqueOpenTrackingDelivered number optional: Count of distinct messages delivered with open tracking enabled (message-level, not recipient-level). Use as the denominator when computing unique open rates.
• 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.
  • response Record<string, unknown> | null nullable: An object containing the response, if available. This field may be null if no response is available or if the error is not related to an HTTP request or if the response is not a JSON object.

Type declarations

Signature

async function engagement (options?: MetricsOptions): Promise<MetricsEngagementResponse>

Response type declarations

interface ErrorResponse {
  message: string;
  statusCode: number | null;
  type: ErrorType;
  response: Record<string, unknown> | null;
}

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

Shared metrics type declarations

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

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

Engagement type declarations

interface MetricsEngagement {
  buckets: {
    click: MetricsBucket[];
    clickTrackingDelivered: MetricsBucket[];
    open: MetricsBucket[];
    openTrackingDelivered: MetricsBucket[];
    uniqueClick?: MetricsBucket[];
    uniqueClickTrackingDelivered?: MetricsBucket[];
    uniqueOpen?: MetricsBucket[];
    uniqueOpenTrackingDelivered?: MetricsBucket[];
  };
  click: number;
  clickTrackingDelivered: number;
  endTime: string;
  open: number;
  openTrackingDelivered: number;
  startTime: string;
  uniqueClick?: number;
  uniqueClickTrackingDelivered?: number;
  uniqueOpen?: number;
  uniqueOpenTrackingDelivered?: number;
}

type MetricsEngagementResponse = DataResponse<MetricsEngagement>;

Source

Source • Playground • Docs • Tests