Email Intelligence

Score any email before it signs up. One POST /v1/email returns a single calibrated risk score plus the underlying signals — disposable status, mail provider, MX deliverability, SPF/DMARC posture, DNSBL hits, domain age, and TLD reputation — for any email or domain.

Signup and checkout forms get flooded with throwaway and undeliverable addresses, and a naive regex passes every one of them. By the time a bounce or chargeback tells you the email was junk, the fake account or order already exists. Email Intelligence resolves the email to a domain-level reputation and hands you the booleans to allow, flag, or block — before you create the account.

When to use it

Call /v1/email at the point of submission — signup, checkout, lead capture, waitlist — whenever an email is the thing you don’t want to be fake. It’s a server-side reputation lookup, so you call it with a secret key from your backend, read the result, and gate on it before you write the record.

It is not a verification email and not an SMTP probe. It checks the domain — disposable status, MX/A-record deliverability, DNSBL listings, and RDAP domain age — without sending mail or touching the recipient’s mail server, so it never tips off the user or risks deliverability damage. Confirming a specific mailbox exists still requires your own double opt-in flow.

How it works

1. POST the email or domain

   Send POST /v1/email with a Bearer API key and a JSON body of {"email": "..."}. You can pass a full address (user@domain.com) or just the bare domain (domain.com). Reputation is keyed on the registrable domain, so mail hosted on a subdomain inherits the parent — treasurer@i.gs.com scores against gs.com.

2. FormShield resolves the reputation

   FormShield combines mailbox signals (role address, free provider, local-part patterns) with domain signals — disposable status, mail-provider class, MX deliverability, SPF/DMARC posture, DNSBL listings, domain age, TLD reputation, and popularity — into one score. Domain-level checks are cached for 30 days, so repeat lookups on the same domain return instantly.

3. Gate on the signal

   The response returns a normalized risk in [0,1], a coarse subverdict (clean / suspicious / malicious / unknown), a recommended action (allow / review / step_up / block), and the individual signals. Gate on action or risk for a single decision, or read the booleans (disposable, deliverable, blacklisted) for precise control — no further round trips.

Quickstart

Send a single request with the submitted address. Replace fs_live_xxx with your API key.

curl -X POST https://api.formshield.dev/v1/email \
  -H "Authorization: Bearer fs_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "newuser@mailinator.com"}'

A bare domain works too — drop the local part and pass {"email": "mailinator.com"} to get the same domain-level reputation.

The response is wrapped in the standard envelope. The signal block holds the reputation; data.cached tells you whether it came from the 30-day cache.

{
  "version": "1",
  "data": {
    "signal": {
      "risk": 0.785,
      "subverdict": "malicious",
      "action": "block",
      "evaluated": true,
      "flags": ["email_disposable"],
      "email": "newuser@mailinator.com",
      "domain": "mailinator.com",
      "registrable_domain": "mailinator.com",
      "role_account": false,
      "free_provider": false,
      "alias": false,
      "gibberish_score": 0.08,
      "disposable": true,
      "deliverable": true,
      "blacklisted": false,
      "blacklists": null,
      "domain_age_days": 8423,
      "new_domain": false,
      "mx_provider": null,
      "mx_tier": "unknown",
      "spf": "hardfail",
      "dmarc_policy": "reject",
      "tld_tier": "neutral",
      "domain_rank": null
    },
    "cached": false
  },
  "error": null,
  "metadata": {
    "request_id": "req_a1b2c3d4e5f6",
    "processing_time_ms": 412
  }
}

Gate on signal.action (or signal.risk / signal.subverdict) for a single allow / review / step-up / block decision, or read signal.disposable, signal.deliverable, and signal.blacklisted directly for precise control.

Signals

The signal block carries one normalized risk, a coarse subverdict, and the underlying checks as individual fields. Read the booleans for precise control, or the risk/subverdict for a single verdict.

Common questions

Next steps