Utility

Experimental APIs crafted for niche use cases like blacklist monitoring, validation, moderation, and geolocation.

Experimental APIs designed for niche automation and trust-and-safety workflows. Endpoints may change as feedback rolls in, so monitor integration logs closely.

Method	Endpoint	Description
GET	/v1/experimental/blacklist.json	Search Blacklists
POST	/v1/experimental/validation	Validate Email
POST	/v1/experimental/jesses_ruleset	Validate Email (Jesse's Ruleset)
POST	/v1/experimental/content_moderation	Moderate Content
POST	/v1/experimental/gender	Guess Gender
GET	/v1/experimental/geolocation	Geolocate IP Address

GET /v1/experimental/blacklist.json

Search Blacklists

Look up a domain or IPv4 address against reputation providers so you can flag deliverability issues early.

Input

domain · string: Domain to inspect (e.g., `example.com`).
ip_address · string: IPv4 address to inspect.

Provide either `domain` or `ip_address`. IPv6 is not supported.

cURL

bash

curl -L -u publishableKey:secretKey \
  -X GET "https://app.bentonow.com/api/v1/experimental/blacklist?site_uuid=ExampleID1234&domain=test.com&ip=1.1.1.1" \
  -H "Accept: application/json"

JavaScript

javascript

const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://app.bentonow.com/api/v1/experimental/blacklist',
  params: {
    site_uuid: 'ExampleID1234',
    domain: 'test.com',
    ip: '1.1.1.1'
  },
  auth: {
    username: 'publishableKey',
    password: 'secretKey'
  },
  headers: {
    'Accept': 'application/json'
  }
};

axios(config)
  .then((response) => console.log(JSON.stringify(response.data, null, 2)))
  .catch((error) => console.error(error));

Laravel

php

use Bentonow\BentoLaravel\Facades\Bento;
use Bentonow\BentoLaravel\DataTransferObjects\BlacklistStatusData;

$data = new BlacklistStatusData(domain: null, ipAddress: "1.1.1.1");

return Bento::getBlacklistStatus($data)->json();

Python

python

from bento_api import BentoAPI
import os

api = BentoAPI(
  site_uuid=os.getenv('BENTO_SITE_UUID'),
  username=os.getenv('BENTO_PUBLISHABLE_KEY'),
  password=os.getenv('BENTO_SECRET_KEY')
)
blacklist_check = api.check_blacklist(domain="example.com")

Response

Each provider flag is `true` when the domain/IP is listed.

Response body

json

{
  "data": [
    {
      "query": "example.com",
      "description": "If any provider returns true you have a deliverability problem.",
      "results": {
        "just_registered": true,
        "spamhaus": true,
        "nordspam": false,
        "spfbl": false,
        "sorbs": false,
        "abusix": false
      }
    }
  ]
}

POST /v1/experimental/validation

Validate Email

Check an email address against spam heuristics, MX records, and optional context.

Required attributes

email · string: Email address to validate.

Optional attributes

name · string: Contact name for additional heuristics.
user_agent · string: User agent string captured at signup.
ip · string: User IPv4 address. Non–Tier-1 traffic will fail validation.

cURL

bash

curl -L -u publishableKey:secretKey \
  -X POST "https://app.bentonow.com/api/v1/experimental/validation?site_uuid=ExampleID1234" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-raw '{
    "email": "person@example.com",
    "user_agent": "Mozilla/5.0"
  }'

JavaScript

javascript

const axios = require('axios');

let data = {
  email: 'user@example.com',
  ip: '1.1.1.1'
};

let config = {
  method: 'post',
  url: 'https://app.bentonow.com/api/v1/experimental/validation',
  params: { site_uuid: 'ExampleID1234' },
  auth: {
    username: 'publishableKey',
    password: 'secretKey'
  },
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  data: JSON.stringify(data)
};

axios(config)
  .then((response) => console.log(JSON.stringify(response.data, null, 2)))
  .catch((error) => console.error(error));

Response

The API returns a `valid` boolean plus additional scoring metadata.

Response body

json

{
  "valid": false,
  "reasons": ["temporary_bounce", "free_provider"],
  "score": 0.42
}

POST /v1/experimental/jesses_ruleset

Validate Email (Jesse's Ruleset)

Run inbox validation through the stricter Bento rules Jesse maintains for production systems.

Required attributes

email · string: Email address to evaluate.

Optional attributes

block_free_providers · boolean: Reject mail from free-mail domains when `true`.
wiggleroom · boolean: Relax a few opinionated checks when `true`.

cURL

bash

curl -L -u publishableKey:secretKey \
  -X POST "https://app.bentonow.com/api/v1/experimental/jesses_ruleset?site_uuid=ExampleID1234" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-raw '{
    "email": "person@example.com",
    "block_free_providers": true
  }'

This ruleset is intentionally strict—log failures to watch for false positives.

Response

Returns the validation outcome mirroring Bento's internal checks.

Response body

json

{
  "valid": false,
  "reasons": ["free_provider"],
  "block_free_providers": true
}

POST /v1/experimental/content_moderation

Moderate Content

Score short-form text for unsafe content and optionally generate a sanitized version.

Required attributes

content · string: Text you want to moderate.

cURL

bash

curl -L -u publishableKey:secretKey \
  -X POST "https://app.bentonow.com/api/v1/experimental/content_moderation?site_uuid=ExampleID1234" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-raw '{
    "content": "<script>alert('xss')</script>"
  }'

Response

Returns a `valid` flag, a list of reasons, and a safe version of the content.

Response body

json

{
  "valid": false,
  "reasons": ["xss", "script_tag"],
  "safe_original_content": "alert('xss')"
}

POST /v1/experimental/gender

Guess Gender

Approximate a subscriber's gender for personalization using US Census data.

Required attributes

name · string: Full name or first name to evaluate.

cURL

bash

curl -L -u publishableKey:secretKey \
  -X POST "https://app.bentonow.com/api/v1/experimental/gender?site_uuid=ExampleID1234" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-raw '{
    "name": "Alex Johnson"
  }'

Response

Returns the gender guess plus a confidence score.

Response body

json

{
  "gender": "female",
  "confidence": 0.71
}

GET /v1/experimental/geolocation

Geolocate IP Address

Resolve an IPv4 address into geographic metadata for downstream analytics.

Required attributes

ip · string: IPv4 address to geolocate.

cURL

bash

curl -L -u publishableKey:secretKey \
  -X GET "https://app.bentonow.com/api/v1/experimental/geolocation?site_uuid=ExampleID1234&ip=1.1.1.1" \
  -H "Accept: application/json"

IPv6 addresses are not supported.

Response

Returns IP metadata like country, city, and coordinates.

Response body

json

{
  "ip": "1.1.1.1",
  "country_name": "United States",
  "region_name": "California",
  "city_name": "Los Angeles",
  "latitude": 34.0522,
  "longitude": -118.2437
}

Need the original Markdown? Open raw file