Broadcasts

Update a broadcast

POST https://demo.notifuse.com/api/broadcasts.update

Updates an existing broadcast. Only broadcasts in draft, scheduled, or paused status can be updated.

Authorizations

Authorization string header required

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

Body application/json

workspace_id string required

The ID of the workspace

  • Example: ws_1234567890
id string required

ID of the broadcast to update

  • Example: broadcast_12345
name string required

Name of the broadcast

  • Maximum length: 255
  • Example: Spring Newsletter 2024
audience object

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 string

List ID to send to. Omit to keep the stored list.

  • Example: newsletter
segments string[]

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.

exclude_unsubscribed boolean

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
schedule object

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
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

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
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

Omit to keep the stored UTM parameters; send an empty object to clear them.

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

Omit to keep the stored data feed settings and their last fetched data.

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. Omit to keep the stored metadata; send an empty object to clear it.

tracking_mode string

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
broadcast object
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
400 Bad request - validation failed object
error string required

Error message

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

Error message

404 Broadcast not found object
error string required

Error message

500 Internal server error object
error string required

Error message