https://demo.notifuse.com/api/broadcasts.update Updates an existing broadcast. Only broadcasts in draft, scheduled, or paused status can be updated.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your API key.
Body application/json
The ID of the workspace
- Example: ws_1234567890
ID of the broadcast to update
- Example: broadcast_12345
Name of the broadcast
- Maximum length: 255
- Example: Spring Newsletter 2024
Merged into the stored audience one key at a time, so a body naming only list retargets the broadcast without dropping its segments or its exclusion of unsubscribed contacts. Omit the whole object to leave the audience untouched.
Show child attributes
List ID to send to. Omit to keep the stored list.
- Example: newsletter
Segment IDs to filter recipients. Omit to keep the stored segments; send an empty array to remove segment targeting and send to the whole list.
Whether to exclude the list's unsubscribed contacts. Omit to keep the stored value; send false to mail them too, in emails without the List-Unsubscribe and List-Unsubscribe-Post headers. Bounced and complained contacts are never mailed, whatever this value.
- Example: true
Omit to keep the stored schedule. Sending it replaces the schedule wholesale, so a body carrying an empty or partial object clears is_scheduled — which a later resume reads to decide between restoring the schedule and sending now.
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
Omit to keep the stored test settings. These hold the broadcast's template variations, so sending a partial object detaches its templates.
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)
Omit to keep the stored UTM parameters; send an empty object to clear them.
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
Omit to keep the stored data feed settings and their last fetched data.
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. Omit to keep the stored metadata; send an empty object to clear it.
Omit to keep the stored mode. Can be changed only while the broadcast is a draft or scheduled. See Broadcast.tracking_mode.
- Available options: inherit, no_tracking
Response
200 Broadcast updated 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