reports

Engagement time series

GET /v1/reports/engagement

Auth required reports.view

Time-bucketed open and click activity. Each bucket emits raw sent, delivered, total opens/clicks, and unique_opens/unique_clicks (distinct recipients who acted within the bucket).

Rate formulas:

open_rate = unique_opens / delivered
click_rate = unique_clicks / delivered

Both denominators are delivered, not sent, and the numerators are unique counts. Ratios are in [0, 1]; zero delivered yields 0.0. Buckets align to UTC the same way as deliverability and empty buckets are not zero-filled.

Caveat: for week and month buckets, a recipient who engages on more than one day inside the bucket may be counted more than once in unique_opens/unique_clicks. This matches the SendOps dashboard. Default window is the trailing 30 days; plan retention applies.

Query parameters

from string<date-time> optional

Window start (RFC 3339). Defaults to 30 days ago.

to string<date-time> optional

Window end (RFC 3339). Defaults to now.

group_by string enum optional

Time-bucket size for the report. UTC-aligned: day = midnight UTC; week = Monday 00:00 UTC (ISO week); month = first of month 00:00 UTC. Buckets with no underlying events are omitted, not zero-filled.

channel string<uuid> optional

Filter by channel UUID. Malformed values return 422 validation_failed.

identity string optional

Filter by sending identity. Accepts a full email address (the local-part is ignored — only the domain matches) or a bare domain.

Responses

200 Engagement buckets, oldest-first application/json

401 Missing, malformed, or unknown API key application/problem+json

403 Key lacks the required scope or plan limit violated application/problem+json

422 Query parameter or path value failed validation application/problem+json

429 Per-org rate limit exceeded application/problem+json

500 Unexpected server-side failure. The code is internal_error. The request_id field can be quoted to SendOps support to investigate. application/problem+json