Broadcasts

List broadcasts

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.

get/v1/sites/{site_id}/broadcasts

Request

  • Base URL
    https://api.getsitecontrol.com
  • Auth
    HTTP bearer

Path parameters

site_idinteger required

Query parameters

statusBroadcastStatus[]

Only broadcasts in any of these statuses; repeat for several

searchstring

Words of the name in order; case, spacing and punctuation are ignored. Or the exact id

created_sincestring date-time

Created at or after; without an offset, taken as UTC; a plain date means its start

updated_sincestring date-time

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

started_sincestring date-time

Sending first started at or after this moment (started_at); without an offset, taken as UTC; a plain date means its start

started_beforestring date-time

Sending first started before this moment, excluded; without an offset, taken as UTC; a plain date means its start

folder_idinteger

Only the items of this folder, an id from list_folders; 0 is General

cursorstring

next_cursor of the previous page, sent with the same order; omit for the first

limitinteger

Items per page

fieldsstring

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'oldest' | 'newest'

Order of a list. oldest: the oldest item first; newest: the newest item first, for the latest items without paging through the history.

Order of the items: oldest first (default) or newest first; asc and desc mean the same

Response

Successful Response

next_cursorstring nullable

Changes

No recorded changes to this operation across all 1 revision of this API.