API ReferenceEngagements

Get publication engagements OAuth Scope: publications:read

Retrieve email engagement metrics for a specific publication over a defined date range and granularity.

By default, the endpoint returns metrics for the past day, aggregated daily. The max number of days allowed is 31. All dates and times are in UTC.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

publicationIdstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"
The prefixed ID of the publication.

Query parameters

start_datedateOptional

The starting date for the engagement metrics in YYYY-MM-DD format. Defaults to 1 day ago if not provided.

number_of_daysintegerOptional1-31

The number of days to return engagement metrics for, starting from start_date. Must be between 1 and 31. Defaults to 1 if not provided.

granularityenumOptional

The granularity at which to report the engagement metrics. Defaults to day if not provided.

Allowed values:
email_typeenumOptional

Filter engagement metrics by email type. If omitted, all email engagement is included.
post: Only post emails.
message: Only automated and system-generated emails.

Allowed values:
directionenumOptionalDefaults to asc

The direction that the results are sorted in. Defaults to asc.
asc: Oldest to newest
desc: Newest to oldest

Allowed values:

Response

OK
datalist of objects
The list of engagement metrics for the publication within the specified date range and granularity. Returns an empty list if there is no engagement data for the specified period.
publication_idstringformat: "^(pub_[0-9a-fA-F\-]+)$"
The unique identifier of the publication. Passed as a path parameter in the request.
granularityenum
The granularity at which the engagement metrics are reported.
Allowed values:
email_typeenum

The email type filter applied to the engagement metrics. Defaults to all.

Allowed values:
start_datedate
The starting date of the engagement metrics.
number_of_daysinteger1-31
The number of days of engagement metrics returned.

Errors