Senders method 📊 Metrics

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 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 senders (type: MetricsSendersType, options?: MetricsSendersOptions): Promise<MetricsSendersResponse>

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

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 • Tests