v1

latestOpenAPI 3.1.0MIT2026-07-243952451019.0 KB

Emails::Broadcast

List Email Broadcasts

List all email broadcasts for a workspace. Filterable by id and status.

get/workspaces/{workspace_id}/emails/broadcasts

Path parameters

workspace_idinteger required

Query parameters

afterstring

ID of item after which the collection should be returned. More examples and info about pagination in our guides.

sort_order'asc' | 'desc'

Sort order of a list response. Use 'desc' to reverse the default 'asc' (ascending) sort order. Examples in our guides.

sort_property'id' | 'updated_at'

Sort property of a list response. The default is id and thus the created_at order. If you sort by other properties, we additionally sort by id implicitly as a secondary sort property, so that you can rely on the sort order to be deterministic even if the main sort property ends up with the same values.

idstring

A comma-separated list of broadcast IDs to filter by.

statusstring

A comma-separated list of statuses to filter by (draft, scheduled, sending, paused, unhealthy, complete, canceled).

Filter by available properties in query params, like this: api/v2/resources?filter[id]=value&filter[another_property]=value1,value2. Check our Filtering guide for examples and all about filtering here.

{
  "id": "1,42",
  "status": "draft,scheduled"
}

Response

idinteger

Broadcast ID

public_idstring nullable

Broadcast public ID

workspace_idinteger

Workspace ID

namestring nullable

Internal name for the broadcast

subjectstring nullable

Email subject line seen by recipients

preheadlinestring nullable

Preview text shown in email clients before opening (max 150 characters)

Current broadcast status. New broadcasts start as draft.

origination_channel_typestring nullable

The type of origination channel that created this broadcast

origination_channel_idinteger nullable

The ID of the origination channel

external_idstring nullable

An optional external identifier for tracking purposes

filter_idinteger nullable

The contact filter determining which contacts receive this broadcast. Numeric Refine::StoredFilter id (not the public id) — the broadcast's own unnamed copy of the filter, created automatically from the filter_id (or recipients) supplied on create/update. null until an audience is set. See Applying filters to email broadcasts.

send_atstring nullable

Scheduled send date

send_at_local_timestring nullable

Scheduled send time in HH:MM:SS format, relative to the specified time zone

time_zonestring nullable

Time zone for scheduled sending

send_immediatelyboolean

Whether the broadcast sends immediately upon creation

sending_atstring date-time nullable

Timestamp when sending actually began

complete_atstring date-time nullable

Timestamp when sending completed

from_emailstring nullable

The sender email address

from_namestring nullable

The sender display name associated with the from address

reply_to_emailstring nullable

The reply-to email address

topic_idsinteger[]

IDs of topics associated with this broadcast

created_atstring date-time nullable

Created at datetime

updated_atstring date-time nullable

Updated at datetime

Example response

[
  {
    "id": 1,
    "public_id": "GhIjKl",
    "workspace_id": 42000,
    "name": "Weekly Newsletter",
    "subject": "This Week's Updates",
    "preheadline": "Check out what's new",
    "status": "draft",
    "origination_channel_type": null,
    "origination_channel_id": null,
    "external_id": null,
    "filter_id": null,
    "send_at": null,
    "send_at_local_time": null,
    "time_zone": "Pacific Time (US & Canada)",
    "send_immediately": false,
    "sending_at": null,
    "complete_at": null,
    "from_email": "marketing@example.com",
    "from_name": "Marketing Team",
    "reply_to_email": null,
    "template": {
      "id": 3001,
      "public_id": "TmPl01",
      "name": "Weekly Newsletter Template"
    },
    "topic_ids": [
      1,
      2
    ],
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-01T00:00:00.000Z"
  }
]