Broadcast statistics
const url = 'https://api.getsitecontrol.com/v1/sites/1/broadcasts/1/stats';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api.getsitecontrol.com/v1/sites/1/broadcasts/1/stats \ --header 'Authorization: Bearer <token>'E-mail numbers of one broadcast over its whole life, its A/B variants
included, plus how many e-mails are still queued and the numbers of each A/B
variant. For a period use get_broadcasts_stats_by_broadcast with this id.
While the broadcast is being prepared, sent or paused, progress gives the
e-mails sent and left, the current step and the estimated finish time.
Every number counts e-mails, one e-mail being one message to one recipient,
and each e-mail at most once per metric: send e-mails sent, including those
rejected on sending; bounce e-mails that bounced or were rejected on
sending; deliver is send minus bounce, never below zero; open e-mails
opened; click e-mails with at least one link clicked; unsubscribe e-mails
whose recipient unsubscribed through them; complaint e-mails reported as
spam through the recipient’s mail provider. rates next to each total
gives the delivery, open, click, click-to-open, unsubscribe, complaint and
bounce rates, rounded to 4 places; a rate is null when its denominator is 0,
as it is undefined, not zero.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Broadcast id from list_broadcasts
Broadcast id from list_broadcasts
Responses
Section titled “Responses”object
All e-mails of the broadcast, every A/B variant included
object
Rates computed from total, so the open rate is rates.open; every key is always present, null when its denominator is 0
object
Delivery rate: deliver / send; null when send is 0: the rate is undefined, not zero
Open rate: open / deliver; null when deliver is 0: the rate is undefined, not zero
Click rate: click / deliver; null when deliver is 0: the rate is undefined, not zero
Click-to-open rate: click / open; null when open is 0: the rate is undefined, not zero. A click is counted without an open when the recipient’s mail app does not load images, so it can exceed 1
Unsubscribe rate: unsubscribe / deliver; null when deliver is 0: the rate is undefined, not zero
Spam complaint rate: complaint / deliver; null when deliver is 0: the rate is undefined, not zero
Bounce rate: bounce / send; null when send is 0: the rate is undefined, not zero
E-mails waiting to be sent, as progress.queued. null for a draft or a scheduled broadcast and when the count is not available; 0 once stopped or completed
A/B variants in their order, empty without A/B. The winner also counts the e-mails of the main phase. A deleted e-mail shows zeros.
object
The variant’s e-mail, as in ab_test.variant_email_ids
Subject of the variant’s e-mail; null when the e-mail was deleted
Preview text of the variant’s e-mail, shown after the subject in inboxes; null when it has none or the e-mail was deleted
From address of the variant’s e-mail; null when the e-mail was deleted
E-mail counts; every key is always present.
open, click and the rest count each e-mail once. send includes
e-mails rejected on sending, which are also counted in bounce.
complaint is spam complaints reported by mail providers.
For a period, each number counts the events dated in it, so the numbers
are independent: a bounce may fall in a later period than its sending.
deliver is send minus bounce, never below zero.
object
Rates computed from total, so the open rate is rates.open; every key is always present, null when its denominator is 0
object
Delivery rate: deliver / send; null when send is 0: the rate is undefined, not zero
Open rate: open / deliver; null when deliver is 0: the rate is undefined, not zero
Click rate: click / deliver; null when deliver is 0: the rate is undefined, not zero
Click-to-open rate: click / open; null when open is 0: the rate is undefined, not zero. A click is counted without an open when the recipient’s mail app does not load images, so it can exceed 1
Unsubscribe rate: unsubscribe / deliver; null when deliver is 0: the rate is undefined, not zero
Spam complaint rate: complaint / deliver; null when deliver is 0: the rate is undefined, not zero
Bounce rate: bounce / send; null when send is 0: the rate is undefined, not zero
How far a broadcast being prepared, sent or paused has got and when it is expected to finish; null in any other status
object
E-mails sent so far, as total.send
E-mails left to send, the same as queued of the response; while the audience is being selected, the contacts matching it. null when the count is not available
sent plus queued; null together with queued
Estimated time (UTC) the last e-mail is sent; for an A/B test it includes the test duration and the sending to the rest of the audience. null while the audience is being selected, while paused and together with queued
Audience_segmentation: the recipients are being selected and queued. ab_test_sending: an A/B broadcast is sending its variants to the test group. ab_test_waiting: the test e-mails are sent and the winner is being chosen. sending: the e-mails are being sent to the recipients.
Running: the step goes on. paused: paused by a person or via the API. paused_balance: paused because the e-mail balance ran out.
{ "progress": { "step": "audience_segmentation", "step_status": "running" }}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Authentication scheme: Bearer
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
site_not_found: no such site in your account; broadcast_not_found: the site has no broadcast with this id, or it was deleted
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
rate_limited: a limit of the key or the account is spent; statistics also spend the heavy request limit of the key. Retry after Retry-After seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Seconds until the bucket refills
temporarily_unavailable: the numbers took too long to count or the limits cannot be checked right now; retry later or shorten the period
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds