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 look up methods.
Available Endpoints
Method | Endpoint | Name |
---|---|---|
POST | /batch/subscribers | Import Subscribers |
GET | /fetch/search | Search Subscribers |
GET | /fetch/subscribers | Find Subscriber |
POST | /fetch/subscribers | Create Subscriber |
POST | /fetch/commands | Run Command |
The Subscriber Model
The Subscriber model contains all the identify 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.
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.
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 seperated list of tags, if a tag doesn't exist it is created.
- Name
remove_tags
- Type
- string
- Description
Comma seperated 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.
Request
curl -L -X POST 'https://app.bentonow.com/api/v1/batch/subscribers?site_uuid=ExampleID1234' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE64ENCODE(USERNAME+PASSWORD)' \
--data-raw '{
"subscribers": [
{
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"tags": "lead,mql",
"remove_tags": "customers",
"some_other_field": "some value"
}
]
}'
Response
The response will contain the result count of subscribers.
JSON Response
{
"result": 1
},
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.
Required Attributes
- Name
page
- Type
- integer
- Description
Page number for the search
Optional Attributes
- 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
Request
curl -L -X GET 'https://app.bentonow.com/api/v1/fetch/search?site_uuid=ExampleID1234' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE64ENCODE(USERNAME+PASSWORD)' \
--data-raw '{
"page": 1,
"created_at": {
"gt": "string",
"lt": "string"
},
"updated_at": {
"gt": "string",
"lt": "string"
},
"last_event_at": {
"gt": "string",
"lt": "string"
},
"unsubscribed_at": {
"gt": "string",
"lt": "string"
}
}'
Response
Returns a report of users that match the request.
JSON Response
"data": [
{
"id": "string",
"type": "string",
"attributes": {
"uuid": "string",
"email": "string",
"fields": {},
"cached_tag_ids": [
"string"
],
"unsubscribed_at": "string",
"navigation_url": "string"
}
}
],
"meta": {
"page": 0,
"query": {
"email": {
"not": "string"
}
}
}
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.
Request
curl -L -X GET 'https://app.bentonow.com/api/v1/fetch/subscribers?site_uuid=ExampleID1234&[email protected]' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE64ENCODE(USERNAME+PASSWORD)'
Response
Returns the subscriber details.
JSON Response
"data": {
"id": "string",
"type": "string",
"attributes": {
"uuid": "string",
"email": "string",
"fields": {},
"cached_tag_ids": [
"string"
]
}
}
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
Request
curl -L -X POST 'https://app.bentonow.com/api/v1/fetch/subscribers?site_uuid=ExampleID1234' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE64ENCODE(USERNAME+PASSWORD)' \
--data-raw '{
"subscriber": {
"email": "[email protected]"
}
}'
Response
Returns the created subscribers details.
JSON Response
"data": {
"id": "12345",
"type": "visitors",
"attributes": {
"uuid": "123-123-123-123-123",
"email": "[email protected]",
"fields": {},
"cached_tag_ids": [
"123"
]
}
}
Run Command
Endpoint to execute a command and change a subscriber's data.
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
Request
curl -L -X POST 'https://app.bentonow.com/api/v1/fetch/commands' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE64ENCODE(USERNAME+PASSWORD)' \
--data-raw '{
"command": [
{
"command": "add_tag",
"email": "[email protected]",
"query": "test"
},
{
"command": "add_tag_via_event",
"email": "[email protected]",
"query": "test"
},
{
"command": "remove_tag",
"email": "[email protected]",
"query": "test"
},
{
"command": "add_field",
"email": "[email protected]",
"query": {
"key": "test",
"value": "test"
}
},
{
"command": "remove_field",
"email": "[email protected]",
"query": "test"
},
{
"command": "subscribe",
"email": "[email protected]"
},
{
"command": "unsubscribe",
"email": "[email protected]"
},
{
"command": "change_email",
"email": "[email protected]",
"query": "[email protected]"
}
]
}'
Response
Returns the updated subscriber details.
JSON Response
"data": {
"id": "12345",
"type": "visitors",
"attributes": {
"uuid": "123-123-123-123-123",
"email": "[email protected]",
"fields": {},
"cached_tag_ids": [
"123"
]
}
}