Bento
View markdown

Emails

Use this API to send one-off messages such as welcome emails, password resets, and order confirmations. Requests are accepted immediately and queued into a priority delivery queue. Most requests are processed within 30 seconds.

This endpoint is throttled to send at a rate of 60 emails per minute regardless of how many emails you queue. For most use cases, this is more than enough and protects you from attacks/abuse but if you'd like to increase this limit, please reach out to support.
Avoid emojis and URL shorteners in transactional emails. Our systems may flag them as spam and throttle delivery to 1 email per hour. We also recommend not personalizing emails with user-set values (first_name, last_name, etc). Users can inject their own content into your emails through these fields.

Available Endpoints

MethodEndpointCopy
POST
/batch/emails

Create Emails

Queue transactional emails for priority delivery.

The Email Model

The email model resembles a standard email but includes additional flags and custom data fields for merging into the provided HTML.

Properties

  • Name
    tostring
    Description

    The email address of the recipient.

  • Name
    fromstring
    Description

    The email address of the sender. Must be an author in your account.

  • Name
    subjectstring
    Description

    The subject of the email.

  • Name
    html_bodystring
    Description

    HTML body. Supports Liquid (visitor fields, conditionals, filters). For marketing sends or when transactional is false, include a visible unsubscribe link with {{ visitor.unsubscribe_url }}. Bento also adds List-Unsubscribe and one-click (RFC 8058) headers automatically. See Unsubscribes.

  • Name
    transactionalboolean
    Description

    Defaults to false, which honors unsubscribe and is the safe option. Set true to send even if the recipient has unsubscribed. USE WITH CAUTION. Do not use this to bypass marketing consent.

  • Name
    personalizationsobject
    Description

    Key/value merge data injected into the email as Liquid variables (for example {{ order_id }}). Works alongside visitor.* Liquid in html_body. See the Liquid guide.

POST/v1/batch/emails

Create Emails

Requests are instant and queued into a priority queue. Most requests will be processed within 30 seconds.

This endpoint takes an array emails that can contain 1 to 60 emails made up of the following keys.
Bento does not support file attachments in emails. Please use links to attachments instead for maximum deliverability.

Required Attributes

  • Name
    tostring
    Description

    The email address of the recipient.

  • Name
    fromstring
    Description

    The email address of the sender. Must be an author in your account.

  • Name
    subjectstring
    Description

    The subject of the email.

  • Name
    html_bodystring
    Description

    HTML body. Supports Liquid (visitor fields, conditionals, filters). For marketing sends or when transactional is false, include a visible unsubscribe link with {{ visitor.unsubscribe_url }}. Bento also adds List-Unsubscribe and one-click (RFC 8058) headers automatically. See Unsubscribes.

  • Name
    transactionalboolean
    Description

    Defaults to false, which honors unsubscribe and is the safe option. Set true to send even if the recipient has unsubscribed. USE WITH CAUTION. Do not use this to bypass marketing consent.

Optional Attributes

  • Name
    personalizationsobject
    Description

    Key/value merge data injected into the email as Liquid variables (for example {{ order_id }}). Works alongside visitor.* Liquid in html_body. See the Liquid guide.



Response

Returns the count of emails accepted into the queue.

  • Name
    resultsinteger
    Description

    Number of emails accepted into the queue. This is not a per-recipient sent or dropped report. Suppression (unsubscribed when transactional is false, hard bounce, or complaint) can drop recipients after acceptance without appearing in this response.

Sending Behavior

  • Bento adds List-Unsubscribe and one-click (RFC 8058) headers automatically. For non-transactional sends, you still need a visible unsubscribe link in the body. Use {{ visitor.unsubscribe_url }} in html_body. See Unsubscribes and the Liquid guide.
  • Open pixels, click rewriting, and UTMs apply by default, same as other Bento emails. Disable per send with Liquid in html_body: {{ "true" | disable_click }}, {{ "true" | disable_utms }}, {{ "true" | disable_open }}. See Open and Click Tracking.
  • The API response is a queue acceptance count, not per-recipient delivery or suppression status. When transactional is false, unsubscribed or suppressed recipients may be dropped silently after acceptance. Hard bounces and complaints stay suppressed.
  • Use the Delivery API for delivery reports and per-recipient delivery events. Per-subscriber open and click timelines live in the person profile UI, not this endpoint.
  • This endpoint cannot bulk list or export unsubscribed addresses. The Subscribers API looks up one email at a time. Bulk search and list are restricted. For exports, use the dashboard or contact support.
  • Batch API mail sends through Bento-managed pools. New accounts start on restricted pools. Good senders move to appropriate pools over time. Established senders may get separate pools for transactional and broadcast mail. See IP pools.