Recuptive — Beta Client Onboarding [INTERNAL]

Pre-launch progress 0 of 10 required items complete

✓ Email infrastructure (Resend)

✓ Suppression / opt-out system

✓ Dedup (phone + email)

✓ Sequence engine (dry-run)

✓ Idempotency verified

→ Client record & Twilio remaining

Step 1 — Information needed from the HVAC company

Business name

The company's full legal or trading name (e.g. "Owens HVAC & Cooling LLC"). Used in email templates as {{company_name}}.

Required

Owner / contact name

The person who will be the primary point of contact. Used as {{agent_name}} in outbound messages if no override is set in client settings.

Required

Contact email address

Where we send their weekly summary and any alerts. Not used in outbound messages to their leads.

Required

Contact phone number

Their main business number. Stored in clients.contact_phone and used as {{company_phone}} in message templates.

Required

Approximate weekly inbound lead volume

Needed to confirm they meet the 10 leads/week minimum and to estimate Twilio message volume for A2P registration.

Required

Lead source(s) — what system generates their inbound leads

e.g. ServiceTitan, Jobber, Housecall Pro, Google Local Services, website contact form, Angi/HomeAdvisor, phone calls. Determines integration method.

Required

Preferred agent name for outbound messages

What name appears in SMS/email — e.g. "Mike from Owens HVAC" or just "Owens HVAC". Stored as client.settings.agent_name. Defaults to contact name if not set.

Optional but recommended

Physical mailing address

Required by CAN-SPAM in all outbound emails. Must be a real physical street address (not a PO Box alone). Set as the MAILING_ADDRESS secret — currently a placeholder in email footers.

Required before live email

Step 2 — Create the client record in the database

Ask the AI CEO to insert this record (paste into chat, fill in brackets)

Insert a new client record with the following:
  business_name: "[Company Name]"
  contact_name: "[Owner Name]"
  contact_email: "[owner@company.com]"
  contact_phone: "[+1XXXXXXXXXX]"
  industry: "hvac"
  status: "active"
  settings: {
    "sequence_id": "c9269e7a-0aed-46a3-b0d2-551948de7691",
    "agent_name": "[Mike from Owens HVAC]"
  }

✓ The sequence_id above is the live HVAC follow-up sequence — already seeded in the database.
✓ The AI CEO will generate and return a client_id (UUID) — copy it for Step 3.
✓ After inserting the real client, separately ask the AI CEO to set the test client (00000000-0000-0000-0000-000000000001) to status: inactive.

Step 3 — Connect their lead source to Recuptive

Lead intake webhook endpoint

POST https://tortvbzanjbzyzmcvopv.functions.supabase.co/lead-intake
Content-Type: application/json

{
  "client_id": "[UUID from Step 2]",
  "first_name": "{{lead.first_name}}",
  "last_name": "{{lead.last_name}}",
  "phone": "{{lead.phone}}",
  "email": "{{lead.email}}",
  "source": "web_form",
  "source_url": "{{lead.source_url}}",
  "service_requested": "{{lead.service_type}}",
  "message": "{{lead.message}}"
}

Integration options by lead source

ServiceTitan / Jobber / Housecall Pro Use their Zapier or webhook trigger → POST to above URL

Website contact form POST form data directly to the webhook, or use Zapier/Make

Google Local Services Ads Use Google LSA → Zapier → Recuptive webhook

Angi / HomeAdvisor Email parse via Zapier (Gmail trigger) → POST to webhook

Manual / testing Use /admin/test-lead with the real client_id — dry-run safe

Required fields: client_id + (phone OR email).
All other fields are optional but improve personalization. first_name is strongly recommended.
Duplicate leads within 30 days are silently ignored — safe to send every form submission.

Step 4 — Twilio SMS configuration (do not enable yet)

Twilio account & phone number

Create a Twilio account at twilio.com. Purchase a local 10DLC phone number for the client's area code. Note the number in E.164 format (+1XXXXXXXXXX).

Requires human action

A2P 10DLC brand & campaign registration

Register Recuptive (or the client's brand) and submit a "Mixed" or "Lead Follow-Up" use-case campaign. Approval typically takes 1–5 business days. Without this, US carriers will filter most outbound SMS.

Requires human action — do before live SMS

Set Twilio secrets via AI CEO

Once you have Twilio credentials, ask the AI CEO to open the secure form for each. Do NOT paste keys into chat.

TWILIO_ACCOUNT_SID AC… from Twilio console

TWILIO_AUTH_TOKEN From Twilio console — used for signature validation

TWILIO_FROM_NUMBER +1XXXXXXXXXX — the purchased number, E.164 format

Required before live SMS

Add twilio_from_number to client settings

After inserting the client record, update their settings JSON to include "twilio_from_number": "+1XXXXXXXXXX". This enables the opt-out handler to associate SMS STOP replies with the correct client. Without it, SMS opt-outs fall back to global suppression (still safe, less precise).

Required for correct SMS opt-out isolation

Configure Twilio webhook for SMS STOP replies

In Twilio console → Phone Numbers → your number → Messaging → "A message comes in" → Webhook → set to:
https://tortvbzanjbzyzmcvopv.functions.supabase.co/opt-out-handler
Method: HTTP POST

Required before live SMS

Step 5 — Email compliance (CAN-SPAM)

✓

Unsubscribe mechanism

HMAC-signed unsubscribe link in every email. Verified working. Opt-outs are client-scoped and permanent.

Complete

✓

Honest subject lines and sender identification

All email subjects are non-deceptive. Sender is identified as the client's business name via Recuptive.

Complete

Physical mailing address in email footer

CAN-SPAM requires a valid physical postal address in every commercial email. Currently a placeholder: "[Physical address required — set MAILING_ADDRESS secret]". Set the MAILING_ADDRESS secret to your real business address before sending live email. Ask the AI CEO to open the secure form.

Required before live email

✓

Opt-out honored within 10 business days

Opt-outs are processed immediately — the suppression check runs before every step. No waiting period needed.

Complete

Step 6 — Final checks before enabling live messaging

Run a dry-run test with the real client_id

Use /admin/test-lead with the production client_id (not the test UUID). Verify the response shows step1_provider: "simulated" and a lead appears in /admin/leads. Delete the test lead after.

Required

Verify sequence-runner cron is firing

Cron runs every 2 hours. Confirm the scheduled job sequence-runner-hourly shows a recent dispatch time. Ask the AI CEO to check if unsure.

Required

Set LIVE_MESSAGING to "true" — explicit owner approval required

This is the final gate. Do not flip this until every other item in this checklist is complete. Ask the AI CEO to open the secure form when ready. Once set to "true", real SMS and email will go out immediately on the next lead intake or sequence-runner run.

Owner approval required

What's already complete and verified

Infrastructure

Resend API✓ Connected

From email✓ hello@recuptive.com

Custom domain✓ recuptive.com

UNSUB_SECRET✓ Set

Cron schedule✓ Every 2h

Lead engine

Phone dedup✓ 30-day window

Email dedup✓ 30-day window

Email opt-out✓ HMAC signed

SMS opt-out✓ Client-isolated

Idempotency✓ Per step/lead

Compliance

Unsubscribe link✓ In all emails

SMS STOP language✓ All SMS steps

Physical address✗ Set MAILING_ADDRESS

Sequences

HVAC sequence✓ 5 steps seeded

Step 1 — SMS✓ Immediate

Step 2 — SMS✓ ~1 hour

Step 3 — Email✓ ~24 hours

Steps 4–5 — SMS✓ Day 3 & 5

Recuptive Admin

Ask the AI CEO to insert this record (paste into chat, fill in brackets)

Lead intake webhook endpoint

Integration options by lead source

Infrastructure

Lead engine

Compliance

Sequences