# Broadcasts
Broadcasts are your large-scale communications designed to engage a wide audience, targeting either all your subscribers or specific segments. These include your marketing campaigns and newsletters, aimed at delivering valuable content, updates, promotions, and news.
## Available Endpoints
| Method | Endpoint | Name |
|-------------------------------------------------------------|-----------------------------------------------------------------------|----------------------------------------------------|
| | | [Create Broadcasts](/broadcasts#create-broadcasts) |
| | | [Get Broadcasts](/broadcasts#get-broadcasts) |
## The Broadcast Model
The broadcast model contains a full set of keys that represent the email broadcast, the tags and segments it was addressed to, and the send rate and open rate across recipients.
### 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`):
`key` `value` object of 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 amount 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.
> We currently don't support exporting your broadcast history directly in the app. However, this endpoint can be used to obtain a copy of all your broadcasts. This feature can be useful if you want to utilize this data in your own application, such as training language models on your writing style or creating a digest of previous content.
- **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`.
---
## Create Broadcasts {{ tag: 'POST', label: '/v1/batch/broadcasts' }}
Create new broadcasts to be sent.
### Required Attributes
> Requires `broadcasts` that is an array of 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`):
`key` `value` object of 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 amount of emails to send per hour to ensure the highest delivery.
- **send_at** (`datetime`):
The date and time to send the broadcast at.
Recommended format: `2024-04-23T18:30:00Z`
**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 count of broadcasts queued for processing.
### 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.