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
Bearer authentication header of the form Bearer <token>, where <token> is your API key.
Body application/json
The ID of the workspace
Name of the broadcast
Show 3 child attributes Hide 3 child attributes
List ID to send to
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.
Show 6 child attributes Hide 6 child attributes
Whether A/B testing is enabled
Percentage of audience to use for testing
Automatically send winning variation to remaining audience
Metric used to determine the winner
Duration of the test in hours (max 7 days)
Test variations (2-8 variations allowed)
Show 5 child attributes Hide 5 child attributes
Name of this variation
Template ID for this variation
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.
Show 7 child attributes Hide 7 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 5 child attributes Hide 5 child attributes
UTM source parameter
UTM medium parameter
UTM campaign parameter
UTM term parameter
UTM content parameter
Configuration for external data feeds
Show 4 child attributes Hide 4 child attributes
Show 3 child attributes Hide 3 child attributes
Whether the global data feed is enabled
URL endpoint to fetch global data from (must be HTTPS)
Custom HTTP headers to include in the request
Show 2 child attributes Hide 2 child attributes
HTTP header name
HTTP header value
Cached data from the global feed (populated after fetch)
When the global feed was last fetched
Show 3 child attributes Hide 3 child attributes
Whether the per-recipient data feed is enabled
URL endpoint to fetch per-recipient data from (must be HTTPS)
Custom HTTP headers to include in the request
Show 2 child attributes Hide 2 child attributes
HTTP header name
HTTP header value
Custom metadata for the broadcast
See Broadcast.tracking_mode.
Response
201 Broadcast created successfully object
Show 26 child attributes Hide 26 child attributes
Unique identifier for the broadcast
The ID of the workspace
Name of the broadcast
Communication channel type
Current status of the broadcast
Show 3 child attributes Hide 3 child attributes
List ID to send to
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.
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
Whether the broadcast is scheduled (false after creation, set via broadcasts.schedule)
Scheduled date in YYYY-MM-DD format
Scheduled time in HH:MM format
IANA timezone
Send at scheduled time in each recipient's timezone
Show 6 child attributes Hide 6 child attributes
Whether A/B testing is enabled
Percentage of audience to use for testing
Automatically send winning variation to remaining audience
Metric used to determine the winner
Duration of the test in hours (max 7 days)
Test variations (2-8 variations allowed)
Show 5 child attributes Hide 5 child attributes
Name of this variation
Template ID for this variation
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.
Show 7 child attributes Hide 7 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 5 child attributes Hide 5 child attributes
UTM source parameter
UTM medium parameter
UTM campaign parameter
UTM term parameter
UTM content parameter
Configuration for external data feeds
Show 4 child attributes Hide 4 child attributes
Show 3 child attributes Hide 3 child attributes
Whether the global data feed is enabled
URL endpoint to fetch global data from (must be HTTPS)
Custom HTTP headers to include in the request
Show 2 child attributes Hide 2 child attributes
HTTP header name
HTTP header value
Cached data from the global feed (populated after fetch)
When the global feed was last fetched
Show 3 child attributes Hide 3 child attributes
Whether the per-recipient data feed is enabled
URL endpoint to fetch per-recipient data from (must be HTTPS)
Custom HTTP headers to include in the request
Show 2 child attributes Hide 2 child attributes
HTTP header name
HTTP header value
Custom metadata for the broadcast
ID of the winning template variation
When the A/B test was sent
When the winning variation was sent
Number of emails added to the queue by orchestrator
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.
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.
400 Bad request - validation failed object
Error message
401 Unauthorized - invalid or missing authentication token object
Error message
500 Internal server error object
Error message