n8n-nodes-bento.Hi {{ name }}, your order {{ order_number }} is confirmed.
" Transactional: true Personalizations: - Key: name Value: "={{ $json.name }}" - Key: order_number Value: "={{ $json.order_id }}" ``` --- ### 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 **Example Command Mapping:** | Command | Extra Parameters | | --- | --- | | Add Tag | `Tag/Field Name` | | Remove Tag | `Tag/Field Name` | | Add Tag via Event | `Tag/Field Name` | | Add Field | `Field Key`, `Field Value` | | Remove Field | `Tag/Field Name` | | Subscribe | None | | Unsubscribe | None | | Change Email | `New Email` | --- ### Validate Email Validate email addresses for spam and 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:** The validation response returned by Bento for the provided email, plus echoed request inputs in the node output **Example Use Cases:** - Filter out invalid emails before adding subscribers - Prevent spam signups - Improve email deliverability rates - Validate email quality in real-time --- ### Audience Schema Operations The new Bento node also covers field and tag management directly from n8n. #### List Fields Retrieve the Bento custom fields configured for the current site. - **Required Parameters**: None - **Returns**: The Bento field records returned for the current site - **Example Use Cases**: - Audit the custom field schema before syncing profile data - Populate internal documentation or dropdowns with Bento field definitions - Check whether a field exists before trying to write to it #### Create Field Create a new Bento custom field definition. - **Required Parameters**: `Field Key` - **Returns**: The Bento create-field response, plus a `fields` array when Bento returns one - **Example Use Cases**: - Provision new profile fields before importing subscriber data - Standardize field creation from infrastructure workflows - Expand your Bento schema without leaving n8n ```yaml Node: Bento Operation: Create Field Field Key: plan_tier ``` #### List Tags Retrieve the Bento tags configured for the current site. - **Required Parameters**: None - **Returns**: All Bento tags available for segmentation and automation - **Example Use Cases**: - Audit tagging conventions before launching campaigns - Populate tag pickers in internal workflow tooling - Check whether a tag exists before applying it to subscribers #### Create Tag Create a new Bento tag. - **Required Parameters**: `Tag Name` - **Returns**: The Bento create-tag response, plus a `tags` array when Bento returns one - **Example Use Cases**: - Provision tags during onboarding of new automation flows - Standardize segmentation setup across environments - Create campaign-specific tags on demand from n8n ```yaml Node: Bento Operation: Create Tag Tag Name: onboarding ``` --- ### Automation Content Operations The Bento node can now inspect and update sequence, workflow, and template content directly from n8n. #### List Sequences - **Optional Parameters**: `Page` - **Returns**: Sequence records with nested email template metadata - **Example Use Cases**: - Inspect available nurture sequences before appending emails - Build reporting or approval workflows around sequence inventory - Sync sequence metadata into internal tooling #### Create Sequence Email - **Required Parameters**: `Sequence ID`, `Subject`, `HTML` - **Optional Parameters**: `Inbox Snippet`, `Delay Interval`, `Delay Interval Count`, `Editor Choice`, `To`, `CC`, `BCC` - **Returns**: The created Bento email template payload - **Example Use Cases**: - Append onboarding or upsell emails to an existing sequence - Generate sequence content programmatically from CMS or AI outputs - Keep Bento sequence maintenance inside n8n deployment workflows ```yaml Node: Bento Operation: Create Sequence Email Sequence ID: seq_12345 Subject: "Day 2: Set up your first Bento workflow" HTML: "Hi {{ first_name }},
Here is your next setup step.
" Inbox Snippet: "Finish the setup in five minutes" Delay Interval: days Delay Interval Count: 2 Editor Choice: classic ``` #### List Workflows - **Optional Parameters**: `Page` - **Returns**: Workflow records with embedded email templates - **Example Use Cases**: - Review live versus draft workflows before publishing related changes - Feed workflow metadata into ops dashboards - Inventory Bento automation assets without leaving n8n #### Get Email Template - **Required Parameters**: `Template ID` - **Returns**: The Bento email template response for the requested numeric template ID - **Example Use Cases**: - Inspect a template before updating it - Pull Bento email content into approval or review workflows - Sync template metadata into internal systems #### Update Email Template - **Required Parameters**: `Template ID` - **Optional Parameters**: `Subject`, `HTML` - **Returns**: The updated Bento email template payload - **Behavior Note**: The node requires at least one of `Subject` or `HTML` - **Example Use Cases**: - Roll out copy changes across existing templates - Update HTML from a centralized content workflow - Patch production templates from automated release jobs ```yaml Node: Bento Operation: Update Email Template Template ID: 4821 Subject: "Updated onboarding lesson" HTML: "We revised this step to make setup easier.
" ``` --- ### Analytics Operations The newer Bento node includes dedicated analytics operations for site, segment, and report-level metrics. #### Site Metrics - **Required Parameters**: None - **Returns**: The Bento site metrics response, plus a compact totals summary when recognized totals are present - **Example Use Cases**: - Monitor list growth from dashboards or health checks - Provide executives with a quick snapshot of site-wide performance - Automate daily or weekly rollups without manual filtering #### Segment Metrics - **Required Parameters**: `Segment ID` - **Returns**: The Bento segment metrics response, plus a compact summary when recognized metrics are present - **Example Use Cases**: - Evaluate segment performance before launching automation - Compare engagement across high-value cohorts - Spot drop-offs in segment engagement over time #### Report Metrics - **Required Parameters**: `Report ID` - **Returns**: The Bento report metrics response, plus a compact summary when recognized metrics are present - **Example Use Cases**: - Summarize the results of a generated report for stakeholders - Refresh dashboards that rely on Bento report data - Monitor revenue and engagement contained in saved Bento reports ```yaml Site Metrics: Operation: Site Metrics Segment Metrics: Operation: Segment Metrics Segment ID: "segment_12345" Report Metrics: Operation: Report Metrics Report ID: "report_98765" ``` --- ### Broadcast Operations The updated node can also review existing broadcasts and queue new broadcast sends. #### List Broadcasts - **Optional Parameters**: `Status`, `Created After`, `Tag IDs` - **Returns**: The Bento broadcast list plus node-level summary fields such as `total` and `scheduledCount` - **Example Use Cases**: - Review scheduled broadcasts before deploying - Audit campaigns tied to certain tags - Build dashboards of historical broadcast activity #### Send Broadcast - **Required Parameters**: `Campaign Name`, `Subject`, `Content`, `Content Type`, `From Email`, `From Name`, `Confirm Send` - **Optional Parameters**: `Approved`, `Inclusive Tags`, `Exclusive Tags`, `Segment ID`, `Batch Size Per Hour` - **Returns**: Bento's API response including any broadcast objects returned or validation errors - **Parameter Note**: `Inclusive Tags` and `Exclusive Tags` are comma-separated strings in this node - **Example Use Cases**: - Launch ad-hoc campaigns from n8n using Bento's batch API - Enforce hour-based throttling for large broadcasts - Target subsets of the audience with inclusive or exclusive tag filters while keeping workflows code-free ```yaml Node: Bento Operation: Send Broadcast Campaign Name: "April product launch" Subject: "The new release is live" Content Type: html Content: "Everything is ready.
" From Email: "hello@example.com" From Name: "Bento Team" Approved: true Inclusive Tags: "launch,customers" Exclusive Tags: "suppress_internal" Segment ID: "segment_12345" Batch Size Per Hour: 2000 Confirm Send: true ``` > ⚠️ **Warning** > `Send Broadcast` will refuse to run unless `Confirm Send` is enabled. That > guard exists specifically to prevent accidental campaign launches from test > runs or incomplete workflows. --- ### Validation And Enrichment Operations The Bento node also includes experimental utility endpoints that are useful in intake, compliance, and enrichment workflows. #### Blacklist Check - **Required Parameters**: Provide at least one of `Domain` or `IP Address` - **Returns**: The Bento blacklist response for the provided domain and/or IP - **Example Use Cases**: - Screen incoming leads or signup forms by their sending domain - Enforce allow or deny rules in automations before triggering downstream actions - Investigate suspicious traffic by cross-referencing domain activity with IP reputation #### Content Moderation - **Required Parameters**: `Content` - **Optional Parameters**: `Metadata` - **Returns**: The Bento moderation response plus echoed metadata when provided - **Example Use Cases**: - Review user-generated content before publishing or emailing - Flag risky support tickets for manual review - Audit campaign content for compliance keywords #### Gender Guess - **Required Parameters**: At least one of `First Name` or `Last Name` - **Optional Parameters**: `Email` - **Returns**: The Bento gender-guess response, plus a summary when Bento returns prediction fields - **Example Use Cases**: - Tailor messaging tone dynamically - Enrich CRM profiles with probabilistic attributes - Flag low-confidence guesses for manual review #### Geolocation Lookup - **Required Parameters**: `IP Address` - **Optional Parameters**: `User Agent` - **Returns**: The Bento geolocation response for the provided IP address - **Example Use Cases**: - Enrich analytics dashboards with regional context - Detect mismatched login locations for security checks - Personalize offers based on detected location **Example Validation And Moderation Flow:** ```yaml 1. Webhook 2. Bento → Validate Email 3. IF → reject disposable or risky addresses 4. Bento → Blacklist Check 5. Bento → Content Moderation 6. Continue to Create Subscriber or Send Transactional Email ``` ## Best Practices ### Security Best Practices - Always use n8n's credential system and never hardcode Bento keys - Keep your Secret Key private and restrict who can edit production credentials - Treat experimental enrichment endpoints as best-effort helpers rather than required steps - Use HTTPS everywhere and avoid passing sensitive data in unnecessary custom fields or event properties - Review any transactional send carefully before enabling the `Transactional` option ### Workflow Best Practices - Use n8n's `Continue On Fail` option for enrichment and validation branches when a safe fallback exists - For large imports, list or create fields and tags before syncing subscriber records - Use `List Sequences`, `List Workflows`, and `Get Email Template` before changing live content - Add approval steps before `Send Broadcast`, especially in shared workspaces - Use meaningful workflow and node names so operational debugging stays fast ### Event Tracking Best Practices - Use descriptive event names such as `purchase_completed`, `page_viewed`, or `trial_started` - Include event properties that are useful for segmentation, but avoid sensitive data - Keep your event naming conventions consistent across apps and automation flows - Use subscriber commands and tags to complement event tracking rather than duplicating it - Track important milestones consistently so segment and report metrics stay trustworthy ### Email And Content Best Practices - Choose the correct `Email Type` and make sure the matching body field is populated - Test sequence and template updates in development before touching production content - Use `Confirm Send` and optional throttling on broadcasts to reduce operational risk - Use valid sender email addresses because the node validates email format before send operations - When updating templates programmatically, keep the source HTML in version control outside n8n as well ### Reporting Best Practices - Use `Site Metrics` for high-level health checks and `Segment Metrics` for cohort analysis - Use `Report Metrics` when you already have Bento report IDs from an existing workflow - Schedule analytics pull workflows during low-traffic windows if they feed large internal dashboards - Store snapshot results in Sheets, Slack, or your warehouse when you need historical comparisons - Separate campaign reporting workflows from campaign sending workflows so failures are easier to isolate ## 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 ecommerce platform 2. **Track Event**: Send `purchase_completed` event with order details 3. **Update Subscriber**: Add `customer` data and update fields such as LTV or plan 4. **Subscriber Command**: Apply a lifecycle tag such as `customer` 5. **Send Email**: Order confirmation or post-purchase follow-up ### Lead Scoring Workflow 1. **Trigger**: User performs action such as downloading content or visiting the pricing page 2. **Track Event**: Record engagement event 3. **Get Subscriber**: Retrieve current subscriber data 4. **Subscriber Command**: Add tags or fields based on behavior 5. **Conditional Logic**: Trigger different flows based on lead score or lifecycle stage ### Audience Provisioning Workflow 1. **Trigger**: Manual or scheduled workflow before a new campaign launch 2. **List Fields**: Check whether required profile fields already exist 3. **Create Field**: Provision missing fields 4. **List Tags**: Check the segmentation tags you expect to use 5. **Create Tag**: Create any missing tags before the import or campaign starts ### Sequence Content Management Workflow 1. **Trigger**: Content release or approval event 2. **List Sequences**: Inspect available sequences 3. **Create Sequence Email**: Add the next step in a nurture sequence 4. **Get Email Template**: Pull the new template back for approval or QA 5. **Update Email Template**: Patch copy or HTML if changes are required ### Broadcast Approval Workflow 1. **Trigger**: Manual approval or internal review form 2. **List Broadcasts**: Review queued or scheduled campaigns 3. **Conditional Logic**: Confirm tags, segment, sender identity, and content 4. **Send Broadcast**: Queue the approved campaign with `Confirm Send` enabled 5. **Slack Or Email Notification**: Notify the team after the broadcast is accepted ### Validation And Moderation Workflow 1. **Trigger**: Form submission or inbound support content 2. **Validate Email**: Check risk before creating the subscriber 3. **Blacklist Check**: Evaluate suspicious domains or IPs 4. **Content Moderation**: Review message content for policy flags 5. **Branching Logic**: Route risky traffic to manual review and send clean traffic downstream ### Daily Metrics Digest 1. **Trigger**: Schedule trigger each morning 2. **Site Metrics**: Pull account-wide Bento metrics 3. **Segment Metrics**: Evaluate one or more high-value segments 4. **Report Metrics**: Attach saved report summaries 5. **Output**: Post the digest to Slack, email, or your reporting system ## Troubleshooting ### Common Authentication Problems **Error: "Authentication Failed"** - Verify your Publishable Key, Secret Key, and Site UUID are correct - Make sure the credential is attached to the Bento node you are testing - Re-test the credential after rotating Bento keys **Error: "Invalid API Key"** - Confirm your Secret Key has not been regenerated or revoked - Check that your Publishable Key and Secret Key belong to the same Bento account ### Common Operation Problems **Error: "Invalid Email Format"** - Ensure email addresses follow RFC-compliant formatting - Trim extra spaces or malformed values before sending them into Bento **Error: "Broadcast send blocked"** - Enable `Confirm Send` - Make sure the sender email and sender name are present - Double-check content type and content body values **Error: "HTML Validation Failed"** - Remove scripts, forms, iframes, or inline event handlers from email HTML - Keep sequence and template updates limited to safe email markup **Error: "Template or Sequence Not Found"** - Re-check the `Template ID` or `Sequence ID` - Use `List Sequences` or `Get Email Template` first if you are unsure of the target ### 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 imports or campaign jobs into smaller batches **Error: "Rate Limited"** - Reduce request frequency in high-volume workflows - Add delays or batching when processing large subscriber sets **Experimental Endpoint Failures** - Use fallback branches for validation and enrichment steps - Treat blacklist, moderation, gender, and geolocation lookups as non-critical where possible ## 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 are limited to 50 characters and values to 500 characters - **Rate Limiting**: Built-in retry and backoff behavior helps prevent API quota exhaustion ### Security Features - **Input Validation**: Key inputs are validated for length, format, and security before requests are sent - **HTML Sanitization**: HTML content is sanitized to prevent unsafe email markup - **Email Validation**: Email addresses are validated using RFC-compliant checks before supported operations run - **Secure Error Handling**: Error messages are designed not to expose sensitive credential data ### Reliability Features - **Automatic Retries**: Retryable Bento errors are retried with exponential backoff - **Timeout Handling**: Request timeouts prevent hung workflows - **Concurrent Request Management**: The node limits concurrent requests per instance - **Broadcast Safety Check**: Broadcast sends require explicit confirmation ### API Endpoints Used The Bento node automatically appends `site_uuid` from your credential to every request. The operation-specific paths are: - `POST /api/v1/batch/events` for subscriber creation and event tracking - `POST /api/v1/batch/subscribers` for subscriber updates - `GET /api/v1/fetch/subscribers?email=...` for subscriber lookups - `POST /api/v1/fetch/commands` for subscriber commands - `GET /api/v1/fetch/fields` and `POST /api/v1/fetch/fields` for Bento field definitions - `GET /api/v1/fetch/tags` and `POST /api/v1/fetch/tags` for Bento tags - `GET /api/v1/fetch/sequences` for sequence inventory - `POST /api/v1/fetch/sequences/:sequenceId/emails/templates` for sequence email creation - `GET /api/v1/fetch/workflows` for workflow inventory - `GET /api/v1/fetch/emails/templates/:id` and `PATCH /api/v1/fetch/emails/templates/:id` for template reads and updates - `POST /api/v1/batch/emails` for transactional email sends - `GET /api/v1/fetch/broadcasts` and `POST /api/v1/batch/broadcasts` for broadcast review and send - `GET /api/v1/stats/site`, `GET /api/v1/stats/segment`, and `GET /api/v1/stats/report` for analytics - `POST /api/v1/experimental/validation`, `GET /api/v1/experimental/blacklist`, `POST /api/v1/experimental/content_moderation`, `POST /api/v1/experimental/gender`, and `GET /api/v1/experimental/geolocation` for validation and enrichment ## 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, install `n8n-nodes-bento` through the Community Nodes section in your workspace settings. ### What happens if an email address is invalid? The node includes built-in email validation for supported operations. Invalid email addresses return an error that you can handle with n8n's error handling tools. For uncertain emails, use the `Validate Email` operation before creating or emailing the subscriber. ### Can I send emails to unsubscribed users? The SDK exposes a `Transactional` boolean on `Send Transactional Email` and passes it through to Bento. In the node source, that flag is documented as affecting tracking and analytics. Any unsubscribe behavior beyond that is defined by Bento rather than enforced by the n8n node. ### Do I need to pass `site_uuid` manually? No. The Bento node appends `site_uuid` from your saved credential to each Bento request automatically. ### How should I use the experimental endpoints safely? Put validation and enrichment steps behind `IF` checks or enable `Continue On Fail` when a fallback path is acceptable. They are useful for moderation, screening, and enrichment, but they should not always be the single point of failure in a production workflow. ### How do I avoid sending a campaign by mistake? Keep `Send Broadcast` behind a manual approval branch and leave `Confirm Send` disabled in development. The node intentionally blocks the request until `Confirm Send` is enabled. ## Additional Resources - [Bento API Documentation](https://docs.bentonow.com) - [Bento Authentication Docs](https://docs.bentonow.com/authentication) - [n8n Community Nodes Documentation](https://docs.n8n.io/integrations/community-nodes/) - [Bento n8n Community Node Repository](https://github.com/bentonow/bento-n8n-sdk)