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.

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.

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
POST	/v1/experimental/validation	Validate Email
POST	/v1/experimental/jesses_ruleset	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.

POST/v1/experimental/validation

Validate Email

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

Name
email
Type
string
Description
The email address to validate.

Optional Attributes

Name
name
Type
string
Description
The contact name to screen for fake, injected, or obviously spammy input.
Name
ip
Type
string
Description
Accepted for compatibility. Not currently used in the decision returned by this endpoint.
Name
user_agent
Type
string
Description
Accepted for compatibility. Not currently used in the decision returned by this endpoint.

Response Model

Name
valid
Type
boolean
Description
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.

POST/v1/experimental/jesses_ruleset

Validate Email Strict

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.

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

Name
email
Type
string
Description
The email address to validate against the stricter ruleset.

Optional Attributes

Name
block_free_providers
Type
boolean
Description
When true, rejects addresses from free email providers.
Name
wiggleroom
Type
boolean
Description
When true, relaxes some of the more opinionated checks.

Response Model

Name
valid
Type
boolean
Description
The final pass or fail result for the stricter ruleset.
Name
reasons
Type
array[string]
Description
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.