OpenAPI JSON Home Open Console

API Reference

Integrate TrialShield in minutes

Use TrialShield to score signup risk, return policy decisions, and validate recipient deliverability before sending email.

Production base URL

https://trialshield.christchurchdynamics.cloud

Local base URL

http://localhost:8787

OpenAPI schema

/openapi.json

Quickstart

  1. Create an account and get your API key in the dashboard.
  2. Store the key server-side only (never expose in browser code).
  3. Call POST /v1/decision from your backend during signup.
  4. Enforce returned action: allow, challenge, block.

Quick decision request

curl -X POST http://localhost:8787/v1/decision \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "email": "support@mailinator.com",
    "ip": "203.0.113.10",
    "policy": { "challenge_threshold": 55, "block_threshold": 80 }
  }'

Authentication

All protected API endpoints require the x-api-key header.

Required header

x-api-key: YOUR_API_KEY

Public demo endpoint only: POST /api/public/try-risk.

Endpoints

POST /v1/email/check

Analyze one email and return risk factors.

  • email (required)
  • domain_age_days (optional)

POST /v1/signup/score

Score a signup payload with email + behavioral signals.

  • email (required)
  • ip, user_agent, domain_age_days (optional)

POST /v1/decision

Return allow/challenge/block using threshold policy.

  • Same input as /v1/signup/score
  • policy.challenge_threshold (optional)
  • policy.block_threshold (optional)

POST /v1/batch/check

Run email risk checks in bulk.

  • emails array (1-200 required)
  • domain_age_days (optional)

POST /v1/smtp/confirm

Probe MX/SMTP to estimate recipient deliverability.

  • email (required)
  • from_email, timeout_ms, max_mx_hosts (optional)

POST /api/public/try-risk

Public demo risk check (no API key).

  • email (required)

Status codes and errors

Status Meaning
200 Success
400 Invalid JSON or failed input validation
401 Missing/invalid API key or unauthorized session
500 Server-side error (retry with backoff)

Integration examples

Node.js (decision endpoint)

import express from "express";

const app = express();
app.use(express.json());

app.post("/api/signup/decision", async (req, res) => {
  const upstream = await fetch("http://localhost:8787/v1/decision", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": process.env.TRIALSHIELD_API_KEY
    },
    body: JSON.stringify({
      email: req.body.email,
      ip: req.ip,
      user_agent: req.get("user-agent")
    })
  });

  const result = await upstream.json();
  if (!upstream.ok) {
    return res.status(502).json({ error: "TrialShield request failed", details: result });
  }
  return res.json(result);
});

cURL (SMTP confirmation)

curl -X POST http://localhost:8787/v1/smtp/confirm \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "email": "person@example.com",
    "from_email": "verify@yourdomain.com",
    "timeout_ms": 6000,
    "max_mx_hosts": 2
  }'