# 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


| Method                                                      | Endpoint                                                                | Name                                                       |
|-------------------------------------------------------------|-------------------------------------------------------------------------|------------------------------------------------------------|
|     |  | [Import Subscribers](/docs/subscribers#import-subscribers) |
|  |       | [Search Subscribers](/docs/subscribers#search-subscribers) |
|  |  | [Find Subscriber](/docs/subscribers#find-subscriber)       |
|     |  | [Create Subscriber](/docs/subscribers#create-subscriber)   |
|     |     | [Run Command](/docs/subscribers#run-command)               |

---

## 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

    
      - **email** (`string`): 
        The Email Address for the subscriber.
      
    
  


---

## Import Subscribers {{ tag: 'POST', label: '/v1/batch/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
    
      - **email** (`string`): 
        The Email Address for the subscriber.
      
    

    ### Optional Attributes
    
      - **first_name** (`string`): 
        The first name for the subscriber
      
      - **last_name** (`string`): 
        The last name for the subscriber
      
      - **tags** (`string`): 
        Comma separated list of tags, if a tag doesn't exist it is created.
      
      - **remove_tags** (`string`): 
        Comma separated list of tags to remove from the subscriber.
      
      - **some_other_field** (`string`): 
        `key` / `value` pair for storing other fields for the subscriber.
      
    

  
  

    

  

<br/><br/>

  
    ### Response
    The response will contain the result count of subscribers.
  
  
    
  


---

## Search Subscribers {{ tag: 'GET', label: '/v1/fetch/search' }}


  

    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

    
      - **page** (`integer`): 
        Page number for the search
      
    

    ### Optional Attributes

    
      - **tags** (`array|string`): 
        Preferred filter. Accepts an array of tag names or a comma separated string.
      
      - **tag_names** (`array|string`): 
        Alias for `tags`. Accepts an array of tag names or a comma separated string.
      
      - **tag_ids** (`array|string`): 
        Legacy compatibility filter. Accepts internal tag ids as an array or comma separated string.
      
      - **created_at** (`object`): 
        The Creation date of the subscriber. <br/>
        `gt` `` - greater than date <br/>
        `lt` `` - less than date <br/>
      
      - **updated_at** (`object`): 
        The update date of the subscriber <br/>
        `gt` `` - greater than date <br/>
        `lt` `` - less than date <br/>
      
      - **last_event_at** (`object`): 
        The last event date of the subscriber. <br/>
        `gt` `` - greater than date <br/>
        `lt` `` - less than date <br/>
      
      - **unsubscribed_at** (`object`): 
        The unsubscription date of the subscriber. <br/>
        `gt` `` - greater than date <br/>
        `lt` `` - less than date <br/>
      
    


  
  

    

  

<br/><br/>

  
    ### 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.

  
  
    
  


---

## Find Subscriber {{ tag: 'GET', label: '/v1/fetch/subscribers' }}


  
    Fetch a matched subscriber in your account.
  ### Required Attributes
    
      - **email** (`string`): 
        Email address to search for a match in your account
      
    

    ### Optional Attributes
    
      - **uuid** (`string`): 
        This returns the subscriber with the given identifier, though it is rarely needed. Can be used in place of email address.
      
    
  
  
    
  

<br/><br/>

  
    ### Response
    Returns the subscriber details.
  
  
    
  


---

## Create Subscriber {{ tag: 'POST', label: '/v1/fetch/subscribers' }}


  
    Creates a subscriber in your account and queues them for indexing.
    ### Required Attributes
    
      - **subscriber** (`object`): 
        An Array of subscriber emails to create. <br/>
        `email` `` - subscriber email address <br/>
      
    

  
  
    
  

<br/><br/>

  
    ### Response
    Returns the created subscriber's details.

  
  
    
  


---

## Run Command {{ tag: 'POST', label: '/v1/fetch/commands' }}


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

    
> ⚠️ **Warning**
> 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
    
      - **command** (`object`): 
        An Array of subscriber and details to change. <br/>
        `command` `` - `add_tag`, `add_tag_via_event`, `remove_tag`, `add_field`, `remove_field`, `subscribe`, `unsubscribe`, `change_email` <br/><br/>
        `email` `` - subscriber email address <br/><br/>
        `query` `` - data for the requested change <br/>
      
    

  
  
    
  

<br/><br/>

  
    ### Response
    Returns the updated subscriber details.