List broadcasts
const url = 'https://api.getsitecontrol.com/v1/sites/1/broadcasts?limit=50&order=oldest';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?limit=50&order=oldest' \ --header 'Authorization: Bearer <token>'Broadcasts (e-mail campaigns) of the site in ascending order of id
(order=newest for the latest first), with
their status, e-mail subject, sender, audience, schedule, A/B test and folder.
Filters combine: every one given must match. started_since and
started_before select by when sending first started (started_at), so a
broadcast scheduled but not started yet is left out; created_since is when
it was created.
Nested lists keep their first 5 entries and texts their first 200 characters (links stay
whole); truncated names what was cut, get_broadcast has it whole. A page holds up to limit broadcasts; while
next_cursor is set, pass it as cursor for the next page. For the numbers
of a page of broadcasts call get_broadcasts_stats_by_broadcast with their
ids.
Deleted broadcasts are not listed. A broadcast without an e-mail is listed
with email_id, subject, preview_text and every field of sender null.
To keep a copy in sync, walk the whole list with the cursor and no filters
once. After that, pass updated_since set to the start of the previous walk
minus a margin of a few minutes, and merge by id. The margin is required:
a change may be stamped slightly earlier than it becomes visible.
updated_at moves with a change of the broadcast, a change of its status by
the user, the scheduler or the sender, the A/B result and a change or
deletion of the broadcast’s e-mail, except a change by the support team.
It does not move with new statistics or a move to a folder. A deleted
broadcast simply disappears. Repeat the full walk now and then to notice all
of these.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Query Parameters
Section titled “Query Parameters”Only broadcasts in any of these statuses; repeat for several
Only broadcasts in any of these statuses; repeat for several
Part of the name, case ignored, or the exact id
Part of the name, case ignored, or the exact id
Created at or after; without an offset, taken as UTC; a plain date means its start
Created at or after; without an offset, taken as UTC; a plain date means its start
updated_at at or after: changes of the broadcast and its e-mails, not new statistics or folder moves; deleted broadcasts are not listed; without an offset, taken as UTC; a plain date means its start
updated_at at or after: changes of the broadcast and its e-mails, not new statistics or folder moves; deleted broadcasts are not listed; without an offset, taken as UTC; a plain date means its start
Sending first started at or after this moment (started_at); without an offset, taken as UTC; a plain date means its start
Sending first started at or after this moment (started_at); without an offset, taken as UTC; a plain date means its start
Sending first started before this moment, excluded; without an offset, taken as UTC; a plain date means its start
Sending first started before this moment, excluded; without an offset, taken as UTC; a plain date means its start
Only the items of this folder, an id from list_folders; 0 is General
Only the items of this folder, an id from list_folders; 0 is General
next_cursor of the previous page, sent with the same order; omit for the first
next_cursor of the previous page, sent with the same order; omit for the first
Items per page
Items per page
Comma-separated fields to keep in each item, for example id,name; each item then carries only those fields and id. Omit for every field
Comma-separated fields to keep in each item, for example id,name; each item then carries only those fields and id. Omit for every field
Order of the items: oldest first (default) or newest first; asc and desc mean the same
Order of the items: oldest first (default) or newest first; asc and desc mean the same
Responses
Section titled “Responses”One page of a list; next_cursor is null on the last page.
object
object
Name in the admin
testing is an A/B broadcast testing its variants or choosing the winner. null only together with non-empty warnings
Why the broadcast entered its status; null when a person simply made the change. Who did it, and the whole story, is in list_broadcast_history
The broadcast’s e-mail; null when it has none
Subject of the e-mail
Preview text of the e-mail, shown after the subject in inboxes
object
The From display name; null when the e-mail has none
The From address the e-mail goes out with: the one set in the editor when its domain is verified for the site, the default Getsitecontrol address otherwise
Where replies go; null when replies go to address
The site’s sending domain of the address set in the editor; null when that address is not on one of them
object
Id in list_email_domains
True: e-mails go out from this domain; false: from the default address until it is verified
Where verification stands
object
Segments the audience conditions refer to
object
Segment id from list_segments
Null when the segment was deleted: then nobody receives it
True: the conditions also hold rules besides segments; get_broadcast has them all
At most this many recipients; null when not limited
True: the conditions select every subscribed contact, the admin’s All contacts; it is stored as an empty list of segments
Null only together with non-empty warnings
object
New modes may be added; strict clients must accept unknown values
Scheduled start, with the offset of timezone; null when none is set
IANA time zone the time was scheduled in
Hours of the recipient’s day to send at; timezone mode only
Target hours the sending is spread over, not a promised end: the actual end follows the sender’s pace, see progress.finishes_at of the broadcast’s stats; smart and ramp modes only
object
Whether the broadcast tests e-mail variants on a part of the audience and sends the winner to the rest
E-mail ids of the variants in their order; empty without A/B
The winning variant; null until the winner is chosen
What picked the winner; null until the test has a result
Last change of the broadcast, its status or its e-mail; see the list description; a move to another folder does not change it
When sending first started; null until then
When the broadcast was stopped or completed; null until then
Latest start or scheduling by a person; null when there was none
Null when the user was deleted
object
Null for Support or for a user who was deleted
Null when the user has no name
The user’s sign-in e-mail; null for Support
Who made the launch at launched_at; null together with it
object
Null for Support or for a user who was deleted
Null when the user has no name
The user’s sign-in e-mail; null for Support
Last change made in the editor, to the broadcast or to one of its e-mails, A/B variants included
Who made the change at edited_at; null when unknown: by an API key, by a user deleted since, or before authors were recorded
object
Null for Support or for a user who was deleted
Null when the user has no name
The user’s sign-in e-mail; null for Support
object
0 is General, where items outside any folder are
Empty unless the broadcast could not be read in full; wording is not stable, do not parse
Parts shortened in the list, as paths; the card has them whole. Empty when nothing was cut
{ "items": [ { "status": "draft", "status_reason": "ab_test", "sender": { "domain": { "state": "verified" } }, "schedule": { "mode": "immediate" }, "ab_test": { "winning_metric": "open_rate" }, "truncated": [] } ]}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
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
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
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