Skip to main content
GET
/
metrics
/
engagement
Retrieve Engagement Metrics
curl --request GET \
  --url https://api.mailchannels.net/tx/v1/metrics/engagement \
  --header 'X-Api-Key: <x-api-key>'
{
  "buckets": {
    "click": [
      {
        "count": 1,
        "period_start": "2023-11-07T05:31:56Z"
      }
    ],
    "click_tracking_delivered": [
      {
        "count": 1,
        "period_start": "2023-11-07T05:31:56Z"
      }
    ],
    "open": [
      {
        "count": 1,
        "period_start": "2023-11-07T05:31:56Z"
      }
    ],
    "open_tracking_delivered": [
      {
        "count": 1,
        "period_start": "2023-11-07T05:31:56Z"
      }
    ]
  },
  "click": 1,
  "click_tracking_delivered": 1,
  "open": 1,
  "open_tracking_delivered": 1,
  "end_time": "2023-11-07T05:31:56Z",
  "start_time": "2023-11-07T05:31:56Z"
}

Headers

​
X-Api-Key
string
required

Query Parameters

​
start_time
string

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.

​
end_time
string

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.

​
campaign_id
string

The ID of the campaign to filter metrics by. If not provided, metrics for all campaigns will be returned.

​
interval
enum<string>
default:day

The interval for aggregating metrics data. Allowed values:

  • hour: Hourly breakdown
  • day: Daily breakdown (default)
  • week: Weekly breakdown
  • month: Monthly breakdown
Available options:
hour,
day,
week,
month

Response

Successfully retrieved engagement metrics

​
buckets
object
required

A series of metrics aggregations bucketed by time interval (e.g. hour, day)

​
click
integer
required

Count of click events by recipients.

Required range: x >= 0
​
click_tracking_delivered
integer
required

Count of recipients of delivered messages with HTML content that contains tracked click URLs, where click tracking is enabled in the send request.

Required range: x >= 0
​
open
integer
required

Count of open events by recipients.

Required range: x >= 0
​
open_tracking_delivered
integer
required

Count of recipients of delivered messages with HTML content where open tracking was enabled in the send request.

Required range: x >= 0
​
end_time
string<date-time>

The end of the time range for retrieving message engagement metrics (exclusive).

​
start_time
string<date-time>

The beginning of the time range for retrieving message engagement metrics (inclusive).