Scopes
Campaign analytics
opens and clicks come in two cardinalities:
total– counted per email, bots excluded. The same email opened five times counts once; opening two different steps counts twice.uniqueLeads– distinct leads who did it at least once.
uniqueLeads, which is why a single enthusiastic reader cannot
push your open rate above 100%.
replies is a flat number – distinct leads who replied. There is no raw reply-event
count, so it is deliberately not dressed up as two cardinalities.
A rate of
null means “no denominator”, not “zero percent”. A campaign that has not
sent anything yet returns "open": null – not 0. If we returned 0, a chart would
show your open rate collapsing to zero on days you simply weren’t sending. Check for
null before plotting.Out-of-office replies
replies counts distinct leads who replied. Pass excludeOOO=true to exclude
out-of-office auto-replies and count only replies from humans:
Breakdowns
Ask for extra detail withbreakdown. Repeat the parameter or pass a comma-separated
list. Each breakdown is a separate query, so request only what you will actually read.
Bounce breakdown
Most outreach APIs give you a singlebounced number. That number cannot tell you what
to do. This one can:
recipientBounces are their problem – the address is dead, so clean your list.
senderBounces are yours – reputation, authentication, or content got you refused.
Scrubbing your list will not fix those, and treating them as one number is how a
deliverability problem hides behind a “normal” bounce rate.
Subsequences
A campaign with subsequences also getssubsequences - one entry per
subsequence, with all-time counters (not limited to the period):
positiveRate is positive leads among those who replied (null when nobody did).
excludeOOO=true applies here too: leads whose status is Out of office are not counted
in replied.
By default the campaign’s totals and breakdowns cover the campaign together with its
subsequences (deleted subsequences included – their emails were really sent). Nothing is
counted twice:
- every email event (sent, open, click, reply, bounce, unsubscribe) belongs to the sequence that sent the email;
- a positive lead, a conversion and its value belong to the sequence whose email the lead replied to. If that subsequence was deleted before the lead’s status changed, they count for the main sequence; what was recorded before the deletion stays with the deleted subsequence;
- a person counts once in the campaign’s lead counts, even after going through the main sequence and a subsequence.
sent, delivered, bounces, unsubscribed,
opens.total, clicks.total, positiveLeads, conversions and conversionValue.
Deleted subsequences are in the campaign’s totals only: they are not listed in
subsequences. For a campaign that had a
deleted subsequence, the main sequence plus the listed subsequences can therefore be lower
than the campaign’s totals - the difference is the deleted subsequences’ share.
Lead counts do not add up: leadsContacted, opens.uniqueLeads, clicks.uniqueLeads and
replies (leads who replied, not reply emails) count a person once in each sequence and
once in the campaign. A lead who replied in the main sequence and in a subsequence is 1 + 1
across the sequences and 1 in the campaign’s replies, so the campaign can be lower than
the sum of its parts.
With startDate / endDate, opens, clicks and replies count the leads emailed in the period
and their engagement: for the campaign, anyone it emailed in the period; for one sequence,
only the leads that sequence emailed. In a period these numbers of the campaign can
therefore also be higher than the sum of its parts.
The same parameters work on
/analytics/timeseries. With breakdown=sequence, the steps
are those of the main sequence, or of the subsequence when subsequenceId is set. A
subsequence id is not accepted as a campaign id here (404).
Over time
sent, delivered, opens, clicks, replies, bounces and
unsubscribed – so bounce rate and unsubscribe rate over time are chartable directly,
without a second call.
interval accepts day, week or month. Long windows are automatically coarsened to
keep the series readable; the response echoes the interval it actually used, which may
be coarser than the one you asked for. Read it back rather than assuming.
Workspace roll-up
activeCampaigns, sendingAccounts, and the
highest-volume campaigns. Use it for a top-level view, then drill into a campaign.
A campaign’s emails include its subsequences, and a person is counted once in the lead
totals even if they went through several sequences of one campaign.
Reporting windows and retention
startDate and endDate are ISO-8601. Passing only startDate means “from then until
now”.
Your plan retains a fixed window of history. If you ask for a start date older than that,
the window is moved forward and the response tells you:
What this API does not report
These are deliberately absent rather than silently zero:- Spam-complaint rate. We do not ingest feedback loops, so we cannot count complaints.
Returning
0would read as “no complaints” instead of “not measured”. - Hourly granularity. The smallest bucket is a day.
- Per-link click-through. Clicks are counted, but not attributed to individual links.