Engagement time series
Time-bucketed open and click activity. Each bucket emits raw sent,
delivered, total opens/clicks, and unique_opens/unique_clicks
(distinct messages opened or clicked within the bucket). Every event
counts in the bucket it happened in, so an open the day after a send
lands in the next day's bucket.
Rate formulas:
open_rate = unique_opens / deliveredclick_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 message opened or clicked on
more than one day inside the bucket may be counted more than once in
unique_opens/unique_clicks. day buckets are exact. (The SendOps
dashboard defaults to counting by send date instead; this endpoint
counts by event date.)
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 optional Filter by channel — its UUID, or the channel's name, which is the handle GET /v1/channels returns and GET /v1/channels/{name} is keyed on. A value that names no channel in the org returns 422 validation_failed rather than an empty page, so a typo reads as a typo instead of as a channel with no traffic.
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
Errors follow the RFC 7807 problem format — see the error reference.
data array<object> required Each entry in data:
period string<date-time> required sent integer<int64> required delivered integer<int64> required SES Delivery events: messages accepted by the receiving server (SMTP 250); not inbox placement.
opens integer<int64> required unique_opens integer<int64> required clicks integer<int64> required unique_clicks integer<int64> required open_rate number<double> required click_rate number<double> required validation_failed Problem. When the refusal is about a
reference — a segment key, template slug, topic or attribute name the
organization does not have — it additionally carries validation_code,
field, line/column, missing, candidates and next_step, so a
client can correct the call without a second round of guessing. See
ValidationProblem.
application/problem+json code is internal_error. The
request_id field can be quoted to SendOps support to investigate.
application/problem+json