Broadcasts

Launch large-scale campaigns, fetch historical sends, and manage approval-ready payloads by API.

Broadcasts power newsletters, marketing campaigns, and any one-to-many announcement. Use these endpoints to inspect scheduled work, pull historical stats into your BI stack, or queue new batches directly from your own tooling.

Method Endpoint Description
POST /v1/batch/broadcasts Create Broadcasts
GET /v1/fetch/broadcasts Get Broadcasts

The broadcast model

Each broadcast record includes metadata about targeting, pacing, and performance so you can audit a send long after it leaves Bento.

name · string

Internal campaign name so you can search later.

subject · string

Email subject line delivered to subscribers.

content · string

HTML or Liquid-enabled body sent to recipients.

type · string

`plain` (Bento styled) or `raw` to provide your own markup.

from · object

`{ email, name }` pair that must match an approved author.

inclusive_tags · string

Comma-separated tags that should receive the broadcast.

exclusive_tags · string

Comma-separated tags to suppress from the send.

segment_id · string

Target a saved segment when you need more complex logic.

batch_size_per_hour · integer

Throttle rate so deliverability stays healthy.

GET /v1/fetch/broadcasts

Get Broadcasts

Returns the broadcasts that belong to your site. Use it to build custom dashboards, export a writing archive, or keep an eye on pacing from outside the UI.

Query parameters

site_uuid · string
UUID of the Bento site whose broadcasts you want to inspect.
page · integer
Optional page cursor for pagination when you have a long history.

                    ?page=2&site_uuid=ExampleID1234

cURL

bash
curl -L -u publishableKey:secretKey \
  -X GET "https://app.bentonow.com/api/v1/fetch/broadcasts?site_uuid=ExampleID1234" \
  -H "Accept: application/json"

JavaScript

javascript
const axios = require('axios');

let config = {
  method: 'get',
  url: 'https://app.bentonow.com/api/v1/fetch/broadcasts',
  params: { site_uuid: 'ExampleID1234' },
  auth: {
    username: 'publishableKey',
    password: 'secretKey'
  },
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
};

axios(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

Laravel SDK

php
use Bentonow\BentoLaravel\Facades\Bento;

return Bento::getBroadcasts()->json();

Python SDK

python
from bento_api import BentoAPI
import os

api = BentoAPI(
  site_uuid=os.getenv('BENTO_SITE_UUID'),
  username=os.getenv('BENTO_PUBLISHABLE_KEY'),
  password=os.getenv('BENTO_SECRET_KEY')
)
broadcasts = api.get_broadcasts()

.NET SDK

csharp
public class BroadcastExample
{
  private readonly IBentoBroadcastService _broadcastService;

  public BroadcastExample(IBentoBroadcastService broadcastService)
  {
    _broadcastService = broadcastService;
  }

  public async Task BroadcastExamples()
  {
    var getBroadcastsResponse = await _broadcastService.GetBroadcastsAsync<dynamic>();
  }
}

Go SDK

go
broadcasts, err := client.GetBroadcasts(ctx)
if err != nil {
  log.Fatal(err)
}
for _, broadcast := range broadcasts {
  fmt.Printf("Broadcast: %s (Type: %s)\n", broadcast.Name, broadcast.Type)
}

Rust SDK

rust
let broadcasts = client.get_broadcasts().await?;

Elixir SDK

elixir
{:ok, broadcasts} = BentoSdk.Broadcasts.get()

Response shape

Each entry exposes IDs, timing metadata, and template details so you can reconcile with your internal analytics.

Response body

json
{
  "data": [
    {
      "id": "string",
      "type": "string",
      "attributes": {
        "name": "string",
        "share_url": "string",
        "template": {
          "subject": "string",
          "to": "string",
          "html": "string"
        },
        "created_at": "2024-08-06T05:44:04.433Z",
        "sent_final_batch_at": "2024-08-06T05:44:04.433Z",
        "send_at": "2024-08-06T05:44:04.433Z",
        "stats": {
          "open_rate": 0
        }
      }
    }
  ]
}
POST /v1/batch/broadcasts

Create Broadcasts

Queue one or many broadcasts in a single call. Bento validates the payload, respects your batching limits, and schedules the jobs for approval.

Required attributes

name · string
Campaign/broadcast name.
subject · string
Subject line delivered to the inbox.
content · string
Body markup. Liquid tags are fully supported.
type · string
`plain` (Bento template) or `raw` (bring your own HTML).
from · object
Approved author `{ email, name }`.
inclusive_tags · string
Comma-separated tags to include.
exclusive_tags · string
Comma-separated tags to suppress.
segment_id · string
Send to the visitors captured by a saved segment.
batch_size_per_hour · integer
Hourly rate limit to smooth delivery.
send_at · datetime
UTC timestamp that schedules the send (required when `approved` is true).
approved · boolean
Only set this to `true` once you are ready for Bento to release the campaign at `send_at`.

cURL

bash
curl -L -u publishableKey:secretKey \
  -X POST "https://app.bentonow.com/api/v1/batch/broadcasts?site_uuid=ExampleID1234" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-raw '{
    "broadcasts": [
      {
        "name": "Campaign #1 — Plain Text Example",
        "subject": "Hello Plain World",
        "content": "<p>Hi {{ visitor.first_name }}</p>",
        "type": "plain",
        "from": {
          "email": "example@example.com",
          "name": "John Doe"
        },
        "inclusive_tags": "lead,mql",
        "exclusive_tags": "customers",
        "segment_id": "segment_123456789",
        "batch_size_per_hour": 1500
      }
    ]
  }'

JavaScript

javascript
const axios = require('axios');

let data = {
  "broadcasts": [
    {
      "name": "Campaign #1 — Plain Text Example",
      "subject": "Hello Plain World",
      "content": "<p>Hi {{ visitor.first_name }}</p>",
      "type": "plain",
      "from": {
        "email": "example@example.com",
        "name": "John Doe"
      },
      "inclusive_tags": "lead,mql",
      "exclusive_tags": "customers",
      "segment_id": "segment_123456789",
      "batch_size_per_hour": 1500
    }
  ]
};

let config = {
  method: 'post',
  url: 'https://app.bentonow.com/api/v1/batch/broadcasts',
  params: { site_uuid: 'ExampleID1234' },
  auth: {
    username: 'publishableKey',
    password: 'secretKey'
  },
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  data: JSON.stringify(data)
};

axios(config)
  .then((response) => console.log(JSON.stringify(response.data, null, 2)))
  .catch((error) => console.error(error));

Laravel SDK

php
use Bentonow\BentoLaravel\Facades\Bento;
use Bentonow\BentoLaravel\DataTransferObjects\CreateBroadcastData;
use Bentonow\BentoLaravel\DataTransferObjects\ContactData;
use Bentonow\BentoLaravel\Enums\BroadcastType;

$data = Collect([
  new CreateBroadcastData(
    name: "Campaign #1 Example",
    subject: "Hello world Plain Text",
    content: "<p>Hi {{ visitor.first_name }}</p>",
    type: BroadcastType::PLAIN,
    from: new ContactData(
      name: "John Doe",
      emailAddress: "example@example.com"
    ),
    inclusive_tags: "lead,mql",
    exclusive_tags: "customers",
    segment_id: "segment_123456789",
    batch_size_per_hour: 1500
  ),
]);

return Bento::createBroadcast($data)->json();

Python SDK

python
from bento_api import BentoAPI
import os

api = BentoAPI(
  site_uuid=os.getenv('BENTO_SITE_UUID'),
  username=os.getenv('BENTO_PUBLISHABLE_KEY'),
  password=os.getenv('BENTO_SECRET_KEY')
)
broadcasts = [
  {
    "name": "Newsletter 1",
    "subject": "Check out our latest news!",
    "content": "<h1>Newsletter 1 Content</h1>",
    "type": "plain",
    "from": {
      "email": "example@example.com",
      "name": "John Doe"
    },
    "inclusive_tags": "lead,mql",
    "exclusive_tags": "customers",
    "segment_id": "segment_123456789",
    "batch_size_per_hour": 1500
  }
]
result = api.batch_create_broadcasts(broadcasts)

.NET SDK

csharp
public class BroadcastExample
{
  private readonly IBentoBroadcastService _broadcastService;

  public BroadcastExample(IBentoBroadcastService broadcastService)
  {
    _broadcastService = broadcastService;
  }

  public async Task BroadcastExamples()
  {
    var broadcastRequest = new BroadcastRequest(
      Name: "Monthly Newsletter",
      Subject: "Your Monthly Update",
      Content: "<p>Hello {{ visitor.first_name }}</p>",
      Type: "plain",
      From: new ContactInfo(
        EmailAddress: "newsletter@example.com",
        Name: "Company Newsletter"
      ),
      InclusiveTags: "newsletter,active",
      BatchSizePerHour: 1000
    );

    await _broadcastService.CreateBroadcastAsync<dynamic>(broadcastRequest);
  }
}

Go SDK

go
broadcasts := []bento.BroadcastData{
  {
    Name:    "Campaign #1 Example",
    Subject: "Hello world Plain Text",
    Content: "<p>Hi {{ visitor.first_name }}</p>",
    Type:    bento.BroadcastTypePlain,
    From: bento.ContactData{
      Name:  "John Doe",
      Email: "sender@yourdomain.com",
    },
    InclusiveTags:    "lead,mql",
    ExclusiveTags:    "customers",
    SegmentID:        "segment_123456789",
    BatchSizePerHour: 1500,
  },
}

if err := client.CreateBroadcast(ctx, broadcasts); err != nil {
  log.Fatal(err)
}

Rust SDK

rust
use bento::{BroadcastData, BroadcastType, ContactData};

let broadcast = BroadcastData {
  name: "Test Campaign".to_string(),
  subject: "Welcome Email".to_string(),
  content: "<p>Hello subscribers!</p>".to_string(),
  broadcast_type: BroadcastType::Plain,
  from: ContactData {
    name: Some("John Doe".to_string()),
    email: "sender@yourdomain.com".to_string(),
  },
  inclusive_tags: Some("lead,mql".to_string()),
  exclusive_tags: None,
  segment_id: None,
  batch_size_per_hour: 300,
};

client.create_broadcasts(vec![broadcast]).await?;

Elixir SDK

elixir
broadcasts = [
  %{
    name: "Campaign #1 Example",
    subject: "Hello Plain World",
    content: "<p>Hi {{ visitor.first_name }}</p>",
    type: :plain,
    from: %{
      email: "example@example.com",
      name: "John Doe"
    },
    inclusive_tags: "lead,mql",
    exclusive_tags: "customers",
    segment_id: "segment_123456789",
    batch_size_per_hour: 1500
  }
]

BentoSdk.Broadcasts.create(broadcasts)

Response

Bento returns the number of broadcasts that were queued so you can confirm nothing was dropped before approval.

Response body

json
{
  "results": 1000
}

Need the original Markdown? Open raw file