# Broadcasts
Broadcasts are one-time marketing sends to a broad audience or a saved segment. Use the API to review broadcast history, create campaigns, and schedule approved sends with explicit audience rules.
## Available Endpoints
## The Broadcast Model
The broadcast model describes the email itself, the tags and segments it was sent to, and its send rate and open rate.
### Properties
- **name** (`string`):
The name of the broadcast campaign.
- **subject** (`string`):
The subject of the email.
- **content** (`string`):
The content of the email.
- **type** (`string`):
The type of email. `plain` for Bento's CSS or `raw` to use your own.
- **from** (`object`):
A `key`/`value` object for the sender. Must be an author in your account.
- **inclusive_tags** (`string`):
A comma separated list of tags to send to.
- **exclusive_tags** (`string`):
A comma separated list of tags you do not want the email to go to.
- **segment_id** (`string`):
The segment ID for the campaign.
- **batch_size_per_hour** (`integer`):
The number of emails to send per hour to ensure the highest delivery.
---
## Get Broadcasts {{ tag: 'GET', label: '/v1/fetch/broadcasts' }}
Returns a list of broadcasts in your account.
> The app does not support exporting broadcast history directly. Use this endpoint to get a copy of all your broadcasts instead.
- **site_uuid** (`string`):
Your site UUID.
- **page** (`integer`):
Pagination number. If you have many broadcasts, you can paginate through them by adding the page parameter.
For example, to get the second page of broadcasts add ?page=2 to the end of the url. Be
sure to continue to add the site_uuid parameter to the end of the url.
- **status** (`string`):
Optional status filter. Supported values are `sent`, `draft`, `sending`, `scheduled`, `paused`, and `canceled`.
If omitted, Bento defaults to `sent`. `cancelled` is also accepted as an alias for `canceled`.
Unsupported values also fall back to `sent`.
### Response
Returns a collection of broadcasts and their details.
> The example response below shows a draft broadcast. Draft broadcasts only return `template.template_id`. Other
> broadcast statuses return the full template payload, including `subject`, `to`, and `html`.
- **data** (`array`):
Broadcast records.
- **data[].id** (`string`):
Broadcast identifier.
- **data[].name** (`string`):
Broadcast campaign name.
- **data[].status** (`string`):
Current status, such as `draft`, `scheduled`, `sending`, or `sent`.
- **data[].template** (`object`):
Template metadata or full template payload depending on broadcast status.
---
## Create Broadcasts {{ tag: 'POST', label: '/v1/batch/broadcasts' }}
Create new broadcasts to be sent.
### Required Attributes
> Requires a `broadcasts` array containing the broadcast object properties.
- **name** (`string`):
Name of the broadcast such as a campaign name.
- **subject** (`string`):
Subject line of the broadcast email.
- **content** (`string`):
Broadcast body content. Supports Liquid tags.
- **type** (`string`):
The type of email. `plain` for Bento's CSS or `raw` to use your own.
- **from** (`object`):
A `key`/`value` object for the sender. Must be an author in your account.
- **inclusive_tags** (`string`):
A comma separated list of tags to send to.
- **exclusive_tags** (`string`):
A comma separated list of tags you do not want the email to go to.
- **segment_id** (`string`):
The segment ID for the campaign.
- **batch_size_per_hour** (`integer`):
The number of emails to send per hour to ensure the highest delivery.
- **inbox_snippet** (`string`):
Preview text shown after the subject line in supporting inboxes. You can also send this value as
`preview_text`, `preview`, `preheader`, `preheader_text`, or `preview_snippet`.
- **send_at** (`datetime`):
The date and time to send the broadcast at.
> **Recommended**
> Recommended format: `2024-04-23T18:30:00Z`
> ⚠️ **Warning**
> **Required** when `approved` is `true`
- **approved** (`boolean`):
Whether the broadcast has been approved by Bento and will be sent at the scheduled time.
> 🚨 **Important**
> We **strongly** recommend you only add this key after you've done a few test requests and have sent those manually.
### Response
Returns the number of broadcasts created, the created broadcast records, and any item-level failures.
Use `broadcasts[].dashboard_url` to send someone straight to the draft in Bento.
- **results** (`integer`):
Number of broadcasts created.
- **broadcasts** (`array`):
Broadcasts created by the request.
- **broadcasts[].id** (`integer`):
Numeric broadcast ID.
- **broadcasts[].template_id** (`integer`):
Numeric template ID for the broadcast content.
- **broadcasts[].name** (`string`):
Broadcast name.
- **broadcasts[].dashboard_url** (`string`):
Bento dashboard URL for editing the created broadcast.
- **failed** (`integer`):
Number of broadcasts that failed validation or processing.
- **failures** (`array`):
Item-level failure details. Each failure includes the request `index`, broadcast `name`, and `error`.
### Content format examples
Use `type` to decide the format of `content`.
#### `type: raw` example: Product launch announcement
Use a complete email HTML document with inline styles. This gives you full control over layout and rendering.
```html
New Feature Announcement
Bento Product Update
Three new tools to improve campaign performance
Hi {{ visitor.first_name | default: "there" }}, this week we shipped improvements to reporting, segmentation, and API performance.
Here are the highlights and how to use each update in your next send.
Build and preview large audience segments in less time before each campaign.
Improved campaign reporting
Compare opens, clicks, and conversions in one view to find winning messages faster.
Webhook retry logs
Debug failed deliveries with detailed retry events and response payloads.
You are receiving this email because you subscribed to product updates from Bento.
Manage your preferences at https://app.bentonow.com/preferences.
```
#### `type: plain` example: Weekly newsletter
Use simple markup for standard newsletters. Keep it lightweight with paragraphs, lists, and CTA links styled like buttons.
```html
Hi {{ visitor.first_name | default: "there" }},
Thanks for being part of Bento. Here is your weekly update from the product team.
What shipped this week
Faster segment loading
Improved campaign reporting
New webhook retry logs
One quick win to try
Create a segment for users who clicked any email in the last 14 days, then send your next feature
announcement only to that group for higher engagement.