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.
CLAUDE.mdStep 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
ISITREAL_API_KEY=isr_your_key_hereCreate 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.
Or write it yourself
Copy-paste ready. Both clients fail open, which is the part people leave out and regret.
// 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,
};
}// 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
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.