ShieldMX API

{
  "valid_syntax": true,
  "email": "someone@relay.firefox.com",
  "domain": "relay.firefox.com",
  "disposable": false,
  "alias": true,
  "matched_domain": "relay.firefox.com",
  "mx_valid": true,
  "recommendation": "REVIEW",
  "reason": "privacy_alias",
  "risk_score": 50,
  "suggestion": null,
  "mode": "live",
  "evaluated_at": 1792841446
}

Run a check to see the verdict here.

Authorization: Bearer smx_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

{
  "emails": [
    "a@relay.firefox.com",
    "b@mailinator.com",
    "c@example.com"
  ]
}

{
  "results": [
    { "email": "a@relay.firefox.com", "recommendation": "REVIEW", "reason": "privacy_alias", "...": "..." },
    { "email": "b@mailinator.com", "recommendation": "REJECT", "reason": "disposable_domain", "...": "..." },
    { "valid_syntax": false, "email": "c@", "error": { "code": "INVALID_SYNTAX", "message": "..." } }
  ],
  "summary": {
    "submitted": 3,
    "checked": 2,
    "rejected": 1,
    "reviewed": 1,
    "allowed": 0,
    "invalid": 1
  }
}

{
  "error": {
    "code": "INVALID_SYNTAX",
    "message": "The provided value fails standardized RFC 5322 parsing evaluations."
  }
}

// app/api/signup/route.ts
const BASE = "https://shieldmx-core-api.slotboard-v.workers.dev";

export async function POST(req: Request) {
  const { email } = await req.json();

  let verdict;
  try {
    const res = await fetch(BASE + "/v1/verify", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.SHIELDMX_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email }),
      signal: AbortSignal.timeout(3000),
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    verdict = await res.json();
  } catch {
    // Fail closed: no account is created while the check cannot run.
    return Response.json({ error: "We could not verify your email right now. Please try again." }, { status: 503 });
  }

  if (verdict.recommendation === "REJECT") {
    console.log("signup rejected", verdict.reason, verdict.domain);
    return Response.json({ error: "We couldn't create an account with that address." }, { status: 422 });
  }

  // REVIEW: create the account, but start the trial only after a card or captcha.
  return Response.json({ ok: true, review: verdict.recommendation === "REVIEW" }, { status: 201 });
}

const BASE = "https://shieldmx-core-api.slotboard-v.workers.dev";

app.post("/signup", express.json(), async (req, res) => {
  let verdict;
  try {
    const r = await fetch(BASE + "/v1/verify", {
      method: "POST",
      headers: {
        Authorization: "Bearer " + process.env.SHIELDMX_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email: req.body.email }),
      signal: AbortSignal.timeout(3000),
    });
    if (!r.ok) throw new Error("HTTP " + r.status);
    verdict = await r.json();
  } catch {
    return res.status(503).json({ error: "We could not verify your email right now. Please try again." });
  }

  if (verdict.recommendation === "REJECT") {
    console.log("signup rejected", verdict.reason, verdict.domain);
    return res.status(422).json({ error: "We couldn't create an account with that address." });
  }

  // REVIEW: create the account, but start the trial only after a card or captcha.
  res.status(201).json({ ok: true, review: verdict.recommendation === "REVIEW" });
});

// src/index.ts, deployed with: wrangler secret put SHIELDMX_API_KEY
export interface Env {
  SHIELDMX_API_KEY: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { email } = (await request.json()) as { email: string };

    const res = await fetch("https://shieldmx-core-api.slotboard-v.workers.dev/v1/verify", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${env.SHIELDMX_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email }),
      signal: AbortSignal.timeout(3000),
    });
    if (!res.ok) {
      return Response.json({ error: "We could not verify your email right now." }, { status: 503 });
    }

    const verdict = (await res.json()) as { recommendation: string; reason: string };
    if (verdict.recommendation === "REJECT") {
      return Response.json({ error: "We couldn't create an account with that address." }, { status: 422 });
    }
    return Response.json({ ok: true, review: verdict.recommendation === "REVIEW" }, { status: 201 });
  },
};

// supabase/functions/signup/index.ts
// Deploy with: supabase secrets set SHIELDMX_API_KEY=smx_live_...
Deno.serve(async (req) => {
  const { email } = await req.json();

  const res = await fetch("https://shieldmx-core-api.slotboard-v.workers.dev/v1/verify", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${Deno.env.get("SHIELDMX_API_KEY")}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email }),
    signal: AbortSignal.timeout(3000),
  });
  if (!res.ok) {
    return Response.json({ error: "We could not verify your email right now." }, { status: 503 });
  }

  const verdict = await res.json();
  if (verdict.recommendation === "REJECT") {
    return Response.json({ error: "We couldn't create an account with that address." }, { status: 422 });
  }
  return Response.json({ ok: true, review: verdict.recommendation === "REVIEW" }, { status: 201 });
});

# pip install fastapi httpx
import os
import httpx
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

BASE = "https://shieldmx-core-api.slotboard-v.workers.dev"
app = FastAPI()

class Signup(BaseModel):
    email: str

@app.post("/signup", status_code=201)
async def signup(body: Signup):
    try:
        async with httpx.AsyncClient(timeout=3) as client:
            r = await client.post(
                f"{BASE}/v1/verify",
                headers={"Authorization": f"Bearer {os.environ['SHIELDMX_API_KEY']}"},
                json={"email": body.email},
            )
            r.raise_for_status()
            verdict = r.json()
    except httpx.HTTPError:
        raise HTTPException(503, "We could not verify your email right now. Please try again.")

    if verdict["recommendation"] == "REJECT":
        raise HTTPException(422, "We couldn't create an account with that address.")
    # REVIEW: create the account, but start the trial only after a card or captcha.
    return {"ok": True, "review": verdict["recommendation"] == "REVIEW"}