From 4bd65db265cb02d67e09e36680c466942a054e22 Mon Sep 17 00:00:00 2001 From: Gabe AO Date: Wed, 14 Oct 2026 17:07:12 +0100 Subject: [PATCH 1/9] feat: add contact-check skill script Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FQdvgNwwnTYBHUGD2dPwFh --- skills/contact-check/check.mjs | 157 +++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 skills/contact-check/check.mjs diff --git a/skills/contact-check/check.mjs b/skills/contact-check/check.mjs new file mode 100644 index 0000000000..099db44eee --- /dev/null +++ b/skills/contact-check/check.mjs @@ -0,0 +1,157 @@ +#!/usr/bin/env node +// contact-check: ask Precleared whether a cold email to one address is allowed. +// +// Usage: +// node check.mjs --email buyer@company.de --source published [--pitch "..."] \ +// [--country DE] [--sender GB|US] [--existing-customer] [--dry-run] +// +// Prints one JSON object. Exit codes, so scripts can gate on the result: +// 0 ok_to_email (send, with a footer that meets footer_text), or the check is switched off +// 2 do not send: consent_needed, blocked or unknown +// 3 check unavailable: network error, daily limit, bad key (try again later) +// 1 usage error +// +// Env: PRECLEARED_SENDER_COUNTRY (GB or US). The check is off until this is set. +// PRECLEARED_API_KEY (optional, free key at https://precleared.dev/get-key). + +import { realpathSync } from "node:fs"; +import { pathToFileURL } from "node:url"; + +const API_URL = process.env.PRECLEARED_API_URL || "https://precleared.dev/api/v1/check"; +const SOURCES = ["published", "bought", "scraped", "given", "unknown"]; +const SENDERS = ["GB", "US"]; +const TIMEOUT_MS = 30000; + +export function parseArgs(argv) { + const opts = { existingCustomer: false, dryRun: false }; + for (let i = 0; i < argv.length; i++) { + const arg = argv[i]; + const next = () => { + const value = argv[++i]; + if (value === undefined || value.startsWith("--")) throw new Error(`Missing value for ${arg}`); + return value; + }; + if (arg === "--email") opts.email = next(); + else if (arg === "--source") opts.source = next(); + else if (arg === "--pitch") opts.pitch = next(); + else if (arg === "--country") opts.country = next(); + else if (arg === "--sender") opts.sender = next(); + else if (arg === "--existing-customer") opts.existingCustomer = true; + else if (arg === "--dry-run") opts.dryRun = true; + else throw new Error(`Unknown option: ${arg}`); + } + return opts; +} + +export function senderFrom(opts, env = process.env) { + return (opts.sender || env.PRECLEARED_SENDER_COUNTRY || "").trim().toUpperCase(); +} + +export function buildPayload(opts, sender) { + const email = (opts.email || "").trim(); + if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) throw new Error("--email must be a full email address"); + const source = (opts.source || "").trim().toLowerCase(); + if (!SOURCES.includes(source)) throw new Error(`--source must be one of: ${SOURCES.join(", ")}`); + if (!SENDERS.includes(sender)) throw new Error("--sender (or PRECLEARED_SENDER_COUNTRY) must be GB or US"); + const payload = { + recipient_email: email, + sender_country: sender, + address_source: source, + existing_customer: Boolean(opts.existingCustomer), + }; + if (opts.pitch) payload.pitch = opts.pitch.trim().slice(0, 200); + if (opts.country) { + const country = opts.country.trim().toUpperCase(); + if (!/^[A-Z]{2}$/.test(country)) throw new Error("--country must be a two-letter code, e.g. DE"); + payload.recipient_country = country; + } + return payload; +} + +export function summarise(status, body) { + if (status === 200 && body && body.verdict) { + const reason = Array.isArray(body.reasons) && body.reasons[0] ? body.reasons[0] : {}; + return { + exitCode: body.verdict === "ok_to_email" ? 0 : 2, + result: { + verdict: body.verdict, + send: body.verdict === "ok_to_email", + rule: reason.text || reason.note || null, + source: reason.source_title || null, + footer_text: body.footer_text || null, + next_step: body.next_step || null, + receipt_id: body.receipt && body.receipt.id ? body.receipt.id : null, + }, + }; + } + const error = body && typeof body === "object" ? body : {}; + return { + exitCode: 3, + result: { + verdict: null, + send: false, + error: error.error || `http_${status}`, + message: error.message || "Precleared could not answer. Do not send; try again later.", + get_key_url: error.get_key_url || null, + }, + }; +} + +async function main() { + let payload; + let opts; + let sender; + try { + opts = parseArgs(process.argv.slice(2)); + sender = senderFrom(opts); + payload = buildPayload(opts, sender || "GB"); + } catch (err) { + console.log(JSON.stringify({ error: "usage", message: err.message })); + return 1; + } + if (!sender) { + console.log( + JSON.stringify({ + skipped: true, + send: true, + message: "contact-check is off. Set PRECLEARED_SENDER_COUNTRY to GB or US in .secrets/env to turn it on.", + }), + ); + return 0; + } + if (opts.dryRun) { + console.log(JSON.stringify({ dry_run: true, url: API_URL, payload })); + return 0; + } + + const headers = { "Content-Type": "application/json", "User-Agent": "b2b-sdr-agent-template" }; + if (process.env.PRECLEARED_API_KEY) headers.Authorization = `Bearer ${process.env.PRECLEARED_API_KEY}`; + + let status = 0; + let body = null; + try { + const res = await fetch(API_URL, { + method: "POST", + headers, + body: JSON.stringify(payload), + signal: AbortSignal.timeout(TIMEOUT_MS), + }); + status = res.status; + body = await res.json().catch(() => null); + } catch (err) { + body = { error: "unreachable", message: `Precleared unreachable: ${err.message}` }; + } + + const { exitCode, result } = summarise(status, body); + console.log(JSON.stringify(result)); + return exitCode; +} + +const invokedDirectly = + Boolean(process.argv[1]) && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href; + +if (invokedDirectly) { + main().then((code) => { + process.exitCode = code; + }); +} From 0b749d19fe5108eda30338be039c14c0d437c812 Mon Sep 17 00:00:00 2001 From: Gabe AO Date: Wed, 14 Oct 2026 17:08:29 +0100 Subject: [PATCH 2/9] feat: add contact-check SKILL.md Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FQdvgNwwnTYBHUGD2dPwFh --- skills/contact-check/SKILL.md | 63 +++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 skills/contact-check/SKILL.md diff --git a/skills/contact-check/SKILL.md b/skills/contact-check/SKILL.md new file mode 100644 index 0000000000..14911d73bb --- /dev/null +++ b/skills/contact-check/SKILL.md @@ -0,0 +1,63 @@ +--- +name: contact-check +description: "Check whether a cold email to one address is allowed (UK, US, Canada, Germany, France) before the first email of a sequence. Returns a verdict, the rule, what the footer must include and a receipt id." +--- + +# contact-check — Cold Email Permission Check + +> Before the Day 1 email to a new address, ask whether a cold email to that buyer is allowed. Germany and France want prior consent in many cases, a UK sole trader counts as an individual, and Canada's CASL depends on whether the address was published. One call per address, before the first email. + +Powered by [Precleared](https://precleared.dev): a per-address verdict under UK PECR and UK GDPR, US CAN-SPAM, Canada's CASL, Germany's UWG and France's rules, with the rule quoted and a signed receipt. Nothing is sent to the buyer. + +**Off by default.** The skill does nothing until `PRECLEARED_SENDER_COUNTRY` is set (see Configuration); until then it exits `0` with `"skipped": true` and the sequence carries on as before. + +## Commands + +| Command | Description | +|---------|-------------| +| `contact:check` | Check one address before the first cold email | + +## Usage + +```bash +node skills/contact-check/check.mjs --email buyer@company.de --source published --pitch "truck spare parts" --country DE +``` + +| Option | Required | Meaning | +|--------|----------|---------| +| `--email` | yes | The buyer's email address | +| `--source` | yes | Where the address came from: `published` (their website, a directory, a trade-show catalogue), `bought` (a purchased list), `scraped` (collected by a tool), `given` (they gave it to you) or `unknown`. It changes the verdict, so never assume `published` | +| `--pitch` | no | What you are offering, in a few words | +| `--country` | no | Buyer's two-letter country code, if known | +| `--sender` | no | `GB` or `US`, where your business is based (overrides `PRECLEARED_SENDER_COUNTRY` for one call) | +| `--existing-customer` | no | The buyer has bought from you before | +| `--dry-run` | no | Print the request without sending it | + +## Reading the result + +The script prints one JSON object and exits with a code you can gate on: + +| Exit | Verdict | What to do | +|------|---------|------------| +| `0` | `ok_to_email`, or the check is off | Send the sequence. The footer must meet `footer_text` (who you are, a postal address, a way to opt out). It describes the requirement; write it in your own words | +| `2` | `consent_needed`, `blocked` or `unknown` | Do not email. Follow `next_step` (for example, get consent through their contact form or a channel the buyer opened) and note it in the CRM | +| `3` | none | The check could not be made (network, daily limit). Do not email yet; try again later | + +Always save `receipt_id` in the CRM notes next to the lead. Anyone can open the receipt at `https://precleared.dev/r/` to see what was checked and why. + +## Configuration + +```bash +# Optional, in .secrets/env +PRECLEARED_SENDER_COUNTRY="GB" # GB or US. Setting this turns the check on +PRECLEARED_API_KEY="" # Optional. Free key at https://precleared.dev/get-key (25 checks/day) +``` + +Without a key, Precleared allows 10 checks a day per server. A free key raises that to 25 a day; paid packs cover more. + +## File Structure +``` +contact-check/ +├── SKILL.md # This file +└── check.mjs # Precleared API call (Node 18+, no dependencies) +``` From 6273552ffa1e3cc86f44cd7343ce98203b59a5a0 Mon Sep 17 00:00:00 2001 From: Gabe AO Date: Wed, 14 Oct 2026 17:09:30 +0100 Subject: [PATCH 3/9] feat: run contact-check before the Day 1 email when enabled Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FQdvgNwwnTYBHUGD2dPwFh --- workspace/AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/workspace/AGENTS.md b/workspace/AGENTS.md index 246481059b..a011e32e93 100644 --- a/workspace/AGENTS.md +++ b/workspace/AGENTS.md @@ -101,6 +101,7 @@ Cold email sequence for leads with email addresses: - **Day 7**: Direct ask (specific product recommendation based on their business) - **Day 14**: Final follow-up (limited-time offer or new product) Rules: +- Before the Day 1 email to a new address, run `contact-check` (see TOOLS.md). It stays off until `PRECLEARED_SENDER_COUNTRY` is set in .secrets/env; once on, it checks buyers in the UK, US, Canada, Germany and France. Send the sequence only if it exits 0, with a footer that meets `footer_text`. Otherwise don't email: follow `next_step` and note it in the CRM. Save any `receipt_id` in the lead's notes - Query Supermemory for company research before composing email - Subject line must be personalized (mention company name or specific need) - Include clear CTA in every email From fb253c3e3edc74a7fe635113ba67df9aec215292 Mon Sep 17 00:00:00 2001 From: Gabe AO Date: Wed, 14 Oct 2026 17:10:13 +0100 Subject: [PATCH 4/9] docs: describe contact-check in TOOLS.md Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FQdvgNwwnTYBHUGD2dPwFh --- workspace/TOOLS.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/workspace/TOOLS.md b/workspace/TOOLS.md index ac670e98cc..8ccdbd32ea 100644 --- a/workspace/TOOLS.md +++ b/workspace/TOOLS.md @@ -155,6 +155,15 @@ gws gmail users messages send --params '{"userId":"me"}' --body '{"raw":"BASE64_ ``` Used for: Cold email sequences, inbox monitoring for replies, formal document delivery. +## Contact Check (Cold Email Permission) +Off until `PRECLEARED_SENDER_COUNTRY` (GB or US) is set in .secrets/env. Once on, run it once per new address before the first cold email to a buyer in the UK, US, Canada, Germany or France: +```bash +node skills/contact-check/check.mjs --email buyer@company.de --source published --pitch "truck spare parts" +``` +`--source` is where the address came from: `published`, `bought`, `scraped`, `given` or `unknown`. Exit code `0` means `ok_to_email` (or the check is switched off); `2` means do not email (follow `next_step`); `3` means the check could not be made, so wait and retry. Save `receipt_id` in the CRM notes. + +Optional `PRECLEARED_API_KEY` in .secrets/env (free key at https://precleared.dev/get-key): 25 checks a day instead of 10. + ## Jina AI (Web Search + Content Extraction) For proactive lead discovery and company research. From e716f4fa9a46db1f88b0b2ddc30cd300739dea50 Mon Sep 17 00:00:00 2001 From: Gabe AO Date: Wed, 14 Oct 2026 17:10:56 +0100 Subject: [PATCH 5/9] docs: add contact-check to the skills table Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FQdvgNwwnTYBHUGD2dPwFh --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 0df85c72a5..b540a4e7b7 100644 --- a/README.md +++ b/README.md @@ -247,6 +247,7 @@ Pre-built capabilities that extend your AI SDR: | **sdr-humanizer** | Rules for natural conversation — pacing, cultural adaptation, anti-patterns. | | **lead-discovery** | AI-driven lead discovery. Web search for potential buyers, ICP evaluation, CRM auto-entry. | | **quotation-generator** | Auto-generate PDF proforma invoices with company letterhead, multi-language support. | +| **contact-check** | Optional. Checks whether a cold email to a new address is allowed (UK, US, Canada, Germany, France) before the first email, with the rule and a receipt. Off until you set `PRECLEARED_SENDER_COUNTRY`. Powered by [Precleared](https://precleared.dev). | | **graphify** | Knowledge graph engine — map product relationships, customer intelligence, and market research into queryable graphs. Powered by [graphify](https://github.com/safishamsi/graphify). | ### Skill Profiles From d2791005d7abbb08fcab6a6a9b9b91304c8dbaa4 Mon Sep 17 00:00:00 2001 From: Gabe AO Date: Wed, 14 Oct 2026 17:11:39 +0100 Subject: [PATCH 6/9] feat: add optional Precleared settings to config.sh.example Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FQdvgNwwnTYBHUGD2dPwFh --- deploy/config.sh.example | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/deploy/config.sh.example b/deploy/config.sh.example index e89594f2d2..e7bbc6500b 100644 --- a/deploy/config.sh.example +++ b/deploy/config.sh.example @@ -80,6 +80,10 @@ CHROMA_COLLECTION="conversation_history" # ─── Jina AI (Web Search + Content Extraction) ────────── JINA_API_KEY="" # Get free key at https://jina.ai/ +# ─── Precleared (Cold Email Permission Check, optional) ── +PRECLEARED_API_KEY="" # Optional. Free key at https://precleared.dev/get-key +PRECLEARED_SENDER_COUNTRY="" # GB or US turns contact-check on; empty keeps it off + # ─── Supermemory (Research Storage) ───────────────────── SUPERMEMORY_API_KEY="" # Get at https://supermemory.ai/ SUPERMEMORY_SPACE="" # Your space name From 2d24d538e776324b35c8eb4cab928d6c41de10b2 Mon Sep 17 00:00:00 2001 From: Gabe AO Date: Wed, 14 Oct 2026 17:12:31 +0100 Subject: [PATCH 7/9] test: validate the contact-check skill Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FQdvgNwwnTYBHUGD2dPwFh --- scripts/validate-template.sh | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/scripts/validate-template.sh b/scripts/validate-template.sh index 196e30f737..c55b24e40c 100755 --- a/scripts/validate-template.sh +++ b/scripts/validate-template.sh @@ -26,6 +26,7 @@ for file in \ workspace/MEMORY.md workspace/HEARTBEAT.md workspace/TOOLS.md \ deploy/config.sh.example deploy/deploy.sh deploy/doctor.sh deploy/generate-config.sh deploy/skill-profiles.sh \ skills/chroma-memory/SKILL.md skills/chroma-memory/chroma.mjs \ + skills/contact-check/SKILL.md skills/contact-check/check.mjs \ product-kb/catalog.json product-kb/scripts/generate-pi.js do require_file "$file" @@ -63,6 +64,16 @@ OPENCLAW_HOME="$TMP_DIR/openclaw" node "$ROOT/skills/chroma-memory/chroma.mjs" s jq -e 'length == 1 and .[0].has_quote == true and .[0].has_commitment == true' "$TMP_DIR/chroma-search.json" >/dev/null pass "Chroma memory smoke test works" +node --check "$ROOT/skills/contact-check/check.mjs" +env -u PRECLEARED_SENDER_COUNTRY node "$ROOT/skills/contact-check/check.mjs" --email buyer@example.de --source published > "$TMP_DIR/contact-check-off.json" +jq -e '.skipped == true and .send == true' "$TMP_DIR/contact-check-off.json" >/dev/null +node "$ROOT/skills/contact-check/check.mjs" --email buyer@example.de --source published --country de --sender GB --dry-run > "$TMP_DIR/contact-check.json" +jq -e '.dry_run == true and .payload.address_source == "published" and .payload.recipient_country == "DE" and .payload.sender_country == "GB"' "$TMP_DIR/contact-check.json" >/dev/null +if node "$ROOT/skills/contact-check/check.mjs" --email buyer@example.de --source guessed --sender GB > /dev/null; then + fail "contact-check accepted an invalid --source" +fi +pass "Contact check skill parses and builds requests" + source "$ROOT/deploy/skill-profiles.sh" skill_list="$(get_skills_for_profile b2b_trade) chromadb" skill_count="$(printf '%s\n' $skill_list | sort -u | wc -l | tr -d ' ')" From c21570fc2e4ffef842e47ecb8c91b9888e85e4fe Mon Sep 17 00:00:00 2001 From: Gabe AO Date: Wed, 14 Oct 2026 17:13:13 +0100 Subject: [PATCH 8/9] docs: changelog entry for contact-check Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FQdvgNwwnTYBHUGD2dPwFh --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index a402f1923e..18b062fe51 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ Changes sourced from upstream (openclaw/openclaw) are labeled with the originati ## [Unreleased] +### Added + +- **contact-check skill**: before the Day 1 cold email to a new address, checks whether that email is allowed under UK PECR, US CAN-SPAM, Canada's CASL, Germany's UWG or France's rules, using [Precleared](https://precleared.dev). Exit codes let scripts gate on the verdict, and the receipt id goes in the CRM notes. Off by default: setting `PRECLEARED_SENDER_COUNTRY` (GB or US) turns it on, and Stage 9 of `AGENTS.md` then runs it before the first email. Node 18+, no dependencies; works without a key (10 checks a day) or with a free key (25 a day). + ## 2026-06-12 — OpenClaw v2026.6.6 upstream sync Upstream: [openclaw/openclaw v2026.6.6](https://github.com/openclaw/openclaw/releases/tag/v2026.6.6) — 77 commits; security hardening, multi-channel delivery stability, Claude Fable 5, and UI performance. From 58fa228d9e5e76707ab6d12448dfd5ade6164120 Mon Sep 17 00:00:00 2001 From: Gabe AO Date: Wed, 14 Oct 2026 20:17:24 +0100 Subject: [PATCH 9/9] fix: treat unexpected Precleared responses as an unavailable check - Only a JSON object with a known verdict counts as an answer; anything else exits 3, and text fields must be strings - Exit 3 now means hold that lead for the next run and carry on with replies and other leads, rather than noting it as do-not-email - Check again if the pitch or where the address came from changes - validate-template.sh checks that unexpected responses count as the check being unavailable Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FQdvgNwwnTYBHUGD2dPwFh --- scripts/validate-template.sh | 15 +++++++++++++++ skills/contact-check/SKILL.md | 4 ++-- skills/contact-check/check.mjs | 31 +++++++++++++++++++------------ workspace/AGENTS.md | 2 +- workspace/TOOLS.md | 4 ++-- 5 files changed, 39 insertions(+), 17 deletions(-) diff --git a/scripts/validate-template.sh b/scripts/validate-template.sh index c55b24e40c..2af4436ab6 100755 --- a/scripts/validate-template.sh +++ b/scripts/validate-template.sh @@ -74,6 +74,21 @@ if node "$ROOT/skills/contact-check/check.mjs" --email buyer@example.de --source fi pass "Contact check skill parses and builds requests" +CONTACT_CHECK="$ROOT/skills/contact-check/check.mjs" node --input-type=module -e ' +import assert from "node:assert/strict"; +import { pathToFileURL } from "node:url"; +const { summarise } = await import(pathToFileURL(process.env.CONTACT_CHECK).href); +for (const body of [[], "ok_to_email", null, { verdict: "maybe" }, { reasons: [] }]) { + assert.equal(summarise(200, body).exitCode, 3); +} +const odd = summarise(200, { verdict: "consent_needed", reasons: { text: "x" }, next_step: 5, receipt: "cc_rcpt_X" }); +assert.equal(odd.exitCode, 2); +assert.deepEqual([odd.result.rule, odd.result.next_step, odd.result.receipt_id], [null, null, null]); +assert.equal(summarise(200, { verdict: "ok_to_email", receipt: { id: "cc_rcpt_X" } }).result.receipt_id, "cc_rcpt_X"); +assert.equal(summarise(429, { error: "daily_limit" }).result.error, "daily_limit"); +' +pass "Contact check treats unexpected responses as unavailable" + source "$ROOT/deploy/skill-profiles.sh" skill_list="$(get_skills_for_profile b2b_trade) chromadb" skill_count="$(printf '%s\n' $skill_list | sort -u | wc -l | tr -d ' ')" diff --git a/skills/contact-check/SKILL.md b/skills/contact-check/SKILL.md index 14911d73bb..fff382db6a 100644 --- a/skills/contact-check/SKILL.md +++ b/skills/contact-check/SKILL.md @@ -5,7 +5,7 @@ description: "Check whether a cold email to one address is allowed (UK, US, Cana # contact-check — Cold Email Permission Check -> Before the Day 1 email to a new address, ask whether a cold email to that buyer is allowed. Germany and France want prior consent in many cases, a UK sole trader counts as an individual, and Canada's CASL depends on whether the address was published. One call per address, before the first email. +> Before the Day 1 email to a new address, ask whether a cold email to that buyer is allowed. Germany and France want prior consent in many cases, a UK sole trader counts as an individual, and Canada's CASL depends on whether the address was published. One call per address, before the first email, and again if the pitch or where you got the address changes. Powered by [Precleared](https://precleared.dev): a per-address verdict under UK PECR and UK GDPR, US CAN-SPAM, Canada's CASL, Germany's UWG and France's rules, with the rule quoted and a signed receipt. Nothing is sent to the buyer. @@ -41,7 +41,7 @@ The script prints one JSON object and exits with a code you can gate on: |------|---------|------------| | `0` | `ok_to_email`, or the check is off | Send the sequence. The footer must meet `footer_text` (who you are, a postal address, a way to opt out). It describes the requirement; write it in your own words | | `2` | `consent_needed`, `blocked` or `unknown` | Do not email. Follow `next_step` (for example, get consent through their contact form or a channel the buyer opened) and note it in the CRM | -| `3` | none | The check could not be made (network, daily limit). Do not email yet; try again later | +| `3` | none | The check could not be made (network, daily limit, an unexpected response). Do not email that lead yet: try again on the next run and carry on with replies and other leads | Always save `receipt_id` in the CRM notes next to the lead. Anyone can open the receipt at `https://precleared.dev/r/` to see what was checked and why. diff --git a/skills/contact-check/check.mjs b/skills/contact-check/check.mjs index 099db44eee..3b4763e3f4 100644 --- a/skills/contact-check/check.mjs +++ b/skills/contact-check/check.mjs @@ -8,7 +8,7 @@ // Prints one JSON object. Exit codes, so scripts can gate on the result: // 0 ok_to_email (send, with a footer that meets footer_text), or the check is switched off // 2 do not send: consent_needed, blocked or unknown -// 3 check unavailable: network error, daily limit, bad key (try again later) +// 3 check unavailable: network error, daily limit, bad key or an unexpected response (try again later) // 1 usage error // // Env: PRECLEARED_SENDER_COUNTRY (GB or US). The check is off until this is set. @@ -20,6 +20,7 @@ import { pathToFileURL } from "node:url"; const API_URL = process.env.PRECLEARED_API_URL || "https://precleared.dev/api/v1/check"; const SOURCES = ["published", "bought", "scraped", "given", "unknown"]; const SENDERS = ["GB", "US"]; +const VERDICTS = ["ok_to_email", "consent_needed", "blocked", "unknown"]; const TIMEOUT_MS = 30000; export function parseArgs(argv) { @@ -68,31 +69,37 @@ export function buildPayload(opts, sender) { return payload; } +const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value); +const text = (value) => (typeof value === "string" && value.trim() ? value.trim() : null); + export function summarise(status, body) { - if (status === 200 && body && body.verdict) { - const reason = Array.isArray(body.reasons) && body.reasons[0] ? body.reasons[0] : {}; + // Only a JSON object with a known verdict counts as an answer. Anything else means the check + // could not be made (exit 3), so a stray response is never read as a verdict. + if (status === 200 && isObject(body) && VERDICTS.includes(body.verdict)) { + const first = Array.isArray(body.reasons) ? body.reasons[0] : null; + const reason = isObject(first) ? first : {}; return { exitCode: body.verdict === "ok_to_email" ? 0 : 2, result: { verdict: body.verdict, send: body.verdict === "ok_to_email", - rule: reason.text || reason.note || null, - source: reason.source_title || null, - footer_text: body.footer_text || null, - next_step: body.next_step || null, - receipt_id: body.receipt && body.receipt.id ? body.receipt.id : null, + rule: text(reason.text) || text(reason.note), + source: text(reason.source_title), + footer_text: text(body.footer_text), + next_step: text(body.next_step), + receipt_id: isObject(body.receipt) ? text(body.receipt.id) : null, }, }; } - const error = body && typeof body === "object" ? body : {}; + const error = isObject(body) ? body : {}; return { exitCode: 3, result: { verdict: null, send: false, - error: error.error || `http_${status}`, - message: error.message || "Precleared could not answer. Do not send; try again later.", - get_key_url: error.get_key_url || null, + error: text(error.error) || (status === 200 ? "unexpected_response" : `http_${status}`), + message: text(error.message) || "Precleared could not answer. Do not send; try again later.", + get_key_url: text(error.get_key_url), }, }; } diff --git a/workspace/AGENTS.md b/workspace/AGENTS.md index a011e32e93..4f5e1fa030 100644 --- a/workspace/AGENTS.md +++ b/workspace/AGENTS.md @@ -101,7 +101,7 @@ Cold email sequence for leads with email addresses: - **Day 7**: Direct ask (specific product recommendation based on their business) - **Day 14**: Final follow-up (limited-time offer or new product) Rules: -- Before the Day 1 email to a new address, run `contact-check` (see TOOLS.md). It stays off until `PRECLEARED_SENDER_COUNTRY` is set in .secrets/env; once on, it checks buyers in the UK, US, Canada, Germany and France. Send the sequence only if it exits 0, with a footer that meets `footer_text`. Otherwise don't email: follow `next_step` and note it in the CRM. Save any `receipt_id` in the lead's notes +- Before the Day 1 email to a new address, run `contact-check` (see TOOLS.md). It stays off until `PRECLEARED_SENDER_COUNTRY` is set in .secrets/env; once on, it checks buyers in the UK, US, Canada, Germany and France. Send the sequence only if it exits 0, with a footer that meets `footer_text`. Exit 2: don't email; follow `next_step` and note it in the CRM. Exit 3 means the check couldn't be made: hold that lead's Day 1 email for the next run and carry on with replies and other leads. Save any `receipt_id` in the lead's notes - Query Supermemory for company research before composing email - Subject line must be personalized (mention company name or specific need) - Include clear CTA in every email diff --git a/workspace/TOOLS.md b/workspace/TOOLS.md index 8ccdbd32ea..95ef31e1af 100644 --- a/workspace/TOOLS.md +++ b/workspace/TOOLS.md @@ -156,11 +156,11 @@ gws gmail users messages send --params '{"userId":"me"}' --body '{"raw":"BASE64_ Used for: Cold email sequences, inbox monitoring for replies, formal document delivery. ## Contact Check (Cold Email Permission) -Off until `PRECLEARED_SENDER_COUNTRY` (GB or US) is set in .secrets/env. Once on, run it once per new address before the first cold email to a buyer in the UK, US, Canada, Germany or France: +Off until `PRECLEARED_SENDER_COUNTRY` (GB or US) is set in .secrets/env. Once on, run it once per new address before the first cold email to a buyer in the UK, US, Canada, Germany or France, and again if the pitch or where you got the address changes: ```bash node skills/contact-check/check.mjs --email buyer@company.de --source published --pitch "truck spare parts" ``` -`--source` is where the address came from: `published`, `bought`, `scraped`, `given` or `unknown`. Exit code `0` means `ok_to_email` (or the check is switched off); `2` means do not email (follow `next_step`); `3` means the check could not be made, so wait and retry. Save `receipt_id` in the CRM notes. +`--source` is where the address came from: `published`, `bought`, `scraped`, `given` or `unknown`. Exit code `0` means `ok_to_email` (or the check is switched off); `2` means do not email (follow `next_step`); `3` means the check could not be made: hold that email for the next run and carry on with other work. Save `receipt_id` in the CRM notes. Optional `PRECLEARED_API_KEY` in .secrets/env (free key at https://precleared.dev/get-key): 25 checks a day instead of 10.