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 optional: The beginning of the time range for retrieving message engagement 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 message engagement 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 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.
  • click number guaranteed
  • clickTrackingDelivered number guaranteed
  • endTime string guaranteed
  • open number guaranteed
  • openTrackingDelivered number guaranteed
  • startTime string guaranteed
• 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 engagement (options?: MetricsOptions): Promise<MetricsEngagementResponse>

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;
}

Engagement type declarations

interface MetricsEngagement {
  buckets: {
    click: MetricsBucket[];
    clickTrackingDelivered: MetricsBucket[];
    open: MetricsBucket[];
    openTrackingDelivered: MetricsBucket[];
  };
  click: number;
  clickTrackingDelivered: number;
  endTime: string;
  open: number;
  openTrackingDelivered: number;
  startTime: string;
}

type MetricsEngagementResponse = DataResponse<MetricsEngagement>;

Source

Source • Playground • Docs • Tests