import {
  Col,
  Properties,
  Property,
  Row,
  WarningNote,
  Note,
  GhostNote,
} from '@/components/docs/mdx'


export const vendorImg = '/docs/images/logos/n8n.svg'
export const bentoLogoImg = '/docs/images/logos/bento-text-logo.svg'
export const headerBackground = '/docs/images/headers/header_background.webp'


import {
  Accordion,
  AccordionItem,
  AccordionTrigger,
  AccordionContent,
} from '@/components/docs/ui/accordion'


# Bento N8N Integration

Connect Bento's powerful email marketing and automation platform directly into your N8N workflows. Send transactional emails, track events, manage subscribers, and execute advanced subscriber commands. 

<IntegrationHeader
  vendorIcon={vendorImg}
  bentoLogo={bentoLogoImg}
  headerBackground={headerBackground}
/>

## Overview

The Bento n8n Community Node makes it quick and easy to integrate Bento's email marketing and automation platform directly into your n8n workflows. This integration provides:

- **Subscriber Management**: Create, update, and retrieve subscriber information with custom fields and tags
- **Event Tracking**: Track custom events and user behavior for advanced segmentation and automation
- **Transactional Emails**: Send personalized transactional emails with HTML/text content and template variables
- **Subscriber Commands**: Execute powerful commands like adding/removing tags, managing fields, and subscription status
- **Email Validation**: Validate email addresses for spam/throwaway detection using Bento's validation service

## Prerequisites

Before getting started, you'll need:

- n8n version 0.198.0 or higher
- Node.js 20.15 or higher
- An active Bento account with API credentials
- Your Bento **`Publishable Key`**, **`Secret Key`**, and **`Site UUID`**

## Installation


  
  
    
      
        1. Open your n8n instance
        2. Go to **Settings** → **Community Nodes**
        3. Click **Install a community node**
        4. Enter the package name: `n8n-nodes-bento`
        5. Click **Install**
      
      
      
        If you're running n8n locally or in a self-hosted environment:
        
        ```bash
        # Navigate to your n8n installation directory
        cd ~/.n8n
        
        # Install the Bento community node
        npm install n8n-nodes-bento
        
        # Restart n8n
        n8n start
        ```
      
      
      
Here is an example `docker-compose.yml` file for you to use:
        
        ```yaml
        version: '3.8'
        services:
          n8n:
            image: n8nio/n8n:latest
            container_name: n8n
            restart: unless-stopped
            ports:
              - "5678:5678"
            volumes:
              - ./n8n:/home/node/.n8n
            environment:
              - N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom/nodes
              - N8N_EDITOR_BASE_URL=http://localhost:5678
              - GENERIC_TIMEZONE=Asia/Tokyo
            entrypoint: ["/bin/sh", "-c"]
            command: |
              "set -e
               cd /home/node/.n8n
               mkdir -p custom/nodes
               npm install bento-n8n-sdk
               ln -sfn /home/node/.n8n/node_modules/bento-n8n-sdk /home/node/.n8n/custom/nodes/bento-n8n-sdk
               exec n8n start"
        ```
      
    
  

{' '}


  1. Log into your [Bento dashboard ](https://app.bentonow.com)
  2. Navigate to **API Keys**
  3. Copy your
  **Publishable Key**, **Secret Key**, and **Site UUID**
  
> Keep your API credentials secure and never share your secret key or include
>     it in version control.


  
  
    1. In your n8n workflow, add a Bento node
    2. Click on the **Credential for Bento API** dropdown
    3. Select **Create New Credential**
    4. Fill in your credentials:
       - **Publishable Key**: Your Bento publishable key (used for client-side operations)
       - **Secret Key**: Your Bento secret key (used for server-side operations)
       - **Site UUID**: Your Bento site UUID (identifies your specific Bento site)
    5. Click **Save** and **Test** to verify the connection
    
    
> ⚠️ **Warning**
> Your Secret Key is sensitive information. n8n automatically encrypts and securely stores your credentials.

  


---

## Available Operations

### Create Subscriber

Add a new subscriber to your Bento audience with email and profile data.

**Required Parameters:**


  - **Email** (`string`): 
    The subscriber's email address
  


**Optional Parameters:**


  - **First Name** (`string`): 
    Subscriber's first name for personalization
  
  - **Last Name** (`string`): 
    Subscriber's last name for personalization
  
  - **Custom Fields** (`object`): 
    Additional key-value pairs to store with the subscriber
  


**Example Use Cases:**

- Add new users from form submissions
- Import subscribers from external databases
- Create subscribers from webhook data

---

### Get Subscriber

Retrieve detailed information about an existing subscriber by email.

**Required Parameters:**


  - **Email** (`string`): 
    The subscriber's email address
  


**Returns:**
Complete subscriber profile including custom fields, tags, and subscription status

**Example Use Cases:**

- Look up subscriber information before sending personalized content
- Verify subscriber existence in conditional workflows
- Retrieve custom field data for personalization

---

### Update Subscriber

Modify subscriber profile information and custom attributes.

**Required Parameters:**


  - **Email** (`string`): 
    The subscriber's email address
  


**Optional Parameters:**


  - **First Name** (`string`): 
    Updated first name
  
  - **Last Name** (`string`): 
    Updated last name
  
  - **Custom Fields** (`object`): 
    Updated or new custom field values
  


**Example Use Cases:**

- Update subscriber information from CRM changes
- Add new custom fields based on user behavior
- Sync subscriber data across platforms

---

### Track Event

Record custom events and behaviors for subscriber segmentation and automation.

**Required Parameters:**


  - **User ID** (`string`): 
    Unique identifier for the user (typically email address)
  
  - **Event Name** (`string`): 
    Name of the custom event (e.g., "purchase_completed", "page_viewed")
  


**Optional Parameters:**


  - **Event Properties** (`object`): 
    Additional key-value pairs with event data
  


**Example Use Cases:**

- Track purchase events with order details
- Record page views and user interactions
- Monitor feature usage and engagement
- Trigger automation based on user behavior

**Example Event Properties:**

```
{
  "purchase_amount": 99.99,
  "product_id": "SKU123",
  "category": "electronics"
}
```

---

### Send Transactional Email

Send personalized transactional emails using HTML or text content.

**Required Parameters:**


  - **Recipient Email** (`string`): 
    Email address of the recipient
  
  - **From Email** (`string`): 
    Sender email address (must be an existing author in your Bento account)
  
  - **Subject** (`string`): 
    Email subject line
  
  - **Email Type** (`select`): 
    Choose between HTML or Text format
  


**Content Parameters:**


  - **HTML Body** (`string`): 
    HTML content (when Email Type is HTML)
  
  - **Text Body** (`string`): 
    Plain text content (when Email Type is Text)
  


**Optional Parameters:**


  - **Transactional** (`boolean`): 
    Mark as transactional email - this ignores if the user has unsubscribed. USE
    WITH CAUTION!
  
  - **Personalizations** (`object`): 
    Template variables for dynamic content using liquid tags
  


**Example Use Cases:**

- Send password reset emails
- Deliver order confirmations
- Send welcome emails to new users
- Notify users of account changes

**Example Personalization:**

```
{
  "name": "John Doe",
  "order_number": "12345",
  "total": "$99.99"
}
```

---

### Subscriber Command

Execute commands on subscribers to manage tags, fields, and subscription status.

**Required Parameters:**


  - **Email** (`string`): 
    The subscriber's email address
  
  - **Command** (`select`): 
    The action to perform
  


**Available Commands:**

- **Add Tag**: Add a tag to the subscriber
- **Remove Tag**: Remove a tag from the subscriber
- **Add Tag via Event**: Add a tag through event tracking
- **Add Field**: Add or update a custom field
- **Remove Field**: Remove a custom field
- **Subscribe**: Subscribe the email address
- **Unsubscribe**: Unsubscribe the email address
- **Change Email**: Update the subscriber's email address

**Example Use Cases:**

- Segment subscribers with tags based on behavior
- Manage subscription preferences
- Update subscriber data programmatically
- Handle unsubscribe requests

---

### Validate Email

Validate email addresses for spam/throwaway detection using Bento's validation service.

**Required Parameters:**


  - **Email** (`string`): 
    The email address to validate
  


**Optional Parameters:**


  - **Name** (`string`): 
    Associated name (improves validation accuracy)
  
  - **IP Address** (`string`): 
    Associated IP address (improves validation accuracy)
  


**Returns:**
Validation results including deliverability score and risk assessment

**Example Use Cases:**

- Filter out invalid emails before adding subscribers
- Prevent spam signups
- Improve email deliverability rates
- Validate email quality in real-time

## Best Practices


  
    ### Security Best Practices
    
    - Always use n8n's credential system - never hardcode API keys
    - Validate all input data before processing
    - Use HTTPS for all communications
    - Implement rate limiting for high-volume workflows
    - Keep your Secret Key secure and never expose it in client-side code
  

{' '}

  ### Workflow Best Practices
  - Use n8n's "Continue on Fail" option for robust workflows
  - Implement error handling for all Bento operations
  - For large datasets, consider using multiple smaller batches
  - Always test your workflows in a development environment first
  - Use meaningful names for your workflows and nodes


{' '}

  ### Event Tracking Best Practices
  - Use descriptive event names (e.g., "purchase_completed", "page_viewed")
  - Include relevant event properties for segmentation
  - Track user journey milestones consistently
  - Use consistent naming conventions across your organization
  - Avoid tracking sensitive information in event properties


  
    ### Email Best Practices
    
    - Use personalizations for dynamic content
    - Include both HTML and text versions when possible
    - Test email templates thoroughly before production use
    - Ensure sender email addresses are verified in Bento
    - Be cautious with transactional email settings
  


## Common Workflow Examples

### User Registration Flow

1. **Trigger**: New user signs up via webhook
2. **Create Subscriber**: Add user to Bento with profile data
3. **Track Event**: Send "signup" event with registration details
4. **Send Email**: Welcome email with onboarding instructions

### E-commerce Purchase Tracking

1. **Trigger**: Purchase completed webhook from e-commerce platform
2. **Track Event**: Send "purchase_completed" event with order details
3. **Update Subscriber**: Add "customer" tag and update LTV
4. **Send Email**: Order confirmation with tracking information

### Lead Scoring Workflow

1. **Trigger**: User performs action (downloads content, visits pricing page)
2. **Track Event**: Record engagement event
3. **Get Subscriber**: Retrieve current subscriber data
4. **Subscriber Command**: Add appropriate tags based on behavior
5. **Conditional Logic**: Trigger different flows based on lead score

## Troubleshooting


  
    ### Common Authentication Problems
    
    **Error: "Authentication Failed"**
    - Verify your API credentials are correct and active
    - Check that your Site UUID format is correct
    - Ensure you're using the right environment (test vs production)
    
    **Error: "Invalid API Key"**
    - Confirm your Secret Key hasn't been regenerated
    - Check that your Publishable Key matches your account
  

{' '}

  ### Common Operation Problems
  **Error: "Invalid Email Format"**
  - Ensure email addresses follow RFC standards
  - Check for extra spaces or special characters

  **Error: "Rate Limited"**
  - Reduce request frequency in your workflows
  - Implement delays between operations for high-volume processing

  **Error: "HTML Validation Failed"**
  - Check for dangerous HTML elements in email content
  - Ensure HTML is properly formatted


  
    ### Common Data Problems
    
    **Error: "Field Limits Exceeded"**
    - Custom field keys are limited to 50 characters
    - Custom field values are limited to 500 characters
    
    **Error: "Payload Too Large"**
    - Maximum request payload size is 1MB
    - Break large operations into smaller batches
  


## Technical Limitations

### API Limits

- **Payload Size**: Maximum request payload size is 1MB
- **Concurrent Requests**: Limited to 5 concurrent requests per node instance
- **Field Limits**: Custom field keys limited to 50 characters, values to 500 characters
- **Rate Limiting**: Built-in rate limiting prevents API quota exhaustion

### Security Features

- **Input Validation**: All inputs are validated for length, format, and security
- **HTML Sanitization**: HTML content is automatically sanitized to prevent XSS attacks
- **Email Validation**: Email addresses are validated using RFC-compliant regex patterns
- **Secure Error Handling**: Error messages don't expose sensitive information

### Reliability Features

- **Automatic Retries**: Failed requests are automatically retried with exponential backoff
- **Timeout Handling**: Configurable timeouts prevent hanging requests
- **Concurrent Request Management**: Intelligent management of concurrent API requests

## FAQ


  
    
### Can I use this with n8n Cloud?

    
      Yes! The Bento n8n Community Node works with both n8n Cloud and
      self-hosted installations. For n8n Cloud, simply install it through the
      Community Nodes section in your settings.
    
  

  
    
### 
      What happens if an email address is invalid?
    

    
      The node includes built-in email validation. Invalid email addresses will
      return an error, which you can handle using n8n's error handling features.
      Consider using the "Validate Email" operation first for uncertain email
      addresses.
    
  

  
    
### 
      Can I send emails to unsubscribed users?
    

    
      Yes, but only for truly transactional emails (like password resets or
      order confirmations) by setting the "Transactional" parameter to true. Use
      this feature with extreme caution as it can impact your sending reputation
      if misused.
    
  

  
    
### How do I get support?

    
      Contact Bento support via: - Email: support@bentonow.com - Discord: [Bento
      Community](https://discord.gg/ssXXFRmt5F) For n8n-specific issues, also
      check the [n8n Community Forum](https://community.n8n.io/).
    
  


## Additional Resources

- [Bento API Documentation](https://docs.bentonow.com)
- [n8n Community Nodes Documentation](https://docs.n8n.io/integrations/community-nodes/)
- [Bento n8n Community Node GitHub Repository](https://github.com/bentonow/bento-n8n-sdk)
- [Join our Discord Community](https://discord.gg/ssXXFRmt5F)