Docs

Build Precleared into your tool

For people who maintain outbound agents, sequencers and CRMs, and for the coding agents that write their code. One check per new recipient, before the first cold email, answers one question: may this email be sent?

The contract

Check each new address once, before the first cold email. Follow-ups to the same person don't need a new check.
Send only when the verdict is ok_to_email. Hold on consent_needed, blocked and unknown.
If the check can't run, don't send.
Keep the receipt id with the lead, and show your user the next_step for anyone held.

Pick the shape that fits your tool

Your tool can	Use	Send when
Read JSON	`POST https://precleared.dev/api/v1/check`	`verdict` is `ok_to_email`
Read only the status code, or stop when a step fails	`POST https://precleared.dev/api/v1/gate`	The status is 200. 422 means hold
Run a command before each send	`precleared check --stdin`, in the npm package `precleared` from version 0.2.0	The exit code is 0. 2 means hold, 1 means it couldn't check
Call tools over MCP	`contact_check` at `https://precleared.dev/mcp`	`verdict` is `ok_to_email`
Use TypeScript or Python	`npm install precleared` or `pip install precleared`	The verdict is `ok_to_email`

What to send

Field	Notes
`recipient_email`	Required, or `recipient_domain` when you have no address. Gate mode also takes `email`
`sender_country`	Where the sending business is based: GB, US or AE. Default GB
`address_source`	`published`, `bought`, `scraped`, `given` or `unknown`. Default unknown. Never assume published: it changes the verdict
`company_name`, `recipient_name`	Optional. They help find a UK company at Companies House. The name isn't stored
`company_number`	Optional. A UK company number confirms the company
`recipient_country`, `default_recipient_country`	Optional. `recipient_country` always wins. The default is used only when the country can't be worked out
`existing_customer`	Optional. True only if the person has bought from the sender
`pitch`, `pitch_relevant`	Optional. What the email offers, and whether it relates to their job
`suppressed`	Optional. True if the address is on the sender's own do-not-contact list

curl https://precleared.dev/api/v1/check?src=your-tool \
  -H "Authorization: Bearer pc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"recipient_email":"jane@acme.co.uk","sender_country":"GB","address_source":"published"}'

What comes back

Each answer has verdict, confidence, reasons (the rule that decided it, with its source), next_step, footer_text, facts, receipt and usage.

footer_text says what the email must include, usually who you are, a postal address and a way to opt out. It's a requirement, not wording to paste.
next_step is one line on what to do with a held lead. Show it to your user.
receipt.id proves the check. precleared.dev/r/ followed by the id shows it to anyone, and the signature can be verified with the public key at /api/v1/public-key.

Errors

Status	Meaning	What your tool should do
400	A field is wrong	Fix the request. It didn't use a check
401	The key is wrong or revoked	Don't send. Ask your user to check their key
402	The day's checks are used and the key has no credits	Don't send. Show your user the answer's `operator_message`, which links to buying more
429 `daily_limit`	The free daily allowance is used	Don't send. Show `operator_message`, which links to a free key
429 `rate_limited`	Too many checks in a minute (60 by default)	Wait `retry_after` seconds, then try again
500	Precleared failed	Don't send. Try again later

Always pass the API's message on to the person running your tool. A check that stops sending without saying why is a check people switch off.

Keys and allowances

Without a key: 10 checks a day per network over the API, and 100 a day over MCP. With a free key: 100 a day for its first 14 days, then 25 a day. For more, £15 a month keeps 100 a day, or packs add checks that never expire.

Let your users bring their own key, sent as Authorization: Bearer pc_live_... or X-API-Key. Your setup can also get them one: POST https://precleared.dev/api/v1/keys with {"email": "..."} returns a new key once, so save it straight away.

Reuse answers

A definite verdict (ok_to_email, consent_needed or blocked) can be reused for up to 30 days for the same address and the same inputs. Never reuse unknown: a later check may settle it.

Tag your calls

Add ?src=your-tool to the address you call (lowercase letters, digits and dashes), for example https://precleared.dev/api/v1/gate?src=opengtm, and send a User-Agent that names your tool. Checks from your integration are then counted as yours.

Already built in

Harvey, HubSpot and Apollo have it built in. Clay, Make, Zapier, n8n and Amplemarket have recipes, and the AI SDK and LangChain have ready-made tools. The full API reference is in the docs and at /openapi.json.

Decision support with sources, not legal advice.