Skip to main content

SEO Intake-Email Auto-Ingest (Layer 3) — 2026-06-03

Summary

The SEO Intake-Email Auto-Ingest feature (Layer 3) automatically processes inbound client SEO intake questionnaire emails and creates draft client, site, and intake records in the SEO Readiness Portal workspace. The feature is idempotent, read-only on the email side, and produces DRAFT-only records with no outbound network calls or email sends.

How It Works

A Node/TypeScript script parses numbered SEO intake questionnaire fields from an email body and extracts:

  • Business name
  • Target markets
  • Languages
  • Priority services
  • Competitors
  • Google Business Profile (GBP) status
  • Website status

The script infers boolean flags (hasWebsite, gbpClaimed, gbpManagerAccess) based on the parsed fields and writes structured records to:

  • .data/workspace.json (client, site, intake objects with DRAFT status)
  • .data/ingest-ledger.json (deduplication ledger keyed by source email id)

All records are created with:

  • client.status="lead"
  • intake.status="submitted"

No audit auto-run. No email send. Email fetch is read-only via email-inbox.js show/pending.

Usage

Script location: ~/business/ALAI-Holding-AS/products/SEO-Readiness-Portal/scripts/ingest-intake-email.ts

Commands:

# Ingest a specific email by ID
npm run ingest:intake -- --email-id <id>

# Scan for eligible intake emails (list only, no ingest)
npm run ingest:intake -- --scan

# Dry-run mode
npm run ingest:intake -- --dry-run --email-id <id>

# Run audit flag (currently no-op, emits warning)
npm run ingest:intake -- --run-audit

Guardrails

  • Draft-only: All created records are drafts. client.status="lead", intake.status="submitted".
  • No outbound email: The script never sends email, only reads.
  • Read-only email fetch: Email fetch via email-inbox.js is read-only.
  • Idempotent: Re-running the same email ID is a clean no-op (dedup ledger keyed by source email id). No duplicate records created.
  • No audit auto-run: Audits must be manually triggered; --run-audit is currently a no-op with warning.

FlowForge Launchd Wrapper

A launchd template is available for periodic scanning:

  • Template: scripts/launchd/com.alai.seo-intake-ingest.plist
  • Behavior: Runs npm run ingest:intake -- --scan every 15 minutes
  • RunAtLoad: false (does not run on boot)
  • Logging: ~/Library/Logs/com.alai.seo-intake-ingest.{out,err}.log
  • Status: NOT auto-loaded by default
  • Install steps: See scripts/launchd/README.md

Test Fixture & Evidence

Real email test: Asmir email #8792 processed successfully:

  • Client: client-smoke-house-hadzici
  • Site: site-client-smoke-house-hadzici
  • Intake: intake-client-smoke-house-hadzici
  • Business: Smoke House Hadžići
  • Mode: No-website GBP/local
  • Competitors: 5
  • Priority services: 10

Verification steps completed by John 2026-06-03:

  • npm run type-check clean
  • Proveo e2e PASS
  • Idempotent re-run re-verified (no duplicate created)

Evidence location: /tmp/evidence-102866/{verification.json,proveo-validation.json,ingest-run.txt}

Limitations

  • --scan is list-only; it does not auto-ingest. Each email must be processed explicitly with --email-id.
  • No automatic audit trigger (future enhancement).
  • No outbound network calls or email sends in this layer.

Documentation generated for MC #102866, 2026-06-03.

No comments to display

Back to top