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 five distinct endpoint categories, each designed to provide specific insights into different aspects of your email campaigns:

• Engagement Metrics: Track recipient interactions including email opens and link clicks
• Performance Metrics: Monitor delivery success rates, bounces, and processing status
• Recipient Behaviour Metrics: Analyze unsubscribe patterns and recipient actions
• Volume Metrics: Track overall sending volumes and message processing statistics
• Sender Metrics: Identify your largest senders and their delivery performance

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.

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_time=2024-01-01T00:00:00Z&end_time=2024-01-31T23:59:59Z&campaign_id=newsletter_jan_2024&interval=day"

Response Structure

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

{
    "open": 250,
    "open_tracking_delivered": 500,
    "click": 50,
    "click_tracking_delivered": 450,
    "buckets": {
        "open": [
            {
                "count": 100,
                "period_start": "2024-01-01T00:00:00Z"
            },
            {
                "count": 150,
                "period_start": "2024-01-02T00:00:00Z"
            }
        ],
        "open_tracking_delivered": [
            {
                "count": 200,
                "period_start": "2024-01-01T00:00:00Z"
            },
            {
                "count": 250,
                "period_start": "2024-01-02T00:00:00Z"
            }
        ],
        "click": [
            {
                "count": 20,
                "period_start": "2024-01-01T00:00:00Z"
            },
            {
                "count": 30,
                "period_start": "2024-01-02T00:00:00Z"
            }
        ],
        "click_tracking_delivered": [
            {
                "count": 200,
                "period_start": "2024-01-01T00:00:00Z"
            },
            {
                "count": 250,
                "period_start": "2024-01-02T00:00:00Z"
            }
        ]
    }
}

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_time=2024-01-01T00:00:00Z"

Response Structure

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

{
    "processed": 1000,
    "delivered": 830,
    "bounced": 170,
    "buckets": {
        "processed": [
            {
                "count": 500,
                "period_start": "2024-01-01T00:00:00Z"
            },
            {
                "count": 500,
                "period_start": "2024-01-02T00:00:00Z"
            }
        ],
        "delivered": [
            {
                "count": 480,
                "period_start": "2024-01-01T00:00:00Z"
            },
            {
                "count": 350,
                "period_start": "2024-01-02T00:00:00Z"
            }
        ],
        "bounced": [
            {
                "count": 20,
                "period_start": "2024-01-01T00:00:00Z"
            },
            {
                "count": 150,
                "period_start": "2024-01-02T00:00:00Z"
            }
        ]
    }
}

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&interval=week"

Response Structure

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

{
    "unsubscribed": 30,
    "unsubscribe_delivered": 600,
    "buckets": {
        "unsubscribed": [
            {
                "count": 10,
                "period_start": "2024-01-01T00:00:00Z"
            },
            {
                "count": 20,
                "period_start": "2024-01-08T00:00:00Z"
            }
        ],
        "unsubscribe_delivered": [
            {
                "count": 300,
                "period_start": "2024-01-01T00:00:00Z"
            },
            {
                "count": 300,
                "period_start": "2024-01-08T00:00:00Z"
            }
        ]
    }
}

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_time=2024-01-01T00:00:00Z&end_time=2024-01-07T23:59:59Z"

Response Structure

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

{
    "processed": 2000,
    "delivered": 1800,
    "dropped": 200,
    "buckets": {
        "processed": [
            {
                "count": 1000,
                "period_start": "2024-01-01T00:00:00Z"
            },
            {
                "count": 1000,
                "period_start": "2024-01-02T00:00:00Z"
            }
        ],
        "delivered": [
            {
                "count": 900,
                "period_start": "2024-01-01T00:00:00Z"
            },
            {
                "count": 900,
                "period_start": "2024-01-02T00:00:00Z"
            }
        ],
        "dropped": [
            {
                "count": 100,
                "period_start": "2024-01-01T00:00:00Z"
            },
            {
                "count": 100,
                "period_start": "2024-01-02T00:00:00Z"
            }
        ]
    }
}

Sender Metrics

Endpoint: GET /metrics/senders/{sender_type}

The sender type can be one of the following:

• campaigns: Delivery metrics grouped by campaign.
• sub-accounts: Delivery metrics grouped by sub-account.

Sender metrics provide aggregate insights into the performance of individual sub-accounts and campaigns. This endpoint helps you identify your largest senders, monitor their delivery performance, and detect any deliverability issues.

Use Cases

• Track campaigns by size and performance
• Discover campaigns or sub-accounts with deliverability issues or high rejection rates
• Identify sub-accounts that are hitting their sending limits

Example Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.mailchannels.net/tx/v1/metrics/senders/campaigns?start_time=2024-01-01T00:00:00Z&end_time=2024-01-31T23:59:59Z&limit=50&offset=1&sort_order=desc"

Response Structure

The sender metrics response provides aggregate delivery performance data for each sender: (Note that senders with no processed messages in the specified time range will be excluded from the response.)

{
    "senders": [
        {
            "name": "campaign_12345",
            "processed": 470,
            "delivered": 450,
            "dropped": 30,
            "bounced": 20
        },
        {
            "name": "campaign_67890",
            "processed": 275,
            "delivered": 250,
            "dropped": 25,
            "bounced": 25
        }
    ],
    "limit": 50,
    "offset": 1,
    "total": 3
}

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