https://demo.notifuse.com/api/broadcasts.get Retrieves a single broadcast by ID. Optionally includes template details for each variation.
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
The ID of the broadcast
- Example: broadcast_12345
Include full template details for each variation
- Default: false
- Example: false
Response
200 Broadcast retrieved successfully object
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
400 Bad request - validation failed object
Error message
401 Unauthorized - invalid or missing authentication token object
Error message
404 Broadcast not found object
Error message
500 Internal server error object
Error message