Utility

Experimental APIs that are designed for specific use cases, offering advanced functionalities tailored to niche use cases.

These endpoints are all considered experimental and subject to change, as we continuously refine and enhance based on user feedback and technological changes.

Available Endpoints

Method	Endpoint	Name
GET	experimental/blacklist.json	Search Blacklists
POST	experimental/validation	Validate Email
POST	experimental/content_moderation	Moderate Content
POST	experimental/gender	Guess Gender
GET	experimental/geolocation	Geolocate IP Address

GET/v1/experimental/blacklist.json

Search Blacklists

The Blacklist Model

Validates the IP or domain name with industry email reputation services to check for delivery issues.

A true value for any of the keys in the model indicates a problem

Properties

Name
just_registered
Type
boolean
Description
true / false flag if the domain age is flagged.
Name
spamhaus
Type
boolean
Description
Spamhaus considers mail from this domain or ip to be contain likely spam.
Name
nordspam
Type
boolean
Description
Nordspam considers mail from this domain or ip to likely contain spam.
Name
spfbl
Type
boolean
Description
Spfbl considers mail from this domain or ip to likely contain spam.
Name
sorbs
Type
boolean
Description
Sorbs considers mail from this domain or ip to likely contain spam.
Name
abusix
Type
boolean
Description
Abusix considers mail from this domain or ip to likely contain spam.

You can provide either a domain or an IP to be looked up.

Only IPV4 addresses are currently supported.

Required Attributes

Name
domain
Type
string
Description
Please provide just the domain (e.g., google.com) without including the protocol (such as http:// or https://)
Name
ip_address
Type
string
Description
Please provide just the IP address.

Request

GET

/v1/experimental/blacklist.json

curl -L -X POST 'https://app.bentonow.com/api/v1/experimental/blacklist?domain=test.com&ip=1.1.1.1' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE64ENCODE(USERNAME+PASSWORD)'
}'

Response

Returns the details of the reputation check.

Results can be null if all the checks return false.

JSON Response

"data": [
    {
      "query": "example.com",
      "description": "If any of the following blacklist providers contains true you have a problem on your hand.",
      "results": {
          "just_registered": true,
          "spamhaus": true,
          "nordspam": true,
          "spfbl": true,
          "sorbs": true,
          "abusix": true
      }
    }
]

POST/v1/experimental/validation

Validate Email

The Validate Email Model

Validates the email address using the provided information to infer its validity.

Properties

Name
valid
Type
boolean
Description
true / false flag if the email address is considered valid.

Validate the submitted email address against spam patterns.

Required Attributes

Name
email
Type
string
Description
Validates an email's domain using MX records.

Optional Attributes

Name
name
Type
string
Description
The contacts full name. Heavy bias towards US Census Data. False positives possible.
Name
user_agent
Type
string
Description
The user agent as a string.
Name
ip
Type
string
Description
The users IP address. Returns false for all countries outside of Tier 1.

Request

POST

/v1/experimental/validation

curl -L -X POST 'https://app.bentonow.com/api/v1/experimental/validation?name=John+Doe&ip=1.1.1.1&[email protected]' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE64ENCODE(USERNAME+PASSWORD)' \
}'

Response

Returns the details of the validation check.

JSON Response

"data": [
  {
    "valid": false,
  }
]

POST/v1/experimental/content_moderation

Moderate Content

The Moderate Content Model

An opinionated Content moderation.

Properties

Name
valid
Type
boolean
Description
true / false flag if the supplied content is considered safe.
Name
reasons
Type
array
Description
string values of the issues found with the supplied content.
Name
safe_original_content
Type
string
Description
A safe version of the supplied content.

This endpoint will return an opinionated moderation score based on the content provided. This is optimised for small amounts of text content, where you never want a link/XSS/etc inside it.

Required Attributes

Name
content
Type
string
Description
The content you wish to moderate.

Request

POST

/v1/experimental/validation

curl -L -X POST 'https://app.bentonow.com/api/v1/experimental/content_moderation?content=Its%20just%20so%20fluffy!' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE64ENCODE(USERNAME+PASSWORD)' \
}'

Response

Returns results of the content moderation.

JSON Response

{
  "valid": true,
  "reasons": [],
  "safe_original_content": "Its just so fluffy!"
}

POST/v1/experimental/gender

Guess Gender

The Gender Guess Model

Guess a subscriber's gender using their first and last name. Best for US users; based on US Census Data.

Properties

Name
gender
Type
string
Description
The guessed gender based on census data.
Name
confidence
Type
float
Description
Confidence level of the guess.

This endpoint allows you to guess the gender of a subscriber based on their first name and last name. Works best with US users as we use US Census Data to make our guesses.

Required Attributes

Name
name
Type
string
Description
This can be the full name of a subscriber or last name.

Request

POST

/v1/experimental/gender

curl -L -X POST 'https://app.bentonow.com/api/v1/experimental/gender?name=John%20Doe' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE64ENCODE(USERNAME+PASSWORD)'
}'

Response

The result of the guessed gender.

The response will always return a confidence level.

JSON Response

{
  "gender": "male",
  "confidence": 0.99497487437186
}

GET/v1/experimental/geolocation

Geolocate IP Address

The Geolocate IP Address Model

This endpoint attempts to geolocate the provided IP address.

This only works with IPV4 IP Addresses

Properties

Name
request
Type
string
Description
The provided IP address that was geolocated.
Name
ip
Type
string
Description
The IP address that was geolocated.
Name
country_code2
Type
string
Description
Two letter country code.
Name
country_code3
Type
string
Description
Three letter country code.
Name
country_name
Type
string
Description
Full name of the country.
Name
continent_code
Type
string
Description
The continent code.
Name
region_name
Type
string
Description
The regional name.
Name
city_name
Type
string
Description
City name.
Name
postal_code
Type
string
Description
Regional postal code.
Name
latitude
Type
number
Description
Latitude for the ip address.
Name
longitude
Type
number
Description
Longitude for the ip address.
Name
dma_code
Type
string
Description
DMA code for the ip address.
Name
area_code
Type
string
Description
Area code if available for the ip address.
Name
timezone
Type
string
Description
Regional time UTC time zone.
Name
real_region_name
Type
string
Description
The real region name.

This end point will geolocate the provided ip address.

Required Attributes

Name
ip
Type
string
Description
The IPV4 address you with to geolocate.

Request

GET

/v1/experimental/geolocation

curl -L -X POST 'https://app.bentonow.com/api/v1/experimental/geolocation?ip=1.1.1.1' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE64ENCODE(USERNAME+PASSWORD)'
}'

Response

The result of the ip geolocation.

The response will contain null values for keys.

JSON Response

{
  "request": "1.1.1.1",
  "ip": "1.1.1.1"
  "country_code2": "JP"
  "country_code3": "JPN"
  "country_name": "Japan"
  "continent_code": "AS"
  "region_name": "42"
  "city_name": "Tokyo"
  "postal_code": "206-0000"
  "latitude": 35.6895,
  "longitude": 139.69171,
  "dma_code": null,
  "area_code": null,
  "timezone": "Asia/Tokyo"
  "real_region_name": "Tokyo"
}