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
Bearer authentication header of the form Bearer <token>, where <token> is your API key.
Query Parameters
The ID of the workspace
- Example: ws_1234567890
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
Keep the broadcasts whose name contains this text, ignoring case. Leading and trailing spaces are ignored.
- Example: autumn
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
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
Maximum number of broadcasts to return
- Default: 50
- Example: 50
Number of broadcasts to skip for pagination
- Default: 0
- Example: 0
Include full template details for each variation
- Default: false
- Example: false
Response
200 List of broadcasts retrieved successfully object
List of broadcasts
Show child attributes
Unique identifier for the broadcast
- Example: broadcast_12345
The ID of the workspace
- Example: ws_1234567890
Name of the broadcast
- Maximum length: 255
- Example: Spring Newsletter 2024
Communication channel type
- Example: email
Current status of the broadcast
- Available options: draft, scheduled, processing, paused, processed, cancelled, failed, testing, test_completed, winner_selected
- Example: draft
Show child attributes
List ID to send to
- Example: newsletter
Optional segment IDs to filter recipients
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 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
Whether the broadcast is scheduled (false after creation, set via broadcasts.schedule)
- Example: false
Scheduled date in YYYY-MM-DD format
- Example: 2024-03-15
Scheduled time in HH:MM format
- Example: 10:30
IANA timezone
- Example: America/New_York
Send at scheduled time in each recipient's timezone
- Example: false
Show child attributes
Whether A/B testing is enabled
- Example: true
Percentage of audience to use for testing
- Required range: x >= 1
- Required range: x <= 100
- Example: 20
Automatically send winning variation to remaining audience
- Example: true
Metric used to determine the winner
- Available options: open_rate, click_rate
- Example: open_rate
Duration of the test in hours (max 7 days)
- Required range: x >= 1
- Required range: x <= 168
- Example: 24
Test variations (2-8 variations allowed)
- Maximum items: 8
Show child attributes
Name of this variation
- Example: Variation A
Template ID for this variation
- Example: template_variant_a
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
Show child attributes
Number of recipients
Number of delivered messages
Number of opens
Number of clicks
Number of bounces
Number of complaints
Number of unsubscribes
Full template object (populated when with_templates=true)
Show child attributes
UTM source parameter
- Example: newsletter
UTM medium parameter
- Example: email
UTM campaign parameter
- Example: spring_2024
UTM term parameter
UTM content parameter
Configuration for external data feeds
Show child attributes
Show child attributes
Whether the global data feed is enabled
- Example: true
URL endpoint to fetch global data from (must be HTTPS)
- Example: https://api.example.com/broadcast-data
Custom HTTP headers to include in the request
Show child attributes
HTTP header name
- Example: Authorization
HTTP header value
- Example: Bearer token123
Cached data from the global feed (populated after fetch)
When the global feed was last fetched
Show child attributes
Whether the per-recipient data feed is enabled
- Example: true
URL endpoint to fetch per-recipient data from (must be HTTPS)
- Example: https://api.example.com/recipient-data
Custom HTTP headers to include in the request
Show child attributes
HTTP header name
- Example: Authorization
HTTP header value
- Example: Bearer token123
Custom metadata for the broadcast
ID of the winning template variation
- Example: template_winner
When the A/B test was sent
When the winning variation was sent
Number of emails added to the queue by orchestrator
- Example: 1000
Number of recipients in test phase
Number of recipients in winner phase
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
When the broadcast was created
When the broadcast was last updated
When the broadcast started sending
When the broadcast completed sending
When the broadcast was cancelled
When the broadcast was paused
Reason for pausing the broadcast
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 number of broadcasts matching the query
- Example: 45
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 message
401 Unauthorized - invalid or missing authentication token object
Error message
403 Forbidden - missing required permission object
Error message
500 Internal server error object
Error message