Add it in one prompt

The prompt makes your agent read the codebase first, tell you which layer the check belongs in, and wait for your yes before it edits anything.

Step 1 — pick your tool

Save the prompt as CLAUDE.md in your repo root and run `claude`, or just paste it straight into the prompt.

Save asCLAUDE.md

Step 2 — copy the prompt

Add isitreal disposable-email checking to this codebase.

## Step 1 — Work out where it belongs. Do this before writing any code.

Map how this project creates accounts:

- Find every signup entry point: HTTP route handlers, server actions,
  RPC or GraphQL mutations, auth-provider callbacks, CLI seeds.
- Trace each one to the single place where the user row is actually
  persisted.
- If a service or domain layer sits between the handlers and the
  database, the check belongs THERE — one change covers every entry
  point. Putting it in each handler means the next handler someone adds
  will be missing it.
- If signup goes through a managed auth provider (Clerk, Auth0,
  Supabase, Firebase, NextAuth, Better Auth), the check belongs in the
  before-sign-up hook, callback, or webhook — not after the user
  already exists.
- If there is an existing validation pipeline for the email field,
  add the check as a step in it rather than beside it.

Then tell me, in two or three sentences: which layer you picked, the
exact file, and why. Wait for me to confirm before editing.

## Step 2 — Add a client with fail-open built in.

  POST https://www.isitreal.email/api/v1/check
  Header: Authorization: Bearer $ISITREAL_API_KEY
  Body:   {"email": "user@example.com"}

  Response:
    decision         "ALLOW" | "REVIEW" | "BLOCK"
    allowed          boolean
    reason           human-readable string
    decided_by       which layer decided
    canonical_email  the address with aliases collapsed
    is_alias         whether the address was rewritten
    degraded         present when our model layer was unreachable

  Batch: POST /api/v1/check/batch  {"emails": [...]}  (max 500)

Requirements for the client:
- Read the key from the environment. Never hardcode it, never send it
  to the browser.
- 3 second timeout.
- On timeout, network error, or any non-2xx — including 429 — return
  ALLOW. A verification outage must never block a real customer.
  Log it so it gets noticed.

## Step 3 — Wire it into the layer you picked.

- BLOCK  -> reject the signup, surface `reason` to the user.
- REVIEW -> create the account, but require email verification before
            granting trial credits or quota.
- ALLOW  -> proceed normally.

## Step 4 — Kill alias farming.

Store `canonical_email` alongside the raw address and put the UNIQUE
index on `canonical_email`. a.d.a.r.s.h+signup42@gmail.com and
adarsh@gmail.com are the same inbox; without this they are two free
trials.

## Step 5 — Tests.

Cover: a disposable address is blocked; a real address is allowed; a
plus-alias collides with its canonical form; and a timeout still lets
the signup through.

Step 3 — add your key

.env
ISITREAL_API_KEY=isr_your_key_here

Create one in the dashboard. It is shown once, so put it straight into your secret store. Server-side only — the key must never reach the browser.

Where the check belongs

Getting this wrong is the usual reason a check quietly stops covering half the signups. Find the row that matches your codebase.

You have a service or domain layerPut it in the function that persists the userOne change covers every entry point — REST, server actions, admin tools, seeds. Handlers added next month inherit it for free.
You use Clerk, Auth0, Supabase, Firebase or NextAuthPut it in the before-sign-up hook, callback or webhookThe provider owns account creation. Checking after the fact means the account already exists and you are deleting rather than preventing.
You already validate the email fieldAdd it as a step in that pipelineIt reads as one rule among the rest, and the rejection path, error shape and copy already exist.
It is a single route handler and nothing elsePut it directly before the insertDo not build an abstraction for one call site. Move it down a layer the day a second signup path appears.

Or write it yourself

Copy-paste ready. Both clients fail open, which is the part people leave out and regret.

lib/isitreal.ts
// lib/isitreal.ts
const ENDPOINT = "https://www.isitreal.email/api/v1/check";
const TIMEOUT_MS = 3000;

export type Decision = "ALLOW" | "REVIEW" | "BLOCK";

export interface Verdict {
  decision: Decision;
  allowed: boolean;
  reason: string;
  decided_by: string;
  canonical_email: string | null;
  is_alias: boolean;
  degraded?: true;
}

export async function checkEmail(email: string): Promise<Verdict> {
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);

  try {
    const res = await fetch(ENDPOINT, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.ISITREAL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email }),
      signal: ac.signal,
    });

    if (!res.ok) return failOpen(email, `HTTP ${res.status}`);
    return (await res.json()) as Verdict;
  } catch (err) {
    return failOpen(email, String(err));
  } finally {
    clearTimeout(timer);
  }
}

// An outage on our side must never cost you a real signup.
function failOpen(email: string, why: string): Verdict {
  console.warn("[isitreal] failing open:", why);
  return {
    decision: "ALLOW",
    allowed: true,
    reason: "verification unavailable, allowed",
    decided_by: "client_fail_open",
    canonical_email: email.trim().toLowerCase(),
    is_alias: false,
    degraded: true,
  };
}
using it
// wherever your app actually persists the user
import { checkEmail } from "@/lib/isitreal";

export async function createAccount(email: string, password: string) {
  const verdict = await checkEmail(email);

  if (!verdict.allowed) {
    throw new SignupRejected(verdict.reason);
  }

  return db.user.create({
    data: {
      email,
      // the UNIQUE index goes on this column, not on `email`
      canonicalEmail: verdict.canonical_email ?? email.toLowerCase(),
      passwordHash: await hash(password),
      // REVIEW gets an account, but no free credits until verified
      trialCredits: verdict.decision === "ALLOW" ? 100 : 0,
      requiresVerification: verdict.decision === "REVIEW",
    },
  });
}
isitreal.py
# isitreal.py
import os
import logging
import httpx

ENDPOINT = "https://www.isitreal.email/api/v1/check"
TIMEOUT = 3.0


def check_email(email: str) -> dict:
    try:
        res = httpx.post(
            ENDPOINT,
            headers={"Authorization": f"Bearer {os.environ['ISITREAL_API_KEY']}"},
            json={"email": email},
            timeout=TIMEOUT,
        )
        res.raise_for_status()
        return res.json()
    except Exception as err:
        # An outage on our side must never cost you a real signup.
        logging.warning("[isitreal] failing open: %s", err)
        return {
            "decision": "ALLOW",
            "allowed": True,
            "reason": "verification unavailable, allowed",
            "decided_by": "client_fail_open",
            "canonical_email": email.strip().lower(),
            "is_alias": False,
            "degraded": True,
        }

Full reference in the docs, or as plain text at /llms.txt if you would rather hand it to an agent.