Bento Python Guide

To initialize the Bento client, you'll need your Site UUID, Publishable Key, and Secret Key from your Bento account. You can find your keys in your Bento Team. To see your keys click Your Private API Keys Button and if do you do not see a Publishable key and Secret Key, click on Generate Key to create a set.

Client Setup

from bento_api import BentoAPI

bento = BentoAPI(
site_uuid='your_site_uuid',
username='your_publishable_key',
password='your_secret_key'
)

Beginner Guide

Tracking Your First Event

Events represent specific actions users take within your application. Tracking these actions provides valuable insights into user behavior patterns and engagement.

Streamlined Subscriber Management

We recommend using Events as the preferred method to add subscribers, as they simultaneously initiate workflows and automations in a single operation.

Powerful Data Enrichment

Events excel at capturing contextual information alongside user actions. This can be used in emails via liquid tags or in segmentation. For instance, when recording a purchase event, you can include detailed transaction information such as:

Detail	Liquid tag
Product details
Purchase amount
Transaction ID
Payment method

Practical Example

When a customer completes a purchase, you can track this as an event while including all relevant purchase details. This approach enables you to:

Trigger specific post-purchase workflows
Launch targeted follow-up automations
Track lifetime value (LTV) metrics
Create personalized communications based on purchase history

Track a simple page view

batch_create_events()

/v1/batch/events

    events = [
      {
          'type': '$pageView',
          'email': '[email protected]',
          'details': {
              'url': '/home',
              'title': 'Home Page'
          }
      }
    ]

    bento.batch_create_events(events)

Track a form submission

batch_create_events()

/v1/batch/events


      events = [
          {
              'type': '$formSubmitted',
              'email': '[email protected]',
              'details': {
                  'formName': 'Newsletter Signup',
                  'source': 'Homepage'
              }
          }
      ]

      bento.batch_create_events(events)

Managing Subscribers

If you need to manage subscribers directly there are a set of convenience methods available to you. Add, update, and unsubscribe subscribers with these simple methods. Currently, you cannot remove subscribers via the API, but you can remove them from the dashboard People > All Users.

Create a new subscriber

create_subscriber()

/v1/batch/subscribers

    subscriber = bento.create_subscriber(email='[email protected]')
    print(f"New subscriber: {subscriber}")

Adding Individual Subscribers

Please note, while these methods make it easy to manage a subscriber, the Bento recommended way to add a subscriber is via an event. This allows you to kick off sequences and automations, while also recording the "event" at the same time (1 API call).

Adding Multiple Subscribers

Importing or modifying multiple subscribers should be handled via the bulk methods, instead of looping over these calls multiple times.

Common Use Cases

Here are some common scenarios with ready-to-use code:

Tracking a user login "Event"

batch_create_events()

/v1/batch/events

      events = [
        {
          'type': '$login',
          'email': '[email protected]',
          'details': {
            'method': 'password',
            'device': 'mobile'
          }
        }
      ]

      bento.batch_create_events(events)

Intermediate Guide

Custom Fields and Tags

Bento allows you to store custom data about your users through fields and segment them with tags:

Create a new custom field definition

create_field()

/v1/fetch/fields

      field = bento.create_field(key='membershipLevel')
      print(f"New field: {field}")

Using Custom Fields & Tags

While custom fields and tags can be used to segment subscribers, most Bento users find that namespaced tags provide a more effective and easier-to-maintain solution for most segmentation use cases.

Namespaced Tags

Namespaced tags follow this format: namespace:detail For example, if you offer three subscription plans, you could create these tags:

subscription:basic
subscription:pro
subscription:enterprise

We recommend applying these tags either through an automated flow or via bulk updates.

Tags do not need to be namespaced, but for many customers the organization pays off by using namespaced tags when it makes sense.

Fields

Fields are perfect for storing information about your subscribers, such as their language, timezone, or other relevant details. By using fields, you can easily segment subscribers based on their specific needs and preferences, allowing you to tailor your marketing efforts and messaging to each group.

The primary difference between fields and namespaced tags is that fields are not limited to a specific detail and do not need to be predefined. You can store any type of data in a field, including strings, numbers, or even objects. This flexibility makes fields a powerful tool for storing data.

Best Practices

For optimal organization, consider using tags for segmentation while storing more detailed user information in custom fields. Many successful implementations use a strategic combination of both approaches.

Tracking Purchase Events

When recording purchase events, you must include a unique: key as part of the tracking data. This requirement prevents duplicate transactions from being recorded in your analytics.

Most users find it beneficial to use their internal cart or order number as the unique: key. This approach simplifies future lookups and maintains consistency across your systems. The unique: key value you provide is accessible through liquid tags when creating custom email templates, allowing for personalized transactional messaging based on specific purchase details.

Tracking purchases is a great way to monitor customer lifetime value (LTV) and identify recurring customers. Bento reports on the LTV of each subscriber, allowing you to identify high-value customers and tailor your marketing efforts accordingly.

Track a purchase event to monitor customer lifetime value

batch_create_events()

/v1/batch/events

    events = [
        {
            'type': '$purchase',
            'email': '[email protected]',
            'details': {
                'unique': {
                    'key': 'order-123'  # Unique order identifier
                },
                'value': {
                    'amount': 9999,  # Amount in cents
                    'currency': 'USD'
                },
                'cart': {
                    'items': [
                        {
                            'product_id': 'prod-456',
                            'product_name': 'Premium Widget',
                            'product_price': 9999,
                            'quantity': 1,
                            'product_sku': 'SKU-456'
                        }
                    ]
                }
            }
        }
    ]

    bento.batch_create_events(events)

Advanced Guide

Batch Operations

For efficiency, we suggest using batch operations when integrating with Bento. These methods allow for single or bulk operations on subscribers and events, improving the performance and scalability of your integration. They also cover more than 80% of the API use cases for most customers.

Import multiple subscribers at once

batch_create_subscribers()

/v1/batch/subscribers

      subscribers = [
          {
              'email': '[email protected]',
              'first_name': 'Alice',
              'fields': {'company': 'Acme Inc'}
          },
          {
              'email': '[email protected]',
              'first_name': 'Bob',
              'fields': {'company': 'Beta Corp'}
          }
          # ... up to 1,000 subscribers
      ]

      result = bento.batch_create_subscribers(subscribers)
      print(f"Batch create subscribers result: {result}")

Import multiple events at once

batch_create_events()

/v1/batch/events

      events = [
          {
              'type': '$login',
              'email': '[email protected]',
              'fields': {'date': '2023-01-01'}
          },
          {
              'type': '$purchase',
              'email': '[email protected]',
              'details': {
                  'unique': {'key': 'order-123'},
                  'value': {'currency': 'USD', 'amount': 9999}
              }
          }
          # ... up to 1,000 events
      ]

      bento.batch_create_events(events)

Transactional Emails

Bento allows you to send personalized transactional emails for time-sensitive, direct communications. These emails serve specific functional purposes rather than marketing objectives.

Ideal Transactional Email Use Cases

User onboarding (confirmation etc)
Password reset notifications
Sign-in verification links
Order confirmations and details
Account notifications

From Address Requirements

The sender address used in your transactional emails must be configured as an Author email within your Bento settings. Please note that generic addresses such as "~~[email protected]~~" or similar non-personal addresses are not currently supported.

Important Distinction

Transactional emails are designed for essential communications that facilitate specific user actions or provide critical information.

Transactional emails should not be used as substitutes for marketing campaigns or promotional content.

Send a transactional email

batch_create_emails

/v1/batch/emails

      emails = [
          {
              'to': '[email protected]',
              'from': {
                  'name': 'Your Name',
                  'email': '[email protected]'
              },
              'subject': 'Your order #123 has shipped!',
              'html': '<h1>Your order has shipped!</h1><p>We're happy to let you know that your order is on its way.</p>',
              'text': 'Your order has shipped! We're happy to let you know that your order is on its way.'
          }
      ]

      result = bento.batch_create_emails(emails)
      print(f"Email send result: {result}")

Subscriber Updates

Many organizations joining Bento already have an established subscriber base that requires bulk updates over time. These updates commonly include setting field data and managing tags across multiple subscribers. We firmly believe that these methods are the best way to manage a single or multiple subscribers, and we recommend using them for all subscriber updates.

These methods cover more than 80% of the API use cases for most customers.

Choosing the Right Update Method:

The SDK offers multiple approaches for creating subscribers in Bento, each suited to different scenarios.

Preferred Method: Events

The recommended way to create subscribers is via events in response to user activity. This approach activates automations, workflows, and can contain data enrichment.

Create a subscriber when they sign up

batch_create_events()

/v1/batch/events

      events = [
        {
          'type': '$subscribe',
          'email': '[email protected]',
          'fields': {
            'firstName': 'Jane',
            'lastName': 'Doe',
            'signupSource': 'website'
          }
        }
      ]

      bento.batch_create_events(events)

Alternative Methods

For scenarios where you need to create subscribers independently of user actions:

Single Subscriber Creation

Use this method when you need to quickly create a single subscriber with minimal data:

Create a single subscriber (email only)

create_subscriber()

/v1/fetch/subscribers

    subscriber = bento.create_subscriber(email='[email protected]')
    print(f"New subscriber: {subscriber}")

This endpoint is rate-limited and not suitable for loops or bulk creation. Use only for individual subscriber creation.

Multiple Or Enriched Subscriber Creation

For creating multiple subscribers or including additional fields:

Import multiple subscribers

batch_create_subscribers()

/v1/batch/subscribers

    subscribers = [
      {
        'email': '[email protected]',
        'fields': {
          'membershipTier': 'gold',
          'accountStatus': 'active',
          'lastRenewalDate': '2023-01-01T00:00:00'
        }
      },
      {
        'email': '[email protected]',
        'fields': {
          'membershipTier': 'silver',
          'accountStatus': 'pending',
          'trialEndsAt': '2023-02-01T00:00:00'
        }
      }
    ]

    result = bento.batch_create_subscribers(subscribers)
    print(f"Batch create subscribers result: {result}")

Best Practices for Batch Imports:

Though the API supports up to 1,000 subscribers per call, we recommend batches of 200-300 for optimal performance when dealing with extensive data.
Include all relevant custom fields in the initial import to minimize follow-up updates.
For very large imports (10,000+ subscribers), consider implementing a queue system with delay between batches.

Updating Subscribers

Depending on your requirements, several approaches are available for updating subscriber information.

Event-Based Updates (Preferred)

When updates occur in response to user actions, tracking events is the recommended approach:

Update subscriber when they update their profile

batch_create_events()

/v1/batch/events

      events = [
          {
              'type': '$subscription_change',
              'email': '[email protected]',
              'fields': {
                  'subscriptionTier': 'premium'
              }
          }
      ]

      bento.batch_create_events(events)

Becuase you can apply as many changes via automations / workflows as you want this is the most flexible method. It doesn't require code or deployment changes, and can be completely handled in Bento.

Alternative Update Methods

For updates outside of user-triggered actions:

Single Attribute Updates

For quickly updating a specific attribute on a single subscriber:

Add or update a single field

batch_create_subscribers()

/v1/batch/subscribers

    subscribers = [
      {
        'email': '[email protected]',
        'first_name': 'Jesse',
        'last_name': 'Bento',
        'tags': ['membership:premium'],
        'fields': {
          'membershipTier': 'premium',
          'accountStatus': 'pending',
          'trialEndsAt': '2023-02-01T00:00:00'
        }
      }
    ]

    result = bento.batch_create_subscribers(subscribers)
    print(f"Update result: {result}")

The Command API is not recommended for multiple updates or bulk operations. Given its heavy rate limit, use the Batch API instead.

Batch Updates

For updating multiple subscribers or multiple fields at once, use the batch import method:

Update multiple subscribers

batch_create_subscribers()

/v1/batch/subscribers

    subscribers = [
      {
        'email': '[email protected]',
        'fields': {
          'membershipTier': 'gold',
          'accountStatus': 'active',
          'lastRenewalDate': '2023-01-01T00:00:00'
        }
      },
      {
        'email': '[email protected]',
        'fields': {
          'membershipTier': 'silver',
          'accountStatus': 'pending',
          'trialEndsAt': '2023-02-01T00:00:00'
        }
      }
    ]

    result = bento.batch_create_subscribers(subscribers)
    print(f"Batch update result: {result}")

Recommendations:

Even for single-subscriber updates, consider using the batch import method when multiple fields need updating.
The batch import performs an "upsert" operation – it creates subscribers that don't exist and updates those that do.
This approach provides the most flexibility as your use cases evolve, whether you need to add more changes or modify multiple users simultaneously.

Specialized Update Operations

For specific update scenarios, the SDK offers dedicated methods:

Change a subscribers email address

execute_commands()

/v1/fetch/commands

      commands = [
        {
          'command': 'change_email',
          'email': '[email protected]',
          'query': '[email protected]'
        }
      ]

      result = bento.execute_commands(commands)
      print(f"Change email result: {result}")

Utility Features

These features provide additional convenience utility for Bento users, to handle some of the common secondary use cases we commonly see, such as validation and blacklist checks.

Email validation

validate_email()

/v1/experimental/validation

      validation_result = bento.validate_email(
        email='[email protected]',
        name=None,
        user_agent='Mozilla/5.0...',
        ip='192.168.1.1'
      )

      print(f"Email validation result: {validation_result}")

API Reference

Core API

BentoAPI Class - Main entry point for using the SDK (from bento_api import BentoAPI)
Configuration - Set up through direct initialization with credentials (BentoAPI(site_uuid, username, password))
Request Methods - Direct method calls for all API operations (e.g., batch_create_events(), create_subscriber())
Exception Handling - Built-in exception class BentoAPIError for error management
HTTP Integration - Uses the Requests library for all API communications

Convenience Methods

Core API

Use Case	Python SDK Method
Add a new subscriber
Unsubscribe a subscriber
Update a data for an existing subscriber
Add a tag to a subscriber
Update subscriber fields
Track a custom event
Track a purchase event

Modules

Batch

Use Case	Method	API Reference
Import multiple subscribers		Import Subscribers >>
Import multiple events		Import Events >>
Send emails		Send Emails >>

Commands

Use Case	Method	API Reference
Add a tag		Subscriber Upsert >>
Remove a tag		Subscriber Upsert >>
Add a field		Subscriber Upsert >>
Remove a field		Subscriber Upsert >>
Subscribe a user		Subscriber Command >>
Unsubscribe a user		Subscriber Command >>
Change email address		Subscriber Command >>

Experimental

Use Case	Method	API Reference
Validate email address		Validate Email >>
Predict gender from name		Gender Guess >>
Get IP geolocation		IP Geolocation >>
Check domain/IP blacklist		Blacklist Check >>

Fields

Use Case	Method	API Reference
Get all fields		Get Fields >>
Create a field		Create Fields >>

Subscribers

Use Case	Method	API Reference
Find subscriber		Find Subscriber >>
Create a subscriber		Create Subscriber >>
Run commands		Subscriber Commands >>

Use Case	Method	API Reference
Get all tags		List Tags >>
Create a tag		Create Tag >>

Common Errors


Not Authorized	Check your API keys and ensure they have appropriate permissions
Rate Limited	Implement backoff/retry logic for batch operations
Network Errors	Check internet connectivity and API endpoint availability
Exceptions	Double check you are using a valid `Author` & the payload format.

Debugging Tips


1.	Enable `logErrors: true` in your configuration for detailed error logging
2.	Use try/catch blocks around API calls to handle errors gracefully
3.	For batch operations, start with smaller batches to isolate issues

FAQ

Bento Python Guide

Reference

Using Pip

Client Setup

Streamlined Subscriber Management

Powerful Data Enrichment

Practical Example

Track a simple page view

Track a form submission

Create a new subscriber

Adding Individual Subscribers

Adding Multiple Subscribers

Tracking a user login "Event"

Create a new custom field definition

Namespaced Tags

Fields

Best Practices

Track a purchase event to monitor customer lifetime value

Import multiple subscribers at once

Import multiple events at once

Ideal Transactional Email Use Cases

From Address Requirements

Important Distinction

Send a transactional email

Choosing the Right Update Method:

Preferred Method: Events

Create a subscriber when they sign up

Alternative Methods

Create a single subscriber (email only)

Import multiple subscribers

Updating Subscribers

Event-Based Updates (Preferred)

Update subscriber when they update their profile

Alternative Update Methods

Add or update a single field

Update multiple subscribers

Specialized Update Operations

Change a subscribers email address

Email validation

Core API

Convenience Methods

Core API

Modules

Batch

Commands

Experimental

Fields

Subscribers

Tags

Common Errors

Debugging Tips

Can I use this SDK in a frontend environment?

How do I handle rate limiting?

What's the maximum batch size for importing subscribers or events?

How do I track anonymous users?

Which Python versions are supported?

How can I contribute to the SDK?

Can I use the SDK with AWS Lambda or other serverless environments?

How does the Python SDK integrate with common web frameworks?