Docs · AI SDK

Precleared with the Vercel AI SDK

The precleared npm package gives an AI SDK agent two tools. contact_check says whether a cold or marketing email to an address is allowed before the agent sends it, in the UK, US, Canada, Germany, France, Australia, Ireland and the Netherlands. verify_receipt fetches a signed receipt later. Both work without a key on the free daily allowance.

Install

npm install precleared zod ai

Use it

import { generateText, isStepCount } from 'ai';
import { Precleared } from 'precleared';
import { preclearedTools } from 'precleared/ai-sdk';

const client = new Precleared({ apiKey: process.env.PRECLEARED_API_KEY });

const { text } = await generateText({
  model: 'openai/gpt-5-mini',
  prompt:
    'Can I cold email jane@acme.co.uk about our bookkeeping software? The address was on their website.',
  tools: await preclearedTools(client),
  stopWhen: isStepCount(3),
});

console.log(text);

preclearedTools() returns { contact_check, verify_receipt } built with the AI SDK's tool(), with zod input schemas, so they work with generateText, streamText and ToolLoopAgent. The model string uses the AI Gateway; any AI SDK model works. Leave out apiKey (or PRECLEARED_API_KEY) to use the keyless allowance.

TypeScript with ai 7: if the compiler says the tools are not assignable to ToolSet, update to precleared 0.1.1 or later, or spread them: tools: { ...(await preclearedTools(client)) }.

What the tools return

Compact text the model can act on: the verdict, the rule that decided it with its source, what the footer must include, the next step and the receipt link. Pass { format: 'json' } to preclearedTools() for objects instead. API errors such as the daily limit come back as text too, with the link to fix them, so the agent can tell the person instead of crashing.

Verdicts

ok_to_emailSend, with a footer that meets footer_text (it describes the requirement, it isn't wording to paste).

consent_neededDo not send. Follow next_step.

blockedDo not send.

unknownA fact could not be established. Treat it as consent_needed unless you can add the missing fact (such as company_number or recipient_country) and check again.

Keys and limits

Without a key: 10 checks a day per network. A free key from /get-key gives 25 a day. After that, packs: £9 for 300 checks (a key's first purchase) or £39 for 2,000. 60 checks a minute per key.

Links: the npm package, the API reference and Precleared with LangChain and LangGraph.

Decision support with sources, not legal advice.

Back to the docs