Online
Bento
View markdown

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

MethodEndpointCopy
GET
/fetch/broadcasts

Get Broadcasts

List broadcast history and draft/scheduled broadcast metadata.

POST
/batch/broadcasts

Create Broadcasts

Create a broadcast campaign for a segment or tag audience.

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
    namestring
    Description

    The name of the broadcast campaign.

  • Name
    subjectstring
    Description

    The subject of the email.

  • Name
    contentstring
    Description

    The content of the email.

  • Name
    typestring
    Description

    The type of email. plain for Bento's CSS or raw to use your own.

  • Name
    fromobject
    Description

    A key/value object for the sender. Must be an author in your account.

  • Name
    inclusive_tagsstring
    Description

    A comma separated list of tags to send to.

  • Name
    exclusive_tagsstring
    Description

    A comma separated list of tags you do not want the email to go to.

  • Name
    segment_idstring
    Description

    The segment ID for the campaign.

  • Name
    batch_size_per_hourinteger
    Description

    The number of emails to send per hour to ensure the highest delivery.

GET/v1/fetch/broadcasts

Get 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.
  • Name
    site_uuidstring
    Description

    Your site UUID.

  • Name
    pageinteger
    Description

    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.

  • Name
    statusstring
    Description

    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.

  • Name
    dataarray
    Description

    Broadcast records.

  • Name
    data[].idstring
    Description

    Broadcast identifier.

  • Name
    data[].namestring
    Description

    Broadcast campaign name.

  • Name
    data[].statusstring
    Description

    Current status, such as draft, scheduled, sending, or sent.

  • Name
    data[].templateobject
    Description

    Template metadata or full template payload depending on broadcast status.

POST/v1/batch/broadcasts

Create Broadcasts

Create new broadcasts to be sent.

Required Attributes

Requires a broadcasts array containing the broadcast object properties.
  • Name
    namestring
    Description

    Name of the broadcast such as a campaign name.

  • Name
    subjectstring
    Description

    Subject line of the broadcast email.

  • Name
    contentstring
    Description

    Broadcast body content. Supports Liquid tags.

  • Name
    typestring
    Description

    The type of email. plain for Bento's CSS or raw to use your own.

  • Name
    fromobject
    Description

    A key/value object for the sender. Must be an author in your account.

  • Name
    inclusive_tagsstring
    Description

    A comma separated list of tags to send to.

  • Name
    exclusive_tagsstring
    Description

    A comma separated list of tags you do not want the email to go to.

  • Name
    segment_idstring
    Description

    The segment ID for the campaign.

  • Name
    batch_size_per_hourinteger
    Description

    The number of emails to send per hour to ensure the highest delivery.

  • Name
    inbox_snippetstring
    Description

    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.

  • Name
    send_atdatetime
    Description

    The date and time to send the broadcast at.

    Recommended format: 2024-04-23T18:30:00Z
    Required when approved is true
  • Name
    approvedboolean
    Description

    Whether the broadcast has been approved by Bento and will be sent at the scheduled time.

    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.

  • Name
    resultsinteger
    Description

    Number of broadcasts created.

  • Name
    broadcastsarray
    Description

    Broadcasts created by the request.

  • Name
    broadcasts[].idinteger
    Description

    Numeric broadcast ID.

  • Name
    broadcasts[].template_idinteger
    Description

    Numeric template ID for the broadcast content.

  • Name
    broadcasts[].namestring
    Description

    Broadcast name.

  • Name
    broadcasts[].dashboard_urlstring
    Description

    Bento dashboard URL for editing the created broadcast.

  • Name
    failedinteger
    Description

    Number of broadcasts that failed validation or processing.

  • Name
    failuresarray
    Description

    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.

Code
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>New Feature Announcement</title>
  </head>
  <body style="margin:0;padding:0;background-color:#f3f4f6;">
    <table role="presentation" width="100%" cellspacing="0" cellpadding="0" border="0" style="background-color:#f3f4f6;padding:24px 0;">
      <tr>
        <td align="center">
          <table role="presentation" width="620" cellspacing="0" cellpadding="0" border="0" style="width:620px;max-width:620px;background-color:#ffffff;border:1px solid #e5e7eb;border-radius:10px;">
            <tr>
              <td style="padding:14px 28px;background-color:#111827;border-radius:10px 10px 0 0;font-family:Arial,sans-serif;">
                <p style="margin:0;color:#e5e7eb;font-size:12px;letter-spacing:0.02em;text-transform:uppercase;">Bento Product Update</p>
              </td>
            </tr>
            <tr>
              <td style="padding:30px 28px 16px 28px;font-family:Arial,sans-serif;color:#111827;">
                <h1 style="margin:0 0 12px 0;font-size:26px;line-height:1.25;">Three new tools to improve campaign performance</h1>
                <p style="margin:0 0 16px 0;font-size:16px;line-height:1.55;color:#374151;">
                  Hi {{ visitor.first_name | default: "there" }}, this week we shipped improvements to reporting, segmentation, and API performance.
                </p>
                <p style="margin:0 0 22px 0;font-size:16px;line-height:1.55;color:#374151;">
                  Here are the highlights and how to use each update in your next send.
                </p>
                <a href="https://bentonow.com/changelog" style="display:inline-block;padding:12px 18px;background-color:#111827;color:#ffffff;text-decoration:none;border-radius:6px;font-size:14px;font-weight:600;">Read the full changelog</a>
              </td>
            </tr>
            <tr>
              <td style="padding:0 28px 24px 28px;font-family:Arial,sans-serif;">
                <table role="presentation" width="100%" cellspacing="0" cellpadding="0" border="0" style="border-collapse:separate;border-spacing:0 12px;">
                  <tr>
                    <td style="padding:14px;border:1px solid #e5e7eb;border-radius:8px;">
                      <p style="margin:0 0 6px 0;font-size:14px;font-weight:700;color:#111827;">Faster segment loading</p>
                      <p style="margin:0;font-size:14px;line-height:1.5;color:#4b5563;">Build and preview large audience segments in less time before each campaign.</p>
                    </td>
                  </tr>
                  <tr>
                    <td style="padding:14px;border:1px solid #e5e7eb;border-radius:8px;">
                      <p style="margin:0 0 6px 0;font-size:14px;font-weight:700;color:#111827;">Improved campaign reporting</p>
                      <p style="margin:0;font-size:14px;line-height:1.5;color:#4b5563;">Compare opens, clicks, and conversions in one view to find winning messages faster.</p>
                    </td>
                  </tr>
                  <tr>
                    <td style="padding:14px;border:1px solid #e5e7eb;border-radius:8px;">
                      <p style="margin:0 0 6px 0;font-size:14px;font-weight:700;color:#111827;">Webhook retry logs</p>
                      <p style="margin:0;font-size:14px;line-height:1.5;color:#4b5563;">Debug failed deliveries with detailed retry events and response payloads.</p>
                    </td>
                  </tr>
                </table>
              </td>
            </tr>
            <tr>
              <td style="padding:0 28px 28px 28px;font-family:Arial,sans-serif;color:#6b7280;font-size:12px;line-height:1.6;">
                You are receiving this email because you subscribed to product updates from Bento.
                <br />
                Manage your preferences at https://app.bentonow.com/preferences.
              </td>
            </tr>
          </table>
        </td>
      </tr>
    </table>
  </body>
</html>

type: plain example: Weekly newsletter

Use simple markup for standard newsletters. Keep it lightweight with paragraphs, lists, and CTA links styled like buttons.

Code
<p>Hi {{ visitor.first_name | default: "there" }},</p>

<p>Thanks for being part of Bento. Here is your weekly update from the product team.</p>

<h2>What shipped this week</h2>

<ul>
  <li>Faster segment loading</li>
  <li>Improved campaign reporting</li>
  <li>New webhook retry logs</li>
</ul>



<h3>One quick win to try</h3>
<p>
  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.
</p>

<p>
  <!-- This is a Bento button and compatible with the editor -->
  <button href="https://app.bentonow.com/broadcasts/new" target="_blank" rel="noopener noreferrer" data-bento-button="true" text="Create next broadcast" width="auto" style="background-color: #111827; color: #ffffff!important; border-radius: 8px; padding: 10px 16px; font-size: 14px; text-decoration: none!important; border: none; cursor: pointer!important; font-weight: 600; display: inline-block!important; width: auto!important;" class="shoji-bento-button" data-width="auto"><a href="https://app.bentonow.com/broadcasts/new" target="_blank" rel="noopener noreferrer" style="color: inherit!important; text-decoration: none!important;">Create next broadcast</a></button>
</p>

<p>
  <a href="https://bentonow.com/docs/broadcasts" style="display:inline-block;padding:10px 16px;background:#f3f4f6;color:#111827;text-decoration:none;border-radius:6px;border:1px solid #d1d5db;">
    Read docs
  </a>
</p>

<p>
  Need help planning your next campaign? Reply to this email and we can help with segmentation and send timing.
</p>

<hr />

<p style="font-size:12px;color:#6b7280;">
  You are receiving this email because you opted in for product updates.
  Update preferences in your account at any time.
</p>

For raw, include full HTML and inline CSS. For plain, use lightweight content blocks.