Decision Endpoint - Documentation

Use the Decision API to evaluate a Gate in real time.

Endpoint

POST /v0/gates/{gate_id}/decisions

Authentication

Include your API key in the Authorization header:

Authorization: Bearer <YOUR_API_KEY>

Request body

Either email or domain is required. If both are provided it will return 400 both_email_and_domain_provided. You can optionally include an ip field for additional IP-based intelligence.

{
  "email": "[email protected]",
  "ip": "1.1.1.1" // optional
}

{
  "domain": "example.com",
  "ip": "1.1.1.1" // optional
}

Example response

{
  "input": {
    "email": "[email protected]",
    "ip": "1.1.1.1"
  },
  "decision": {
    "action": "block",
    "matched_rule": {
      "id": "01k1hxqrn2f7xfreq20y0p012d",
      "name": "Block domains with no MX records",
      "message": "This domain is invalid."
    }
  },
  "signals": {
    "email": {
      "address": "[email protected]",
      "normalized": "[email protected]",
      "domain": "example.com",
      "local_part": "user",
      "local_part_length": 5,
      "subaddress": null,
      "disposable": false,
      "role_account": true
    },
    "domain": {
      "name": "example.com",
      "tld": "com",
      "sld": "example",
      "subdomain": null,
      "age_days": 10948,
      "mx": false,
      "mx_records": [],
      "disposable": false,
      "public_domain": false,
      "relay_domain": false,
      "spam": false,
      "blocklisted": false
    },
    "ip": {
      "address": "1.1.1.1",
      "abuse": {
        "detected": false
      },
      "anonymity": {
        "proxy": {
          "detected": false
        },
        "relay": {
          "detected": false
        },
        "tor": {
          "detected": false
        },
        "vpn": {
          "detected": false
        }
      },
      "geo": {
        "city": "Hong Kong",
        "country": "Hong Kong",
        "country_code": "HK",
        "continent": "Asia",
        "continent_code": "AS"
      },
      "hosting": {
        "detected": true
      },
      "network": {
        "asn": 	13335,
        "aso": "Cloudflare, Inc.",
        "domain": "cloudflare.com",
        "type": "hosting"
      }
    }
  },
  "meta": {
    "version": "0.1",
    "request_id": "01K1SKM0ZDCEEES5QA9N3M5EPX",
    "duration_ms": 52.62,
    "created_at": "2025-08-04T03:57:18+00:00"
  }
}

Error responses

400 missing_input: Neither email nor domain provided
400 invalid_email: The email format is invalid
400 invalid_domain: The domain format is invalid
401 unauthorized: Invalid or missing API key
403 pro_only: Your account is not a Pro plan customer
404 gate_not_found: Unknown gate_id
429 rate_limit_exceeded: Too many requests