Verify an email

POSThttps://trueuser.dev/api/v1/verify

Submits a single email for verification. Returns a verdict computed from your custom rules over the underlying detection signals, plus reasoning. Default mode can use AI and recent signup context; latency varies. Local mode skips the AI call.

Request body

stringrequired

The email address to check, up to 254 characters. Format is assessed as a signal; a successful HTTP response does not mean the address is valid.

username

string

The username the customer chose at signup. Helps the model spot collisions across distinct emails (a strong batch-attack signal).

string

Optional client IP from your trusted server/proxy context. It can help assess recent registration patterns; it is not a dedicated IP reputation lookup.

user_agent

string

Optional client User-Agent for verification context. Send only user data appropriate for your privacy policy.

local_mode

boolean

When true, evaluate the email against your rules using only local signals (format, disposable list, role/alias/relay, suspicious-pattern heuristic) — no AI call. Faster and free of credit cost, but may miss cases that only the model would catch (novel disposable providers, batch-cluster patterns). Defaults to false.

Response

verdict

enum

One of allow, review, or block — derived from your account's verdict rule applied to the signals below. Edit the rule at /dashboard/rules.

signals

object

Detection booleans and scores: format_valid, disposable, public_domain, relay_domain, alias, role_account, spam, suspicious_pattern, batch_cluster.

reasoning

string

One short sentence summarizing the strongest signals.

latency_ms

number

Server-side latency for this verification.

Errors

400invalid_json / missing_email / invalid_emailBody must be JSON with an email of at most 254 characters. Invalid format can return HTTP 200 with format_valid: false and a rule-based verdict.

401unauthorizedProvide a valid Bearer API key or an authenticated session.

Other non-2xxunavailableHandle unexpected errors and timeouts. Keep costly benefits pending; do not assume a retry is free or idempotent.

Integrate safely

Keep the API key server-side. Validate responses and set a timeout. A failed request should leave costly trial benefits pending, with a real retry or review path. An AI failure can return local signals with HTTP 200; there is no structured degraded flag. An allow verdict does not prove identity or inbox ownership.

Persist eligibility and grant credits atomically with a unique grant key. Use a durable job queue for background checks. Read the Next.js guide and download the helper →

Build with your coding agent

Copy a prompt. Add signup protection.

Paste this into Claude Code, Codex, Cursor, or your preferred coding agent in your project. It covers the API contract, server-side secrets, failure handling, and trial-credit safeguards.

TrueUser integration prompt

Integrate TrueUser signup risk checks into this project. Inspect the existing framework, authentication flow, trial-credit ledger, tests, and project instructions first. Follow the project's conventions and implement the integration, not just a plan.

Reference: https://trueuser.dev/docs
Next.js guide: https://trueuser.dev/blog/nextjs-signup-abuse-protection

API contract:
- From the server only, POST https://trueuser.dev/api/v1/verify with Authorization: Bearer <TRUEUSER_API_KEY> and Content-Type: application/json.
- JSON body: email (required string, max 254 characters); optional username, ip, user_agent, and local_mode (boolean, defaults to false). Only send additional user data when needed and permitted by our privacy policy. Get IP from trusted server/proxy context, not a user-provided field.
- A successful response has email, verdict (allow | review | block), signals, reasoning, and latency_ms. Signals: format_valid, disposable, public_domain, relay_domain, alias, role_account, spam (booleans); suspicious_pattern and batch_cluster (numbers from 0 to 1).
- local_mode: true uses local checks without an AI call or credit charge; batch_cluster is 0. Default mode can use AI and recent signup context. AI failures can fall back to local signals with HTTP 200; there is no structured degraded flag. Do not treat an allow verdict as proof of identity, inbox ownership, or absence of abuse.
- HTTP 400 can report invalid_json, missing_email, or invalid_email (too long); 401 reports unauthorized. Invalid email format can instead return HTTP 200 with format_valid: false and a policy verdict. Handle other non-2xx responses defensively. No documented idempotency key, Retry-After, or request-id guarantee.

Implementation requirements:
1. Store TRUEUSER_API_KEY as a server-only environment variable. Add a placeholder to the project's env example and setup docs. Never use NEXT_PUBLIC_, put the key in browser code, commit a real key, or print it in logs.
2. Call TrueUser from the trusted signup/trial-eligibility path before issuing expensive benefits. Validate the email and the response at runtime. Use a bounded, configurable timeout; do not retry automatically in the signup request. Treat timeout, network/HTTP errors, and malformed responses as an application-owned pending/unavailable outcome, not allow.
3. Map allow to the normal eligibility flow (including existing email confirmation); review to a pending review or step-up flow; block to withheld trial benefits with a neutral message and a recovery/contact path. Pending/unavailable must withhold costly benefits and provide a real retry or review route. Keep authentication and abuse policy separate; do not lock existing users out just because a risk check failed.
4. Enforce the decision on the backend. Persist eligibility and grant credits atomically/idempotently with a database transaction and unique grant key appropriate to our account model. Repeated or concurrent signup callbacks must not grant credits twice. Do not equate email aliases, shared IPs, or privacy relays with fraud. Do not invent identity/device matching.
5. Minimize logging: record verdict/status and necessary diagnostic codes, not API keys, full response reasoning, or raw email/IP in analytics. Keep existing rate limits and CSRF/auth protections.
6. Add focused tests for allow/review/block, invalid input, 401/5xx, timeout, malformed response, and repeated/concurrent credit grants. Mock TrueUser; do not use live customer data or paid calls in tests. Run the relevant checks and report exactly what passed and what could not run.

Finish with changed files, environment setup, the configured timeout/failure policy, and any remaining deployment steps. If a durable ledger or review workflow does not exist, explain the missing dependency and keep trial benefits withheld rather than inventing a working integration.

Read the Next.js guide →

Add your real API key to your server environment after reviewing the generated changes.

Request · cURLexample

curl https://trueuser.dev/api/v1/verify \
  -H "Authorization: Bearer $TRUEUSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email":    "[email protected]",
    "username": "alex_42",
    "ip":       "203.0.113.42"
  }'

Illustrative response · 200 OKexample

{
  "email": "[email protected]",
  "verdict": "block",
  "signals": {
    "format_valid":  true,
    "disposable":    true,
    "public_domain": false,
    "relay_domain":  false,
    "alias":         false,
    "role_account":  false,
    "spam":          false,
    "suspicious_pattern": 0.84,
    "batch_cluster": 0.91
  },
  "reasoning":  "Disposable provider with batch-shaped local part.",
  "latency_ms": 68
}

Try TrueUser

Free domain checker

The free tool checks blocklist membership. Sign in to try the full verification API.