Broadcasts

Create a broadcast

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

Creates a new broadcast campaign in draft status.

Important: Creating a broadcast does not schedule or send it. After creating the broadcast, you must call the /api/broadcasts.schedule endpoint to schedule or send it immediately.

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
name string required

Name of the broadcast

Max length 255 Example Spring Newsletter 2024
audience object required
Show 3 child attributes Hide 3 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
test_settings object
Show 6 child attributes Hide 6 child attributes
enabled boolean

Whether A/B testing is enabled

Example true
sample_percentage integer

Percentage of audience to use for testing

Min 1 Max 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

Options open_rate, click_rate Example open_rate
test_duration_hours integer

Duration of the test in hours (max 7 days)

Min 1 Max 168 Example 24
variations object[]

Test variations (2-8 variations allowed)

Max items 8
Show 5 child attributes Hide 5 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 7 child attributes Hide 7 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 5 child attributes Hide 5 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 4 child attributes Hide 4 child attributes
global_feed object
Show 3 child attributes Hide 3 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 2 child attributes Hide 2 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 3 child attributes Hide 3 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 2 child attributes Hide 2 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

tracking_mode string

See Broadcast.tracking_mode.

Options inherit, no_tracking

Response

201 Broadcast created successfully object
broadcast object
Show 26 child attributes Hide 26 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

Max length 255 Example Spring Newsletter 2024
channel_type string

Communication channel type

Example email
status string

Current status of the broadcast

Options draft, scheduled, processing, paused, processed, cancelled, failed, testing, test_completed, winner_selected Example draft
audience object
Show 3 child attributes Hide 3 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 5 child attributes Hide 5 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 6 child attributes Hide 6 child attributes
enabled boolean

Whether A/B testing is enabled

Example true
sample_percentage integer

Percentage of audience to use for testing

Min 1 Max 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

Options open_rate, click_rate Example open_rate
test_duration_hours integer

Duration of the test in hours (max 7 days)

Min 1 Max 168 Example 24
variations object[]

Test variations (2-8 variations allowed)

Max items 8
Show 5 child attributes Hide 5 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 7 child attributes Hide 7 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 5 child attributes Hide 5 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 4 child attributes Hide 4 child attributes
global_feed object
Show 3 child attributes Hide 3 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 2 child attributes Hide 2 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 3 child attributes Hide 3 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 2 child attributes Hide 2 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.

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

500 Internal server error object
error string required

Error message