📊 Metrics module Email API

This module allows you to retrieve metrics for messages sent from your account.

Engagement method

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 string | null nullable

Performance method

Retrieve performance metrics for messages sent from your account, including counts of processed, delivered, hard-bounced 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.performance()

full.ts

import { MailChannels } from 'mailchannels-sdk'

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

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

Params

• options MetricsOptions optional: Optional filter options.
  • startTime string optional: The beginning of the time range for retrieving message performance 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 performance 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 MetricsPerformance | null nullable
  • bounced number guaranteed: Count of messages bounced during the specified time range.
  • buckets object guaranteed: A series of metrics aggregations bucketed by time interval (e.g. hour, day).
    • bounced 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.
    • delivered 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.
    • processed 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.
  • delivered number guaranteed: Count of messages delivered during the specified time range.
  • endTime string guaranteed: The end of the time range for retrieving message performance metrics (exclusive).
  • processed number guaranteed: Count of messages processed during the specified time range.
  • startTime string guaranteed: The beginning of the time range for retrieving message performance metrics (inclusive).
• error string | null nullable

Recipient Behaviour method

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 string | null nullable

Volume method

Retrieve volume metrics for messages sent from your account, including counts of processed, delivered and dropped 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.volume()

full.ts

import { MailChannels } from 'mailchannels-sdk'

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

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

Params

• options MetricsOptions optional: Optional filter options.
  • startTime string optional: The beginning of the time range for retrieving message volume 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 volume 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 MetricsVolume | null nullable
  • buckets object guaranteed: A series of metrics aggregations bucketed by time interval (e.g. hour, day).
    • delivered 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.
    • dropped 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.
    • processed 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.
  • delivered number guaranteed: Count of messages delivered during the specified time range.
  • dropped number guaranteed: Count of messages dropped during the specified time range.
  • endTime string guaranteed: The end of the time range for retrieving message volume metrics (exclusive).
  • processed number guaranteed: Count of messages processed during the specified time range.
  • startTime string guaranteed: The beginning of the time range for retrieving message volume metrics (inclusive).
• error string | null nullable

Usage method

Retrieves usage statistics during the current billing period.

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.usage()

full.ts

import { MailChannels } from 'mailchannels-sdk'

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

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

Response

• usage object | null nullable
  • endDate string guaranteed: The end date of the current billing period (ISO 8601 format).
  • startDate string guaranteed: The start date of the current billing period (ISO 8601 format).
  • total number guaranteed: The total usage for the current billing period.
• error string | null nullable

Senders method

Retrieves a list of senders, either sub-accounts or campaigns, with their associated message metrics. Sorted by total # of sent messages (processed + dropped). Supports optional filter for time range, and optional settings for limit, offset, and sort order. Note: senders without any messages in the given time range will not be included in the results. The default time range is from one month ago to now, and the default sort order is descending.

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.senders("campaigns")

full.ts

import { MailChannels } from 'mailchannels-sdk'

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

const { data, error } = await mailchannels.metrics.senders("campaigns")

Params

• type MetricsSendersType required: The type of senders to retrieve metrics for. Can be either sub-accounts or campaigns.
• options MetricsSendersOptions optional: Optional filter options.
  • startTime string optional: The beginning of the time range for retrieving top senders 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 top senders metrics (exclusive). Formats: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ. Defaults to the current time if not provided.
  • limit number optional: The maximum number of senders to return. Possible values are 1 to 1000. Defaults to 10 if not provided.
  • offset number optional: The number of senders to skip before returning results. Defaults to 0 if not provided.
  • sortOrder "asc" | "desc" optional: The order in which to sort the results, based on total messages (processed + dropped). Defaults to desc if not provided.

Response

• data MetricsSenders | null nullable
  • endTime string guaranteed
  • limit number guaranteed
  • offset number guaranteed
  • senders object[] guaranteed
    • bounced number guaranteed
    • delivered number guaranteed
    • dropped number guaranteed
    • name string guaranteed
    • processed number guaranteed
  • startTime string guaranteed
  • total number guaranteed: The total number of senders in this category that sent messages in the given time range.
• error string | null nullable

Type declarations

class Metrics {
  constructor (protected mailchannels: MailChannelsClient);
  async engagement (options?: MetricsOptions): Promise<MetricsEngagementResponse>;
  async performance (options?: MetricsOptions): Promise<MetricsPerformanceResponse>;
  async recipientBehaviour (options?: MetricsOptions): Promise<MetricsRecipientBehaviourResponse>;
  async volume (options?: MetricsOptions): Promise<MetricsVolumeResponse>;
  async usage (): Promise<MetricsUsageResponse>;
  async senders (type: MetricsSendersType, options?: MetricsSendersOptions): Promise<MetricsSendersResponse>;
}

All type declarations

Responses

interface DataResponse<T> {
  data: T | null;
  error: string | null;
}

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

Performance type declarations

interface MetricsPerformance {
  bounced: number;
  buckets: {
    bounced: MetricsBucket[];
    delivered: MetricsBucket[];
    processed: MetricsBucket[];
  };
  delivered: number;
  endTime: string;
  processed: number;
  startTime: string;
}

type MetricsPerformanceResponse = DataResponse<MetricsPerformance>;

Recipient Behaviour type declarations

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

type MetricsRecipientBehaviourResponse = DataResponse<MetricsRecipientBehaviour>;

Volume type declarations

interface MetricsVolume {
  buckets: {
    delivered: MetricsBucket[];
    dropped: MetricsBucket[];
    processed: MetricsBucket[];
  };
  delivered: number;
  dropped: number;
  endTime: string;
  processed: number;
  startTime: string;
}

type MetricsVolumeResponse = DataResponse<MetricsVolume>;

Usage type declarations

type MetricsUsageResponse = DataResponse<{
  endDate: string;
  startDate: string;
  total: number;
}>;

Senders type declarations

type MetricsSendersType = "sub-accounts" | "campaigns";

interface MetricsSendersOptions {
  startTime?: string;
  endTime?: string;
  limit?: number;
  offset?: number;
  sortOrder?: "asc" | "desc";
}

interface MetricsSenders {
  endTime: string;
  limit: number;
  offset: number;
  senders: {
    bounced: number;
    delivered: number;
    dropped: number;
    name: string;
    processed: number;
  }[];
  startTime: string;
  total: number;
}

type MetricsSendersResponse = DataResponse<MetricsSenders>;

Source

Source • Playground • Docs