Online
Bento
View markdown

Utility API

Experimental endpoints for blacklist lookups, email validation, content moderation, gender guessing, and IP geolocation. Use them to screen signups, enrich subscriber data, and check sending reputation.

Looking for the overview of why Bento blocks certain emails? See the Spam API overview. For endpoint details, see the Spam API reference.
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

MethodEndpointName
GETexperimental/blacklist.jsonSearch Blacklists
POSTexperimental/validationValidate Email
POSTexperimental/jesses_rulesetValidate Email (Jesse's Ruleset)
POSTexperimental/content_moderationModerate Content
POSTexperimental/genderGuess Gender
GETexperimental/geolocationGeolocate 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_registeredboolean
    Description

    true / false flag if the domain age is flagged.

  • Name
    spamhausboolean
    Description

    Spamhaus considers mail from this domain or IP to likely contain spam.

  • Name
    nordspamboolean
    Description

    Nordspam considers mail from this domain or IP to likely contain spam.

  • Name
    spfblboolean
    Description

    Spfbl considers mail from this domain or IP to likely contain spam.

  • Name
    sorbsboolean
    Description

    Sorbs considers mail from this domain or IP to likely contain spam.

  • Name
    abusixboolean
    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
    domainstring
    Description

    Please provide just the domain (e.g., google.com) without including the protocol (such as http:// or https://)

  • Name
    ip_addressstring
    Description

    Please provide just the IP address.



Response

Returns a boolean result for each reputation service checked.

Results can be null if all the checks return false.
POST/v1/experimental/validation

Validate Email

The Validate Email Model

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

Properties

  • Name
    validboolean
    Description

    true / false flag if the email address is considered valid.



Validate the submitted email address against spam patterns.

Required Attributes

  • Name
    emailstring
    Description

    Validates an email's domain using MX records.

Optional Attributes

  • Name
    namestring
    Description

    The contact's full name. Heavy bias towards US Census Data. False positives possible.

  • Name
    user_agentstring
    Description

    The user agent as a string.

  • Name
    ipstring
    Description

    The user's IP address. Accepted for compatibility but not currently used in the validation result. See the Spam API reference for current behavior.



Response

Returns a single valid boolean for the submitted email.

POST/v1/experimental/jesses_ruleset

Validate Email (Against Jesse's Ruleset)

The Validate Email (Against Jesse's Ruleset) Model

Validates the email address using the provided information to infer its validity. This is a custom ruleset that Jesse, the Founder of Bento, has created that we use in our own application. It is extremely strict so use with caution. We recommend logging failures to monitor them so you don't get any false positives.



Required Attributes

  • Name
    emailstring
    Description

    Validates an email's domain using MX records.

Optional Attributes

  • Name
    block_free_providersboolean
    Description

    Whether to block free email providers.

  • Name
    wiggleroomboolean
    Description

    Set to true to reduce a few extremely opinionated checks.



Response

Returns a valid flag plus a list of reasons when the email fails a check.

POST/v1/experimental/content_moderation

Moderate Content

The Moderate Content Model

Opinionated content moderation for short text. It flags links, XSS, and other unsafe input, then returns a safe version of the content.

Properties

  • Name
    validboolean
    Description

    true / false flag if the supplied content is considered safe.

  • Name
    reasonsarray
    Description

    string values of the issues found with the supplied content.

  • Name
    safe_original_contentstring
    Description

    A safe version of the supplied content.



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

Required Attributes

  • Name
    contentstring
    Description

    The content you wish to moderate.



Response

Returns a valid flag, the reasons any content was flagged, and a sanitized copy of the original content.

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. The model returns the guessed gender and a confidence score.

Properties

  • Name
    genderstring
    Description

    The guessed gender based on census data.

  • Name
    confidencefloat
    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
    namestring
    Description

    Full name of the subscriber, or first and last name together.



Response

Returns the guessed gender and a confidence score.

The response will always return a confidence level.
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
    requeststring
    Description

    The provided IP address that was geolocated.

  • Name
    ipstring
    Description

    The IP address that was geolocated.

  • Name
    country_code2string
    Description

    Two letter country code.

  • Name
    country_code3string
    Description

    Three letter country code.

  • Name
    country_namestring
    Description

    Full name of the country.

  • Name
    continent_codestring
    Description

    The continent code.

  • Name
    region_namestring
    Description

    The regional name.

  • Name
    city_namestring
    Description

    City name.

  • Name
    postal_codestring
    Description

    Regional postal code.

  • Name
    latitudenumber
    Description

    Latitude for the ip address.

  • Name
    longitudenumber
    Description

    Longitude for the ip address.

  • Name
    dma_codestring
    Description

    DMA code for the ip address.

  • Name
    area_codestring
    Description

    Area code if available for the ip address.

  • Name
    timezonestring
    Description

    Regional UTC time zone.

  • Name
    real_region_namestring
    Description

    The real region name.



This endpoint will geolocate the provided IP address.

Required Attributes

  • Name
    ipstring
    Description

    The IPv4 address you wish to geolocate.



Response

Returns the location data for the IP address, including country, region, city, and coordinates.

The response will contain null values for keys.