# Spam API

The Spam API helps you decide whether a signup looks real before you accept it. It is designed for forms, gated content, lead capture, and any flow where you want a fast `valid` or `invalid` answer for an email address. This page covers the endpoints, request shape, and response behavior you can wire directly into a signup flow.


> Want the higher-level explanation of why addresses get blocked? See the [Spam API overview](/docs/spam-api-overview).


> The standard validation endpoint is intentionally conservative. If Bento cannot complete a DNS-based check quickly enough, it returns `valid: true` rather than blocking a legitimate signup.


> ⚠️ **Warning**
> This API is opinionated. It catches obvious bad signups well, but you should still log results and monitor rejects if you use it in a hard-blocking signup flow.


## Available Endpoints

| Method                                                   | Endpoint                                                                             | Name                                                            |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
|  |      | [Validate Email](/docs/spam_api#validate-email)                 |
|  |  | [Validate Email (Strict)](/docs/spam_api#validate-email-strict) |

---

## What The Standard Endpoint Checks

The `validation` endpoint uses Bento's internal spam checker and firewall to reject common bad signups, including:

- malformed or non-resolvable email addresses
- disposable inboxes and many temporary mail providers
- common domain typos like misspelled `gmail.com`-style domains
- synthetic mailboxes such as `test`, `demo`, or `staging`
- role or abuse-focused inboxes like `abuse@`, `postmaster@`, or `noreply@`
- suspicious names containing digits, HTML, link injection, crypto spam, XSS, or random-string patterns

It is tuned to be useful at signup time, not to be a perfect compliance-grade verifier. For the higher-level reasoning behind these checks, see the [Spam API overview](/docs/spam-api-overview).

---

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


  
    Returns a single `valid` boolean for the submitted signup data.

    
> The current implementation evaluates `email` and `name`. `ip` and `user_agent` are accepted by the API surface but are not currently used to change the result.


    ### Required Attributes
    
      - **email** (`string`): 
        The email address to validate.
      
    

    ### Optional Attributes
    
      - **name** (`string`): 
        The contact name to screen for fake, injected, or obviously spammy input.
      
      - **ip** (`string`): 
        Accepted for compatibility. Not currently used in the decision returned by this endpoint.
      
      - **user_agent** (`string`): 
        Accepted for compatibility. Not currently used in the decision returned by this endpoint.
      
    

  
  
    
  


<br />
<br />


  
    ### Response Model
    
      - **valid** (`boolean`): 
        `true` when the signup passes Bento's standard validation checks, `false` when it matches a blocked pattern.
      
    

    
> If Bento hits a timeout while checking DNS-backed email validity, the endpoint returns `valid: true` to avoid rejecting a real user because of a slow upstream lookup.


  
  
    
  


---

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


  
    This is Bento's stricter internal ruleset. It is more opinionated than the standard endpoint and returns both a `valid` flag and a list of `reasons`.

    
> 🚨 **Important**
> Use this endpoint carefully in production signup flows. It is intentionally strict and more likely to produce false positives than the standard `validation` endpoint.


    ### Required Attributes
    
      - **email** (`string`): 
        The email address to validate against the stricter ruleset.
      
    

    ### Optional Attributes
    
      - **block_free_providers** (`boolean`): 
        When `true`, rejects addresses from free email providers.
      
      - **wiggleroom** (`boolean`): 
        When `true`, relaxes some of the more opinionated checks.
      
    

  
  
    
  


<br />
<br />


  
    ### Response Model
    
      - **valid** (`boolean`): 
        The final pass or fail result for the stricter ruleset.
      
      - **reasons** (`array[string]`): 
        Human-readable reasons explaining why the address was rejected.
      
    
  
  
    
  


---

## Recommended Usage

- use `validation` inline on signup forms where you want a safer default
- use `jesses_ruleset` for internal review flows, lead scoring, or manual triage
- store the result alongside the submission so you can audit rejects later
- if you hard-block on failures, offer a fallback path for legitimate users to contact you

## Need Help With A False Positive

If a real signup is getting blocked, log the payload you submitted and reach out to `support@bentonow.com` with a sample. Include whether you used `validation` or `jesses_ruleset` so the team can review the result faster.