Get a broadcast
const url = 'https://api.getsitecontrol.com/v1/sites/1/broadcasts/1';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 \ --header 'Authorization: Bearer <token>'One broadcast with the fields of list_broadcasts, nothing shortened, plus
its whole audience: the condition tree and the recipient settings (limit,
sort, quality gate), the A/B test split and duration, and whether links get
UTM parameters. How many contacts it reaches is get_broadcast_recipients,
its numbers are in get_broadcast_stats, its clicks by link in
get_broadcast_clicks, the body of its e-mail in get_email.
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
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
Who receives the broadcast. Only subscribed contacts are sent to: that condition is always added and is not in the tree. The tree is written as segment conditions.
Which contacts belong to the segment: a tree of conditions, applied to the contacts as they are at the moment it is used.
Conditions are the condition language of the Getsitecontrol admin, with its
own variable names and codes; they are not the field names and values of
Contact. A segment written here can be edited in the admin, and the
variables below are the ones the admin’s condition editor offers.
A node is an object with exactly op and args. A group has op and
or or and nodes in args; a leaf has the variable {{$contact.<name>}}
as the first argument, then its values: none for * (is set) and
undefined (is not set), two for between and !between, one for the
rest. To negate, use the opposite operator; there is no not node.
The admin editor shows a root group whose args are groups, each holding
leaves, as in the example; write that shape so the segment stays editable
there. {"op": "and", "args": []} matches every contact of the site.
Conditions are saved as sent.
Values are integers, strings or, for ina and !ina, a list of them.
| Operator | Meaning |
|---|---|
=, != | equals, differs |
ina, !ina | any of the list, none of it |
<, >, between, !between | compare; between includes both ends |
^, $, in, match (and !-forms) | starts with, ends with, contains, wildcard * without case |
*, undefined | is set, is not set |
Text operators other than match are case sensitive, except on
$contact.email: a contact’s email is stored lowercase and compared without
case by every operator. In ^, $, in,
match and their negations _ matches any single character and % is a
plain character.
| Variable | Operators | Value |
|---|---|---|
$contact.email, phone, firstName, lastName | text operators, =, !=, ina, !ina, *, undefined | string |
$contact.country | =, !=, ina, !ina, *, undefined | ISO 3166-1 alpha-2, upper case |
$contact.date | =, !=, <, >, between, !between, *, undefined | date the contact was added |
$contact.isSubscribed | = | marketing status: S subscribed, U unsubscribed, B bounced |
$contact.emailQuality | =, !=, ina, !ina, *, undefined | Corp+, Corp corporate, Pers+, Pers personal (+ is the higher grade), Edu education, Gov government, Risk risky, Temp disposable, Unk unknown |
$contact.tags | =, !=, ina, !ina, *, undefined | tag ids from list_tags |
$contact.segments | =, !=, ina, !ina | ids from list_segments, as integers |
$contact.emailSend, emailOpen, emailClick | =, !=, ina, !ina, *, undefined | e-mail id, as email_id of a broadcast |
$contact.emailSendCount, emailOpenCount, emailClickCount | =, !=, <, >, between, !between, *, undefined | integer, not negative |
$contact.emailSendDate, emailOpenDate, emailClickDate | as $contact.date | the latest event |
$contact.$shopifySpent, $shopifyOrders | as the counts | integer |
$contact.$shopifyOrderDate | as $contact.date | the latest order |
$contact.<field id> | by the field type from list_contact_fields: text, integer, number, date or datetime | as the field; boolean and other fields are refused |
ina and !ina on tags and segments take at least one id. On
$contact.tags, = means the contact has that tag among its tags.
$contact.isSubscribed compares the stored status code as the admin does:
S does not match a contact who confirmed double opt-in, U does not match
one who never subscribed or awaits double opt-in, and B matches every
bounced contact. The contact statuses subscribed, unsubscribed and
bounced are the broader groups.
Ids are integers or strings of digits. A number is a 32-bit integer or a
string holding one. A date is YYYY-MM-DD or ISO 8601 with an offset. For $contact.date,
$shopifyOrderDate and datetime fields, a value at midnight is a whole
day: = and != cover the day, and the second value of between runs to
its end. Date fields and $contact.email*Date compare with midnight
exactly.
Nested segments may not form a cycle. A list must reference each nested segment once, and not one nested inside another.
Conditions are checked the way they run: nested segments must exist and the whole tree must compile, so an unknown variable or a value of the wrong type is refused. Conditions saved in the admin are returned as they are and may use other variables and values.
null only together with non-empty warnings
object
At most this many recipients; null when not limited
Which contacts the limit keeps
E-mail qualities left out of the audience; empty when none is
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
Percent of the audience the variants are tested on; null without A/B
Hours the test runs before the winner is chosen; null without A/B
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
object
Whether UTM parameters are added to the e-mail’s links; null without an e-mail
{ "status": "draft", "status_reason": "ab_test", "sender": { "domain": { "state": "verified" } }, "audience": { "recipient_settings": { "sort": "newest", "quality_gate": [ "corporate_prime" ] } }, "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
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
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