Outreach toolkit

The outreach toolkit is an internal operator workflow that turns first-party usage evidence into targeted, personalized conversion emails for domains that are clearly over the free allowance. It is deliberately not a bulk marketing tool — it only targets domains with proven, over-threshold Vumbnail usage.

Behavior

The operator runs a short script-driven pipeline:

1. Prepare local inputs (gitignored): an entry-tier.csv of domains already over threshold plus contacts, and a sites-meta.json of per-domain overrides (industry, contact role, send priority, notes).
2. Fetch usage evidence (bun outreach:usage) — exports referrer, direct/ no-referrer, user-agent, and IP summaries from production analytics as NDJSON.
3. Build sequences (bun outreach:build-sequences) — generates a personalized three-part email sequence per domain into docs/sites/<domain>.md, merging evidence + templates + the policy thresholds.
4. Configure sender (gitignored sender-config.json) — from/reply-to and a compliant List-Unsubscribe header.
5. Export & validate — bun outreach:export-mail-merge produces a Thunderbird-compatible mail-merge.csv; bun outreach:validate-mail-merge gate-checks it before any send.

The actual send is done by a human through Thunderbird Mail Merge — the toolkit prepares and validates, it does not send.

The threshold

Targeting is gated on the shared policy numbers: free allowance 50,000/month, 20% grace, so outreach only fires at 60,000/month and above. These come from @repo/core/vumbnail-pricing.ts so the toolkit, the watermark cohort, and the docs can’t drift.

Inputs & outputs

Inputs: entry-tier.csv, sites-meta.json, production usage exports, templates in docs/templates/, sender-config.json, suppression-list.json.

Outputs: per-domain sequence markdown, a validated mail-merge.csv, and a pass/fail validation report. No outreach artifacts or contact data are committed to git.

States & edge cases

• Under threshold — a domain below 60,000/month is not eligible; the toolkit refuses to target it.
• Suppressed recipient — validation fails if a recipient’s email or domain is on suppression-list.json.
• Duplicate / missing recipient — validation fails on duplicate addresses or a row missing an email or domain.
• Missing compliance headers — validation fails if sender headers or List-Unsubscribe aren’t populated.
• Pilot batches — a --max-send-priority flag restricts a run to the highest- priority contacts for a small first send.

Data shape

type CsvEntryRow = Record<string, string> // domain + contact columns from entry-tier.csv

type SiteMeta = {
  domain: string
  contact_name?: string
  contact_email?: string
  contact_role?: string
  industry?: string
  send_priority?: number   // lower = earlier
  notes?: string
}

type MailMergeRow = {
  to: string
  contact_name: string
  domain: string
  monthly: number                        // measured monthly requests
  monthly_requests_over_threshold: number
  free_tier_monthly_requests: 50000
  outreach_monthly_threshold: 60000
  from_email: string
  from_name: string
  list_unsubscribe: string
  part_1_subject: string; part_1_body: string
  part_2_subject: string; part_2_body: string
  part_3_subject: string; part_3_body: string
}

Open questions

• Send-lane automation. A pilot send lane is in progress but has been blocked on local sender configuration; how much of the send step to automate vs. keep human-in-the-loop is open.
• Contact selection. The toolkit encodes role-preference guidance (web owner → marketing ops → … → generic alias), but the right primary/backup contact per archetype is still being tuned. See the global Open questions.