Files · xAI Grok Lead Intake for Mailchimp SMB Email Marketing

# xAI Grok Lead Intake for Mailchimp SMB Email Marketing
 
> Capture website leads, qualify them with xAI Grok, and automatically sync to Mailchimp audiences without manual sorting.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## How it works
 
1. A **lead submission** is sent via POST to `/api/lead` with the prospect's name, email, company, and message.
2. The **confidence-router** (with an `LLMClassifier` backed by xAI Grok) classifies the lead as **hot**, **warm**, or **cold** based on purchase intent.
3. The **confidence-router** decides: **ROUTE** (high confidence → sync to Mailchimp), **CLARIFY** (ambiguous → ask for more info), or **FALLBACK** (low confidence → reject).
4. Accepted leads are upserted into the configured Mailchimp audience list with quality-based tags (`lead-hot`, `lead-warm`, `lead-cold`).
5. Every classification emits a **cost telemetry span** via `@reaatech/llm-cost-telemetry` and exports it to **Langfuse** for observability.
 
## Quick start
 
```bash
pnpm install
cp .env.example .env    # fill in your API keys
pnpm dev                # start dev server on http://localhost:3000
 
# Try it:
curl -X POST http://localhost:3000/api/lead \
  -H 'Content-Type: application/json' \
  -d '{"name":"Jane Doe","email":"jane@example.com","message":"Interested in your SaaS product"}'
```
 
## API
 
### POST /api/lead
 
Submit a website lead for classification and Mailchimp sync.
 
**Request body:**
```json
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "company": "Acme Corp",
  "message": "Interested in your enterprise plan pricing",
  "phone": "+1-555-0123",
  "source": "contact-form"
}
```
 
**Responses:**
 
| Status | Body | Meaning |
|--------|------|---------|
| 200 | `{"status":"accepted","contactId":"abc123"}` | Lead synced to Mailchimp |
| 200 | `{"status":"clarify","prompt":"Please provide more details..."}` | Needs more info |
| 422 | `{"status":"rejected","reason":"..."}` | Low confidence / error |
| 400 | `{"error":"Invalid input","details":[...]}` | Validation failed |
 
## Mailchimp integration
 
The Mailchimp adapter (`src/lib/mailchimp.ts`) syncs enriched leads to a configured audience list.
 
| Detail | Value |
|--------|-------|
| Audience list ID | `MAILCHIMP_LIST_ID` env var |
| Merge fields mapped | `FNAME` (lead name), `PHONE`, `COMPANY`, `SOURCE` |
| Tagging convention | `lead-hot`, `lead-warm`, `lead-cold` per quality classification |
 
## Tags
 
Leads are tagged in Mailchimp with their quality level:
 
| Quality | Tag |
|---------|-----|
| hot | `lead-hot` |
| warm | `lead-warm` |
| cold | `lead-cold` |
 
## Environment variables
 
See `.env.example` for all required variables.
 
## Project layout
 
```
app/api/lead/route.ts    POST /api/lead endpoint
src/lib/types.ts         Type definitions + Zod schemas
src/lib/classifier.ts    Grok classification + confidence routing
src/lib/repair.ts        Structured LLM output repair
src/lib/telemetry.ts     Cost telemetry + Langfuse export
src/lib/mailchimp.ts     Mailchimp API adapter
src/lib/lead-processor.ts Orchestration layer
tests/                   Vitest suite (mirrors src/)
```
 
## License
 
MIT — see [LICENSE](./LICENSE).