Volume method 📊 Metrics

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 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 volume (options?: MetricsOptions): Promise<MetricsVolumeResponse>

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

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

Source

Source • Playground • Docs • Tests