# Utility API

Experimental APIs for specific use cases, with advanced functionality tailored to niche needs.


> Looking for the overview of why Bento blocks certain emails? See the [Spam API overview](/docs/spam-api-overview). For endpoint details, see the [Spam API reference](/docs/spam_api).


> 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                                                                                    |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
|  |      | [Search Blacklists](/docs/utility#search-blacklists)                                    |
|     |          | [Validate Email](/docs/utility#validate-email)                                          |
|     |      | [Validate Email (Jesse's Ruleset)](/docs/utility#validate-email-against-jesses-ruleset) |
|     |  | [Moderate Content](/docs/utility#moderate-content)                                      |
|     |              | [Guess Gender](/docs/utility#guess-gender)                                              |
|  |         | [Geolocate IP Address](/docs/utility#geolocate-ip-address)                              |

---

## Search Blacklists {{ tag: 'GET', label: '/v1/experimental/blacklist.json' }}

<p />
## 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
    
      - **just_registered** (`boolean`): 
        `true` / `false` flag if the domain age is flagged.
      
      - **spamhaus** (`boolean`): 
        [Spamhaus](https://www.spamhaus.org) considers mail from this domain or IP to likely contain spam.
      
      - **nordspam** (`boolean`): 
        [Nordspam](https://www.nordspam.com) considers mail from this domain or IP to likely contain spam.
      
      - **spfbl** (`boolean`): 
        [Spfbl](https://spfbl.net/en/) considers mail from this domain or IP to likely contain spam.
      
      - **sorbs** (`boolean`): 
        [Sorbs](https://www.sorbs.net) considers mail from this domain or IP to likely contain spam.
      
      - **abusix** (`boolean`): 
        [Abusix](https://abusix.com) considers mail from this domain or IP to likely contain spam.
      
    
  

<br/><br/>

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

    
> Only IPv4 addresses are currently supported.


    ### Required Attributes
    
      - **domain** (`string`): 
        Please provide just the domain (e.g., `google.com`) without including the protocol (such as `http://` or `https://`)
      
      - **ip_address** (`string`): 
        Please provide just the IP address.
      
    

  
  
    
  

<br/><br/>

  
    ### Response
    Returns the details of the reputation check.

    
> `Results` can be null if all the checks return `false`.


  
  
   
  


---

## Validate Email {{ tag: 'POST', label: '/v1/experimental/validation' }}

<p />
## The Validate Email Model


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

  
  
    ### Properties
    
      - **valid** (`boolean`): 
        `true` / `false` flag if the email address is considered valid.
      
    
  

<br/><br/>

  
    Validate the submitted email address against spam patterns.

    ### Required Attributes
    
      - **email** (`string`): 
        Validates an email's domain using MX records.
      
    

    ### Optional Attributes
    
      - **name** (`string`): 
        The contact's full name. Heavy bias towards US Census Data. False positives possible.
      
      - **user_agent** (`string`): 
        The user agent as a string.
      
      - **ip** (`string`): 
        The user's IP address. Returns `false` for all countries outside of Tier 1.
      
    

  
  
    
  

<br/><br/>

  
    ### Response
    Returns the details of the validation check.

  
  
    
  


---

## Validate Email (Against Jesse's Ruleset) {{ tag: 'POST', label: '/v1/experimental/jesses_ruleset' }}

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

  

<br/><br/>

  

    ### Required Attributes
    
      - **email** (`string`): 
        Validates an email's domain using MX records.
      
    

    ### Optional Attributes
    
      - **block_free_providers** (`boolean`): 
        Whether to block free email providers.
      
      - **wiggleroom** (`boolean`): 
        Set to true to reduce a few extremely opinionated checks.
      

    

  
  
    
  

<br/><br/>

  
    ### Response
    Returns the details of the validation check.

  
  
    
  


---

## Moderate Content {{ tag: 'POST', label: '/v1/experimental/content_moderation' }}

<p />
## The Moderate Content Model


  
    Opinionated content moderation.

  
  
    ### Properties
    
      - **valid** (`boolean`): 
        `true` / `false` flag if the supplied content is considered safe.
      
      - **reasons** (`array`): 
        `string` values of the issues found with the supplied content.
      
      - **safe_original_content** (`string`): 
        A safe version of the supplied content.
      
    
  

<br/><br/>

  
    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
    
      - **content** (`string`): 
        The content you wish to moderate.
      
    

  
  
    
  

<br/><br/>

  
    ### Response
    Returns results of the content moderation.

  
  
    
  


---

## Guess Gender {{ tag: 'POST', label: '/v1/experimental/gender' }}

<p />
## 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
    
      - **gender** (`string`): 
        The guessed gender based on census data.
      
      - **confidence** (`float`): 
        Confidence level of the guess.
      
    
  

<br/><br/>

  
    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** (`string`): 
        Full name of the subscriber, or first and last name together.
      
    

  
  
    
  

<br/><br/>

  
    ### Response
    The result of the guessed gender.

    
> The response will always return a confidence level.


  
  
    
  


---

## Geolocate IP Address {{ tag: 'GET', label: '/v1/experimental/geolocation' }}

<p />
## The Geolocate IP Address Model


  
    This endpoint attempts to geolocate the provided IP address.

    
> This only works with IPv4 IP addresses.


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

<br/><br/>

  
    This endpoint will geolocate the provided IP address.

    ### Required Attributes
    
      - **ip** (`string`): 
        The IPv4 address you wish to geolocate.
      
    

  
  
    
  

<br/><br/>

  
    ### Response
    The result of the ip geolocation.

    
> The response will contain null values for keys.