ONLINE
Bento

Subscribers

Manage your subscribers. When you are a new customer with an existing list you might use the import subscribers endpoint. Find and search subscribers with convenient lookup methods.

Available Endpoints

MethodEndpointCopy
POST/batch/subscribers

Import Subscribers

Bulk create or update subscribers without triggering automations.

GET/fetch/search

Search Subscribers

Search subscribers by page and filters.

GET/fetch/subscribers

Find Subscriber

Fetch a subscriber by email or UUID.

POST/fetch/subscribers

Create Subscriber

Create a single subscriber record.

POST/fetch/commands

Run Command

Apply a targeted subscriber command when batch endpoints do not fit.

The Subscriber Model

The Subscriber model contains all the identity information about your subscribers, such as their email address, first name, last name, and tags. You can add other key / value fields to hold other information about the subscriber, such as notes or other important details.

Properties

  • Name
    email
    Type
    string
    Description

    The Email Address for the subscriber.

POST/v1/batch/subscribers

Import Subscribers

This endpoint emulates our background processes for imports, serving as the go-to method for subscriber additions and updates. When you send your data to Bento, it's processed through our import queues. Although updates are typically swift, they can take up to 5 minutes to reflect. This endpoint is ideal for both bulk and single subscriber updates.

Request supports 1 to 1000 subscribers per post.
Does not trigger Flows or Automations.

Required Attributes

  • Name
    email
    Type
    string
    Description

    The Email Address for the subscriber.

Optional Attributes

  • Name
    first_name
    Type
    string
    Description

    The first name for the subscriber

  • Name
    last_name
    Type
    string
    Description

    The last name for the subscriber

  • Name
    tags
    Type
    string
    Description

    Comma separated list of tags, if a tag doesn't exist it is created.

  • Name
    remove_tags
    Type
    string
    Description

    Comma separated list of tags to remove from the subscriber.

  • Name
    some_other_field
    Type
    string
    Description

    key / value pair for storing other fields for the subscriber.



Response

The response will contain the result count of subscribers.

GET/v1/fetch/search

Search Subscribers

This endpoint delivers a report of the most recent 100 subscribers who accessed a page resource, complete with options for date-based searching and filtering.

This endpoint is limited to Bento Enterprise customers only. Please contact us for early access.
Use tag names in tags, not internal tag IDs. You can send an array or a comma-separated string like customer,lead,enterprise.
tag_names is also accepted as an alias. tag_ids still works for older integrations, but tags is the recommended param.

Required Attributes

  • Name
    page
    Type
    integer
    Description

    Page number for the search

Optional Attributes

  • Name
    tags
    Type
    array|string
    Description

    Preferred filter. Accepts an array of tag names or a comma separated string.

  • Name
    tag_names
    Type
    array|string
    Description

    Alias for tags. Accepts an array of tag names or a comma separated string.

  • Name
    tag_ids
    Type
    array|string
    Description

    Legacy compatibility filter. Accepts internal tag ids as an array or comma separated string.

  • Name
    created_at
    Type
    object
    Description

    The Creation date of the subscriber.
    gt date string - greater than date
    lt date string - less than date

  • Name
    updated_at
    Type
    object
    Description

    The update date of the subscriber
    gt date string - greater than date
    lt date string - less than date

  • Name
    last_event_at
    Type
    object
    Description

    The last event date of the subscriber.
    gt date string - greater than date
    lt date string - less than date

  • Name
    unsubscribed_at
    Type
    object
    Description

    The unsubscription date of the subscriber.
    gt date string - greater than date
    lt date string - less than date



Response

Returns a report of users that match the request.

When you search with tags or tag_names, the response metadata includes both the requested tag names and the resolved cached_tag_ids used internally for search.
GET/v1/fetch/subscribers

Find Subscriber

Fetch a matched subscriber in your account.

Required Attributes

  • Name
    email
    Type
    string
    Description

    Email address to search for a match in your account

Optional Attributes

  • Name
    uuid
    Type
    string
    Description

    This returns the subscriber with the given identifier, though it is rarely needed. Can be used in place of email address.



Response

Returns the subscriber details.

POST/v1/fetch/subscribers

Create Subscriber

Creates a subscriber in your account and queues them for indexing.

Required Attributes

  • Name
    subscriber
    Type
    object
    Description

    An Array of subscriber emails to create.
    email string - subscriber email address



Response

Returns the created subscriber's details.

POST/v1/fetch/commands

Run Command

Endpoint to execute a command and change a subscriber's data.

This endpoint is not recommended for most use cases as it has a delayed response. It is recommended to use if the batch endpoints are not working for your use case.

Required Attributes

  • Name
    command
    Type
    object
    Description

    An Array of subscriber and details to change.
    command string - add_tag, add_tag_via_event, remove_tag, add_field, remove_field, subscribe, unsubscribe, change_email

    email string - subscriber email address

    query string/object - data for the requested change



Response

Returns the updated subscriber details.

Was this page useful?

Your answer helps us find docs that need work.