Skip to main content

Metrics​

The Metrics API provides comprehensive analytics and insights into your email sending performance through MailChannels Email API. By leveraging these endpoints, you can monitor key performance indicators, track user engagement, analyze delivery outcomes, and gain valuable insights into recipient behaviour patterns.

The Metrics API offers four distinct endpoint categories, each designed to provide specific insights into different aspects of your email campaigns:

Key Features​

The Metrics API provides several powerful features to help you optimize your email campaigns:

  • Time-based Filtering: All endpoints support flexible time range filtering to analyze performance over specific periods
  • Campaign Segmentation: Filter metrics by specific campaign IDs to analyze individual campaign performance
  • Real-time Data: Access up-to-date metrics to make informed decisions about your email strategy
  • Comprehensive Coverage: Track the complete email lifecycle from processing to recipient engagement

By leveraging the Metrics API effectively, you can gain comprehensive insights into your email performance, optimize your campaigns for better engagement, and ensure reliable email delivery to your recipients.

Authentication​

All Metrics API endpoints require authentication using your MailChannels API key. Include your API key in the X-Api-Key header with every request:

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.mailchannels.net/tx/v1/metrics/engagement"

Common Query Parameters​

All metrics endpoints support the following optional query parameters for filtering and customization:

  • start_date (optional): Filter metrics from this date (ISO 8601 format)
  • end_date (optional): Filter metrics until this date (ISO 8601 format)
  • campaign_id (optional): Filter metrics for a specific campaign
  • interval (optional): Time interval for grouping metrics data

Engagement Metrics​

Endpoint: GET /metrics/engagement

Engagement metrics provide insights into how recipients interact with your emails after delivery. This endpoint tracks user actions such as email opens and link clicks, helping you understand recipient engagement patterns and optimize your email content and timing.

Use Cases​

  • Monitor campaign engagement rates
  • Identify high-performing content
  • Optimize send times based on open patterns
  • Track link click-through rates

Example Request​

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.mailchannels.net/tx/v1/metrics/engagement?start_date=2024-01-01T00:00:00Z&end_date=2024-01-31T23:59:59Z&campaign_id=newsletter_jan_2024"

Response Structure​

The engagement metrics response provides time-series data for email campaign performance, organized into temporal buckets for trend analysis.

  • open: Total number of email opens
  • open_tracking_delivered: Number of recipients who received emails that had open tracking enabled
  • click: Total number of link clicks
  • click_tracking_delivered: Number of recipients who received emails that had click tracking enabled
  • buckets: Metrics bucketed by time period (e.g. hour, day)
    • open: Array of open event buckets
      • count: Number of open events in this time period
      • period_start: Starting date and time of the time period this bucket represents
    • open_tracking_delivered: Array of open tracking delivery buckets
      • count: Number of recipients who received emails that had open tracking enabled in this time period
      • period_start: Starting date and time of the time period this bucket represents
    • click: Array of click event buckets
      • count: Number of click events in this time period
      • period_start: Starting date and time of the time period this bucket represents
    • click_tracking_delivered: Array of click tracking delivery buckets
      • count: Number of recipients who received emails that had click tracking enabled in this time period
      • period_start: Starting date and time of the time period this bucket represents

Performance Metrics​

Endpoint: GET /metrics/performance

Performance metrics focus on the technical aspects of email delivery, providing essential data about message processing, successful deliveries, and delivery failures. This endpoint helps you monitor the health of your email infrastructure and identify potential deliverability issues.

Use Cases​

  • Monitor overall delivery success rates
  • Identify delivery issues and bounce patterns
  • Track processing performance
  • Analyze sender reputation impact

Example Request​

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.mailchannels.net/tx/v1/metrics/performance?start_date=2024-01-01T00:00:00Z"

Response Structure​

The performance metrics response provides time-series data for email delivery performance:

  • processed: Messages successfully processed by the system
  • delivered: Messages successfully delivered to recipients
  • bounced: Messages that permanently failed delivery
  • buckets: Metrics bucketed by time period (e.g. hour, day)
    • processed: Array of processing event buckets
      • count: Number of messages processed in this time period
      • period_start: Starting date and time of the time period this bucket represents
    • delivered: Array of delivery event buckets
      • count: Number of messages delivered in this time period
      • period_start: Starting date and time of the time period this bucket represents
    • bounced: Array of hard bounce event buckets
      • count: Number of messages that hard bounced in this time period
      • period_start: Starting date and time of the time period this bucket represents

Recipient Behaviour Metrics​

Endpoint: GET /metrics/recipient-behaviour

Recipient behaviour metrics provide insights into how recipients respond to your email campaigns beyond basic engagement. This endpoint tracks actions that indicate recipient preferences and satisfaction, such as unsubscribe events.

Use Cases​

  • Monitor unsubscribe rates
  • Identify content or frequency issues
  • Track recipient satisfaction trends
  • Optimize email cadence and content strategy

Example Request​

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.mailchannels.net/tx/v1/metrics/recipient-behaviour?campaign_id=weekly_newsletter"

Response Structure​

The recipient behaviour metrics response provides time-series data for email unsubscribe activity:

  • unsubscribed: Number of recipients who clicked unsubscribe links
  • unsubscribe_delivered: Number of recipients who received emails that had unsubscribe links.
  • buckets: Metrics bucketed by time period (e.g. hour, day)
    • unsubscribed: Array of unsubscribe event buckets
      • count: Number of recipients who clicked unsubscribe links in this time period
      • period_start: Starting date and time of the time period this bucket represents
    • unsubscribe_delivered: Array of unsubscribe delivery buckets
      • count: Number of recipients who received emails that had unsubscribe links in this time period
      • period_start: Starting date and time of the time period this bucket represents

Volume Metrics​

Endpoint: GET /metrics/volume

Volume metrics provide a high-level overview of your email sending activity, including processing volumes, successful deliveries, and dropped messages. This endpoint is essential for understanding your overall email throughput and system performance.

Use Cases​

  • Track overall sending volumes
  • Monitor system capacity and performance
  • Identify processing bottlenecks
  • Analyze sending patterns over time

Example Request​

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.mailchannels.net/tx/v1/metrics/volume?start_date=2024-01-01T00:00:00Z&end_date=2024-01-07T23:59:59Z"

Response Structure​

The volume metrics response provides time-series data for email processing and delivery volumes:

  • processed: Total messages processed by the system
  • delivered: Total messages successfully delivered
  • dropped: Messages that failed processing or were rejected
  • buckets: Metrics bucketed by time period (e.g. hour, day)
    • processed: Array of processing event buckets
      • count: Number of messages processed in this time period
      • period_start: Starting date and time of the time period this bucket represents
    • delivered: Array of delivery event buckets
      • count: Number of messages delivered in this time period
      • period_start: Starting date and time of the time period this bucket represents
    • dropped: Array of dropped message buckets
      • count: Number of messages dropped in this time period
      • period_start: Starting date and time of the time period this bucket represents

Error Handling​

All metrics endpoints use consistent error handling:

  • 200 OK: Successfully retrieved metrics
  • 400 Bad Request: Invalid query parameters or request format
  • 401 Unauthorized: Invalid or missing API key
  • 500 Internal Server Error: Server-side processing error