Bento Plugin for OpenCode

Comprehensive integration with Bento email marketing and analytics platform. Manage subscribers, track events, send broadcasts, and analyze engagement using the official Bento Node SDK.

Features

Subscriber Management

• Add, update, and retrieve subscribers
• Upsert subscribers (create or update)
• Batch import subscribers
• Unsubscribe users

Event Tracking

• Track custom events with details
• Track purchases for LTV calculation
• Batch import events
• Custom event properties and fields

Tag & Field Management

• Create and manage tags
• Add/remove tags from subscribers
• Create and manage custom fields
• Update field values

Email Broadcasting

• Get all broadcast campaigns
• Create new broadcast campaigns
• Target by tags and segments
• Throttle sending rates

Transactional Emails

• Send individual or batch transactional emails
• Liquid template support
• Personalization variables
• Override unsubscribe status (for critical emails)

Analytics & Statistics

• Get overall site statistics
• Segment performance metrics
• Broadcast report analytics
• Subscriber growth tracking

Experimental Features

• Email validation
• IP geolocation
• Blacklist checking
• Content moderation
• Gender guessing from names

Commands API (No Automations)

• Update tags without triggering automations
• Update fields without triggering automations
• Useful for data cleanup and migrations

Prerequisites

1. A Bento account at app.bentonow.com
2. Node.js version 18 or later
3. Bento API credentials (see Setup section)

Setup

1. Get Your Bento Credentials

1. Log into your Bento account at app.bentonow.com
2. Navigate to Settings → API Keys
3. Copy the following:
   • Publishable Key (starts with bento_pk_)
   • Secret Key (starts with bento_sk_)
   • Site UUID (your site identifier)

2. Configure Environment Variables

cp .env.example .env

Edit .env and add your credentials:

BENTO_PUBLISHABLE_KEY=bento_pk_your_publishable_key_here
BENTO_SECRET_KEY=bento_sk_your_secret_key_here
BENTO_SITE_UUID=your_site_uuid_here

3. Install Dependencies

npm install
# or
pnpm install

4. Test the Plugin

npm run quickstart
# or
opencode run "get site statistics"

Using from Other Projects

Add to your project's opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "/absolute/path/to/bento/index.ts"
  ]
}

Available Tools

Subscriber Management Tools

add-subscriber

Add a new subscriber to Bento (TRIGGERS automations).

Parameters:

• email (required): Subscriber email address
• firstName (optional): First name
• lastName (optional): Last name
• fields (optional): Additional custom fields as key-value pairs

Example:

opencode run "add subscriber [email protected] with firstName John and lastName Doe"

upsert-subscriber

Create or update a subscriber in Bento.

Parameters:

• email (required): Subscriber email address
• fields (optional): Custom fields to set
• tags (optional): Comma-separated tags to add
• removeTags (optional): Comma-separated tags to remove

Example:

opencode run "upsert subscriber [email protected] with tags premium,vip"

get-subscriber

Get subscriber details by email or UUID.

Parameters:

• email (optional): Subscriber email address
• uuid (optional): Subscriber UUID

Example:

opencode run "get subscriber [email protected]"

update-fields

Update custom fields for a subscriber (TRIGGERS automations).

Parameters:

• email (required): Subscriber email address
• fields (required): Fields to update as key-value pairs

Example:

opencode run "update fields for [email protected] set lastLogin to today"

remove-subscriber

Unsubscribe a subscriber (TRIGGERS automations).

Parameters:

• email (required): Subscriber email address

Example:

opencode run "remove subscriber [email protected]"

batch-import-subscribers

Import multiple subscribers in a single operation.

Parameters:

• subscribers (required): Array of subscriber objects with email, firstName, lastName, and fields

Example:

opencode run "batch import 3 subscribers from this list: [email protected], [email protected], [email protected]"

Event Tracking Tools

track-event

Track a custom event for a subscriber (TRIGGERS automations).

Parameters:

• email (required): Subscriber email address
• type (required): Event type (e.g., $pageView, $login, custom-event)
• details (optional): Event details/properties
• fields (optional): Fields to update on subscriber

Example:

opencode run "track event $pageView for [email protected] with url /products"

track-purchase

Track a purchase event to calculate subscriber LTV (TRIGGERS automations).

Parameters:

• email (required): Subscriber email address
• orderKey (required): Unique order identifier
• amount (required): Purchase amount in cents (e.g., 1000 = $10.00)
• currency (optional, default: USD): Currency code
• cartItems (optional): Array of cart items with productId, productName, quantity, price

Example:

opencode run "track purchase for [email protected] order ORD-123 amount 9999 cents"

Tag Management Tools

tag-subscriber

Add a tag to a subscriber (TRIGGERS automations).

Parameters:

• email (required): Subscriber email address
• tagName (required): Tag name to add

Example:

opencode run "tag subscriber [email protected] with Premium Customer"

get-tags

Get all tags in the Bento account.

Example:

opencode run "get all tags"

create-tag

Create a new tag in Bento.

Parameters:

• name (required): Tag name

Example:

opencode run "create tag VIP Customer"

Field Management Tools

get-fields

Get all custom fields defined in Bento.

Example:

opencode run "get all fields"

create-field

Create a new custom field in Bento.

Parameters:

• key (required): Field key/name

Example:

opencode run "create field loyaltyPoints"

Broadcasting Tools

get-broadcasts

Retrieve all broadcast campaigns.

Example:

opencode run "get all broadcasts"

create-broadcast

Create new broadcast campaign(s).

Parameters:

• broadcasts (required): Array of broadcast objects with:
  • name: Broadcast name
  • subject: Email subject
  • content: HTML content
  • type: Content type (html or plain)
  • fromName: Sender name
  • fromEmail: Sender email
  • inclusiveTags (optional): Comma-separated tags to include
  • exclusiveTags (optional): Comma-separated tags to exclude
  • segmentId (optional): Segment ID to send to
  • batchSizePerHour (optional): Throttle rate per hour

Example:

opencode run "create broadcast Weekly Newsletter subject 'Your Update' from John at [email protected]"

Transactional Email Tools

send-transactional-email

Send transactional email(s) via Bento.

Parameters:

• emails (required): Array of 1-100 email objects with:
  • to: Recipient email
  • from: Sender email (must be existing Author in Bento)
  • subject: Email subject (supports liquid templates)
  • htmlBody: HTML email content (supports liquid templates)
  • transactional: Send to unsubscribed users (default: false)
  • personalizations (optional): Liquid template variables

Example:

opencode run "send transactional email to [email protected] from [email protected] subject 'Welcome' with name John"

Important: The from email must be an existing Author in your Bento account. Add authors at Settings → Authors in the Bento dashboard.

Analytics Tools

get-site-stats

Get overall site statistics including subscribers and engagement.

Example:

opencode run "get site statistics"

get-segment-stats

Get statistics for a specific segment.

Parameters:

• segmentId (required): Segment ID to get stats for

Example:

opencode run "get segment stats for segment_123"

get-report-stats

Get statistics for a specific broadcast report.

Parameters:

• reportId (required): Report ID to get stats for

Example:

opencode run "get report stats for report_456"

Form Tools

get-form-responses

Get responses for a specific form.

Parameters:

• formId (required): Form ID

Example:

opencode run "get form responses for form_789"

Experimental Tools

validate-email

Validate an email address (Experimental).

Parameters:

• email (required): Email to validate
• ip (optional): IP address
• name (optional): Name
• userAgent (optional): User agent string

Example:

opencode run "validate email [email protected]"

geolocate-ip

Get geolocation information for an IP address (Experimental).

Parameters:

• ip (required): IP address to geolocate

Example:

opencode run "geolocate IP 192.168.1.1"

check-blacklist

Check if a domain or IP is blacklisted (Experimental).

Parameters:

• domain (optional): Domain to check
• ipAddress (optional): IP address to check

Example:

opencode run "check blacklist for domain example.com"

moderate-content

Perform content moderation on text (Experimental).

Parameters:

• content (required): Content to moderate

Example:

opencode run "moderate content 'This is a test message'"

guess-gender

Attempt to guess gender from a name (Experimental).

Parameters:

• name (required): Name to analyze

Example:

opencode run "guess gender for name Alex"

Commands API Tools (No Automations)

These tools use the Commands API and do NOT trigger automations. Use these for data cleanup, migrations, or when you want to update data without triggering workflows.

add-tag-no-automation

Add tag to subscriber WITHOUT triggering automations.

Parameters:

• email (required): Subscriber email
• tagName (required): Tag name

Example:

opencode run "add tag Premium to [email protected] without automation"

remove-tag-no-automation

Remove tag from subscriber WITHOUT triggering automations.

Parameters:

• email (required): Subscriber email
• tagName (required): Tag name

Example:

opencode run "remove tag Trial from [email protected] without automation"

add-field-no-automation

Add field to subscriber WITHOUT triggering automations.

Parameters:

• email (required): Subscriber email
• key (required): Field key
• value (required): Field value

Example:

opencode run "add field migrated with value true to [email protected] without automation"

remove-field-no-automation

Remove field from subscriber WITHOUT triggering automations.

Parameters:

• email (required): Subscriber email
• fieldName (required): Field name to remove

Example:

opencode run "remove field tempData from [email protected] without automation"

Important Concepts

Automations vs. Commands

V1 Methods (Triggers Automations):

• add-subscriber, tag-subscriber, update-fields, track-event, etc.
• Use the Batch API
• Takes 1-3 minutes to appear in Bento
• Triggers automations when data changes
• Best for real-time user interactions

Commands API (No Automations):

• add-tag-no-automation, add-field-no-automation, etc.
• Direct API operations
• Instant updates
• Does NOT trigger automations
• Best for data migrations and cleanup

Event Timing

Batch operations (most V1 methods) use Bento's batch import API, which processes events asynchronously. Events typically appear within 1-3 minutes.

Purchase Amounts

All purchase amounts should be in cents. For example:

• $10.00 = 1000 cents
• $99.99 = 9999 cents

Liquid Templates

Transactional emails and broadcast subjects/content support Liquid templates:

Hello {{ name }},

Your order {{ order_id }} is confirmed.

Total: {{ total_amount | money }}

Pass template variables in the personalizations field.

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | BENTO_PUBLISHABLE_KEY | Yes | Bento publishable API key | | BENTO_SECRET_KEY | Yes | Bento secret API key | | BENTO_SITE_UUID | Yes | Bento site UUID |

Error Handling

All tools return JSON responses with the following structure:

Success:

{
  "success": true,
  "data": { ... },
  "message": "Operation completed successfully"
}

Error:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Common Issues

"Missing required Bento credentials"

Make sure all three environment variables are set in your .env file.

"Author not found" (Transactional Emails)

The from email must be added as an Author in your Bento account:

1. Go to Settings → Authors in Bento
2. Add the email address you want to send from
3. Verify the email if required

Events not appearing

Batch operations take 1-3 minutes to process. Check the Bento dashboard after a few minutes.

Rate Limits

Bento may rate limit API requests. The SDK handles most errors gracefully, but very high-volume operations should be throttled on your end.

API Reference

This plugin uses a custom client implementation based on the official Bento Node SDK, providing direct API access without external dependencies.

For detailed API documentation, visit:

• Bento Documentation
• Subscribers API
• API Reference

Support

• Plugin Issues: OpenPets GitHub Issues
• Bento Support: Discord or email [email protected]
• Documentation: docs.bentonow.com

License

MIT