Email Generation API

Generation is a staged pipeline: copy first, then structure, then code. All stages require a user JWT.

POST /api/gen/copy        (Claude Haiku — finalized copy)
    │
    ▼
POST /api/gen/blueprint   (Claude Haiku — structure + design tokens)
    │
    ▼
POST /api/generate        (Claude Sonnet — kinetic HTML + optional AMP)

Only /api/generate (and the simple /api/generate-email) charge tokens — the ai_generation action is deducted server-side via the spend_tokens RPC, returning 402 on insufficient balance.

POST `/api/gen/copy`

Stage 1: turns the prompt into finalized email copy (Claude Haiku). The copy is the single source of truth for the email's words — the blueprint and code stages place it verbatim.

Request

Field	Type	Required	Description
`prompt`	string	Yes	Email generation prompt
`emailType`	string	No	Email type hint

Response

{
  "success": true,
  "copyDoc": {
    "subject": "...",
    "preheader": "...",
    "sections": [{ "role": "hero", "headline": "...", "body": "...", "cta": "..." }],
    "items": [{ "label": "Pricing", "headline": "...", "body": "..." }]
  },
  "copyText": "Subject  ·  Preheader  ·  ..."
}

items holds copy for interactive elements (tabs, slides, accordion panels). copyText is a flattened manuscript for the reader UI.

POST `/api/gen/blueprint`

Stage 2: produces the full structural blueprint (Claude Haiku) — the same schema /api/generate consumes: complete design tokens (colors, typography, spacing, buttons), sections, and interactive config. Provided copy is placed verbatim.

Request

Field	Type	Required	Description
`prompt`	string	Yes	Email generation prompt
`copyDoc`	object	No	Finalized copy from `/api/gen/copy` (used verbatim)
`emailType`	string	No	Email type hint
`detectedTechnique`	string	No	Kinetic technique hint
`images`	array	No	Uploaded images to assign to sections
`savedSections`	array	No	Locked reusable sections
`designTokens`	object	No	Brand design tokens — used exactly, then force-merged after parse
`styleTheory`	string	No	Style theory key from the Style picker

Response

{
  "success": true,
  "blueprint": { "subject": "...", "technique": "tabs", "design": { "colors": {...}, "typography": {...}, "spacing": {...}, "buttons": {...} }, "sections": [...], "interactiveConfig": {...} }
}

POST `/api/generate`

Stage 3 and the primary endpoint. Uses the full RAG pipeline for context-aware kinetic email code. Charges ai_generation tokens.

Request

curl -X POST https://kinetic.email/api/generate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a product showcase email with tabbed navigation for a shoe brand",
    "useRAG": true,
    "generateAmp": false
  }'

Field	Type	Required	Description
`prompt`	string	Yes	Email generation prompt
`useRAG`	boolean	No	Enable Pinecone RAG retrieval (default `false`)
`emailType`	string	No	Email type for design blueprint injection
`generateAmp`	boolean	No	Also generate AMP4Email output
`images`	array	No	User-uploaded images
`savedSections`	array	No	Saved reusable HTML sections (injected verbatim)
`designTokens`	object	No	Brand design tokens (colors, typography, buttons)
`styleTheory`	string	No	Style theory key (unknown keys degrade silently to Auto)
`blueprint`	object	No	Pre-generated blueprint from `/api/gen/blueprint` (skips inline blueprint generation)
`complexity`	string	No	Complexity hint (default `intermediate`)

Response

{
  "success": true,
  "html": "<!DOCTYPE html>...",
  "ampHtml": "<!doctype html><html ⚡4email>...",
  "blueprint": { "subject": "...", "design": { "colors": {...} }, "sections": [...] },
  "metadata": {
    "technique": "tabs",
    "ampGenerated": false,
    "rag": { "used": true, "examplesCount": 5 },
    "qa": { "score": 92, "qualifiesForFreeRegen": false, "failedChecks": [] },
    "validator": { "fixesApplied": [], "warnings": [], "refineTriggered": false }
  }
}

ampHtml is populated when generateAmp: true is passed. metadata.qa.qualifiesForFreeRegen is true when the QA score is below 70 — those builds qualify for one free regeneration.

How It Works

Auth & tokens — Verifies user JWT, deducts ai_generation tokens (402 if insufficient)
Structured prompt assembly — Combines Playground config tabs into a single prompt:
- Email Type, Kinetic Features, Color Scheme
- Brand Style Guide (colors, fonts, tone, business context, logo)
- Uploaded images with names and descriptions
- Saved sections marked for verbatim injection
Technique extraction — Parses the kinetic technique from the prompt
Query rewriting — Claude reformulates the prompt into a technical retrieval query
Dual RAG queries (parallel, RAG v2 — single Pinecone index, text-embedding-3-large):
- Query A: Technique-filtered Pinecone search (topK=10)
- Query B: Broad unfiltered search (topK=15)
Merge, gate & filter — Deduplicates, drops matches below a 50% score, keeps positive examples only; blog/concept prose is excluded from code context
Re-rank — Claude Haiku selects the best mix of up to 7 results
HTML hydration — Full HTML for matched examples is fetched from the Supabase rag_documents table (Pinecone stores only vectors + small metadata)
Blueprint — Uses the client-supplied blueprint if provided, otherwise Claude Haiku generates one with finalized copy and a design system. Brand design tokens are injected as constraints, then force-merged after parse as a safety net
Parallel generation — Claude Sonnet 4.6 generates kinetic HTML and (if requested) AMP4Email HTML simultaneously, both referencing the same blueprint. Saved sections are injected verbatim; a "View in browser" link using {{VIB_URL}} is included at the top
Deterministic auto-fix — Tiered fixes in api/_validate-kinetic.js (including the Yahoo/AOL .& selector injection) repair mechanical issues without another model call
QA checks — 26 programmatic checks in api/lib/qa-checks.js produce a score; results are logged to the qa_evaluations table

Supported Techniques

Technique	Description
`tabs`	Radio button tabbed interfaces
`accordion`	Checkbox expand/collapse sections
`carousel`	Radio button image/content carousels
`survey`	Progressive disclosure survey forms
`quiz`	Interactive quizzes with reveal states
`menu`	Hamburger menu overlays
`stepper`	Multi-step wizard flows
`toggle`	Simple on/off switches
`amp4email`	AMP-powered interactive emails

POST `/api/generate-email`

A simpler generation endpoint that calls Claude Sonnet directly without the RAG pipeline. Also supports refine mode. Charges ai_generation tokens.

Request

curl -X POST https://kinetic.email/api/generate-email \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a simple tabbed email for a newsletter"
  }'

Field	Type	Required	Description
`prompt`	string	Yes	Generation prompt, or change instructions in refine mode
`refine`	boolean	No	Refine an existing email instead of generating fresh
`currentHtml`	string	No	Existing HTML to refine (required with `refine`)

Response

{
  "success": true,
  "html": "<!DOCTYPE html>...",
  "usage": {
    "input_tokens": 2100,
    "output_tokens": 3800
  }
}

When to Use Which

Scenario	Endpoint
Production email generation	`/api/generate` (RAG pipeline)
Copy the user reads before build	`/api/gen/copy` → `/api/gen/blueprint` → `/api/generate`
Targeted edits to existing HTML	`/api/generate-email` with `refine: true`
Quick prototyping	`/api/generate-email` (direct Claude)

POST /api/gen/copy​

Request​

Response​

POST /api/gen/blueprint​

Request​

Response​

POST /api/generate​

Request​

Response​

How It Works​

Supported Techniques​

POST /api/generate-email​

Request​

Response​

When to Use Which​

POST `/api/gen/copy`

Request

Response

POST `/api/gen/blueprint`

Request

Response

POST `/api/generate`

Request

Response

How It Works

Supported Techniques

POST `/api/generate-email`

Request

Response

When to Use Which