Broadcasts

List broadcasts

GET https://demo.notifuse.com/api/broadcasts.list

Retrieves a list of broadcasts with pagination and optional filtering by status, name and start date. Supports fetching template details for each variation, and the number of broadcasts in each status. Requires the broadcasts read permission.

Authorizations

Authorization string header required

Bearer authentication header of the form Bearer <token>, where <token> is your API key.

Query Parameters

workspace_id string required

The ID of the workspace

  • Example: ws_1234567890
status string

Filter broadcasts by status: one status, or several separated by commas. Each one is draft, scheduled, processing, paused, processed, cancelled, failed, testing, test_completed or winner_selected; any other value is refused with 400.

  • Example: processing,paused
search string

Keep the broadcasts whose name contains this text, ignoring case. Leading and trailing spaces are ignored.

  • Example: autumn
started_after string<date-time>

Keep the broadcasts that started sending at or after this RFC 3339 date-time. A broadcast that never started is left out. Applies to the rows, total_count and status_counts. An unreadable value is refused with 400.

  • Example: 2026-10-13T00:00:00Z
with_status_counts boolean

Return status_counts, the number of broadcasts in each status. The counts follow search and started_after but not status, so each status tab has its own number. A value that is not a boolean is refused with 400.

  • Default: false
  • Example: true
limit integer

Maximum number of broadcasts to return

  • Default: 50
  • Example: 50
offset integer

Number of broadcasts to skip for pagination

  • Default: 0
  • Example: 0
with_templates boolean

Include full template details for each variation

  • Default: false
  • Example: false

Response

200 List of broadcasts retrieved successfully object
broadcasts object[]

List of broadcasts

Show child attributes
id string

Unique identifier for the broadcast

  • Example: broadcast_12345
workspace_id string

The ID of the workspace

  • Example: ws_1234567890
name string

Name of the broadcast

  • Maximum length: 255
  • Example: Spring Newsletter 2024
channel_type string

Communication channel type

  • Example: email
status string

Current status of the broadcast

  • Available options: draft, scheduled, processing, paused, processed, cancelled, failed, testing, test_completed, winner_selected
  • Example: draft
audience object
Show child attributes
list string required

List ID to send to

  • Example: newsletter
segments string[]

Optional segment IDs to filter recipients

exclude_unsubscribed boolean

Whether to exclude the list's unsubscribed contacts. Omitting the key excludes them; send false to mail them too, e.g. for a legal notice. With false the emails carry no List-Unsubscribe and List-Unsubscribe-Post headers. Bounced and complained contacts are never mailed, whatever this value.

  • Default: true
  • Example: true
schedule object

Schedule settings for a broadcast. Note: When a broadcast is first created, these fields are empty/false. Use the /api/broadcasts.schedule endpoint to configure scheduling.

Show child attributes
is_scheduled boolean

Whether the broadcast is scheduled (false after creation, set via broadcasts.schedule)

  • Example: false
scheduled_date string

Scheduled date in YYYY-MM-DD format

  • Example: 2024-03-15
scheduled_time string

Scheduled time in HH:MM format

  • Example: 10:30
timezone string

IANA timezone

  • Example: America/New_York
use_recipient_timezone boolean

Send at scheduled time in each recipient's timezone

  • Example: false
test_settings object
Show child attributes
enabled boolean

Whether A/B testing is enabled

  • Example: true
sample_percentage integer

Percentage of audience to use for testing

  • Required range: x >= 1
  • Required range: x <= 100
  • Example: 20
auto_send_winner boolean

Automatically send winning variation to remaining audience

  • Example: true
auto_send_winner_metric string

Metric used to determine the winner

  • Available options: open_rate, click_rate
  • Example: open_rate
test_duration_hours integer

Duration of the test in hours (max 7 days)

  • Required range: x >= 1
  • Required range: x <= 168
  • Example: 24
variations object[]

Test variations (2-8 variations allowed)

  • Maximum items: 8
Show child attributes
variation_name string

Name of this variation

  • Example: Variation A
template_id string required

Template ID for this variation

  • Example: template_variant_a
sender_id string

ID of one of the marketing email integration's senders. This variation leaves from it instead of its template's sender. Omitted, the variation uses its template's sender: sending test_settings without it clears a sender chosen earlier. An ID that is not one of the integration's senders is refused with a 400. A variation whose chosen sender has since been removed from the integration is queued for no further recipient until another sender is chosen: the broadcast cannot be scheduled, cannot be resumed while that variation still has recipients to queue, and pauses at the next run of its sending task if it is queuing them. Emails already queued keep the sender they were queued with; nothing falls back to another address. Saving test_settings checks every variation's sender, a losing one's included. Two variations using the same template must choose the same sender.

  • Example: 3f1c2a9e-7b4d-4e1a-9c2f-5d8e6a0b1c3d
metrics object
Show child attributes
recipients integer

Number of recipients

delivered integer

Number of delivered messages

opens integer

Number of opens

clicks integer

Number of clicks

bounced integer

Number of bounces

complained integer

Number of complaints

unsubscribed integer

Number of unsubscribes

template object | null

Full template object (populated when with_templates=true)

utm_parameters object
Show child attributes
source string

UTM source parameter

  • Example: newsletter
medium string

UTM medium parameter

  • Example: email
campaign string

UTM campaign parameter

  • Example: spring_2024
term string

UTM term parameter

content string

UTM content parameter

data_feed object

Configuration for external data feeds

Show child attributes
global_feed object
Show child attributes
enabled boolean

Whether the global data feed is enabled

  • Example: true
url string

URL endpoint to fetch global data from (must be HTTPS)

  • Example: https://api.example.com/broadcast-data
headers object[]

Custom HTTP headers to include in the request

Show child attributes
name string required

HTTP header name

  • Example: Authorization
value string required

HTTP header value

  • Example: Bearer token123
global_feed_data object

Cached data from the global feed (populated after fetch)

global_feed_fetched_at string<date-time> | null

When the global feed was last fetched

recipient_feed object
Show child attributes
enabled boolean

Whether the per-recipient data feed is enabled

  • Example: true
url string

URL endpoint to fetch per-recipient data from (must be HTTPS)

  • Example: https://api.example.com/recipient-data
headers object[]

Custom HTTP headers to include in the request

Show child attributes
name string required

HTTP header name

  • Example: Authorization
value string required

HTTP header value

  • Example: Bearer token123
metadata object

Custom metadata for the broadcast

winning_template string | null

ID of the winning template variation

  • Example: template_winner
test_sent_at string<date-time> | null

When the A/B test was sent

winner_sent_at string<date-time> | null

When the winning variation was sent

enqueued_count integer

Number of emails added to the queue by orchestrator

  • Example: 1000
test_phase_recipient_count integer

Number of recipients in test phase

winner_phase_recipient_count integer

Number of recipients in winner phase

test_paused_seconds integer

Seconds an A/B test waiting for its winner spent paused. The automatic winner is picked once the test duration has passed without them. Omitted when 0.

  • Example: 3600
created_at string<date-time>

When the broadcast was created

updated_at string<date-time>

When the broadcast was last updated

started_at string<date-time> | null

When the broadcast started sending

completed_at string<date-time> | null

When the broadcast completed sending

cancelled_at string<date-time> | null

When the broadcast was cancelled

paused_at string<date-time> | null

When the broadcast was paused

pause_reason string | null

Reason for pausing the broadcast

tracking_mode string

Absent or inherit follows the workspace tracking settings and each recipient's tracking consent (stored as absent). no_tracking sends every email without the open pixel and the click-tracking redirect, keeping the UTM parameters; it cannot be combined with an A/B test whose winner is sent automatically.

  • Available options: inherit, no_tracking
total_count integer

Total number of broadcasts matching the query

  • Example: 45
status_counts map<string, integer>

Returned only with with_status_counts=true, always an object then. The number of broadcasts in each status, following search and started_after but not status. A status no broadcast has is absent.

400 Bad request - validation failed object
error string required

Error message

401 Unauthorized - invalid or missing authentication token object
error string required

Error message

403 Forbidden - missing required permission object
error string required

Error message

500 Internal server error object
error string required

Error message