Decision API

POST /api/assess is Mailsurity's decision engine: instead of a plain disposable/legitimate boolean, it returns a 0-100 risk score, a paired confidence score, and a resolved ALLOW / VERIFY / BLOCK decision, so you branch directly on a decision the engine already made instead of writing your own thresholds around a boolean.

It runs on the same detection cascade as /api/check-email: curated allow/deny lists, a global disposable-domains list, a verdict cache, and live heuristics with an AI classifier for borderline cases, plus additional signals (domain age, role-account detection, network reputation) folded into a single score.

Same auth and request shape as /api/check-email: bearer token, one JSON field. Pick your language:

curl -X POST https://mailsurity.com/api/assess \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "abc@temporary-domain.example"}'

Evaluates a single email address and returns a full risk assessment. Costs one credit per successful call, same as /api/check-email.

Headers

Body parameters

{ "email": "abc@temporary-domain.example" }

The score maps to a decision through two bands, evaluated on top of risk_score:

These 30/70 thresholds are overridable per team from the dashboard (Settings → Decision Engine), and further overridable by your own field → operator → value → action rules (first match wins, evaluated before the threshold bands). When a rule fires, applied_rule in the response names it.

Always present, with null/false values rather than omitted keys when a signal couldn't be resolved (a timeout, an unsupported TLD, etc.) — never a guess.

Beyond the default 30/70 bands, two team-level overrides layer on top of the same underlying score, without changing risk_score itself:

• Thresholds — raise or lower the ALLOW/VERIFY and VERIFY/BLOCK cut points for your team from the dashboard.
• Decision rules — condition → action overrides (e.g. “always BLOCK when domain_age_days < 2”), evaluated priority-ascending, first match wins. A matched rule is reported back in applied_rule.

Identical to /api/check-email: standard HTTP status codes, a JSON body of the shape { "error": "message" }, and 1 credit per successful call.

Closes the calibration loop: report the actual outcome of a signup (fraud or legitimate) so scoring improves against real results over time. This isn't a rating of /api/assess's decision — it's ground truth about the identity, and it costs 0 credits since the label matters more than the credit.

curl -X POST https://mailsurity.com/api/feedback \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"check_id": "0f3c1e6a-1234-4a11-9c2e-8b6f2a5d9e10", "outcome": "fraud"}'

Or, without a check_id on hand:

{ "email": "user@example.com", "outcome": "legitimate", "note": "optional, max 500 chars" }

Exactly one of check_id or email must be present. A successful call returns:

{ "recorded": true, "id": 123 }

• Branch on decision, not risk_score directly — the threshold and rule logic already accounts for your team's tuning, so re-deriving your own cutoffs from the raw score just duplicates that work.
• Treat VERIFY as a real third state, not a soft ALLOW or BLOCK: route it to step-up verification or a review queue instead of collapsing it into one of the other two.
• Store check_id alongside the signup so you can call /api/feedback later once you know the real outcome — that's what calibrates future scores.
• Fail open: on a timeout, network error, or unexpected status, default to ALLOW rather than blocking a real user because the API was unreachable.

If a plain disposable/legitimate boolean is all your integration needs, /api/check-email is the simpler contract — same cascade, same cost, smaller response. It isn't going anywhere; see the full reference.