Skip to main content

Email Generation API

Two endpoints handle AI-powered email generation, each suited for different use cases.

POST /api/generate​

The primary email generation endpoint. Uses the full RAG pipeline for context-aware, high-quality kinetic email output.

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",
    "conversationHistory": []
  }'
FieldTypeRequiredDescription
promptstringYesEmail generation prompt
conversationHistoryarrayNoPrevious messages for multi-turn context

Response​

{
  "success": true,
  "html": "<!DOCTYPE html>...",
  "ampHtml": "<!doctype html><html ⚡4email>...",
  "blueprint": { "subject": "...", "design": { "colors": {...} }, "sections": [...] },
  "usage": {
    "input_tokens": 15234,
    "output_tokens": 4521
  },
  "ragContext": {
    "codeExamples": 4,
    "knowledgeArticles": 3
  }
}

ampHtml and blueprint are included when generateAmp: true is passed in the request.

How It Works​

  1. Auth & tokens — Verifies user JWT, deducts ai_generation tokens
  2. Structured prompt assembly — Combines Playground config tabs into a single prompt:
    • Email Type, Kinetic Features, Color Scheme, RAG Model
    • Brand Style Guide (colors, fonts, tone, business context, logo)
    • Uploaded images with names and descriptions
    • Saved sections marked for verbatim injection
  3. Technique extraction — Parses **Kinetic Features:** from structured prompts
  4. Dual RAG queries (parallel):
    • Query A: Technique-filtered Pinecone search (topK=10)
    • Query B: Broad unfiltered search (topK=15)
  5. Merge & deduplicate — Combines results, removes duplicates
  6. Re-rank — Claude Haiku selects best 7 results for diversity
  7. Content focus filtering — Blog results split by contentFocus: kinetic builds get kinetic + general blogs, AMP builds get amp + general blogs
  8. Blueprint generation — Claude Haiku generates a structural blueprint with finalized copy and design system. If brand design tokens exist, they are injected as constraints — Haiku uses them instead of picking new values. Uploaded images are assigned to sections. Saved sections are marked as locked.
  9. Design token override — After blueprint parse, brand design tokens are force-merged into the blueprint's design object as a safety net
  10. 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 with positional instructions. Images are referenced with <img> tags (kinetic) or <amp-img> (AMP). A "View in browser" link using {{VIB_URL}} is included at the top.
  11. QA check — Validates output against kinetic email rules

Supported Techniques​

TechniqueDescription
tabsRadio button tabbed interfaces
accordionCheckbox expand/collapse sections
carouselRadio button image/content carousels
surveyProgressive disclosure survey forms
quizInteractive quizzes with reveal states
menuHamburger menu overlays
stepperMulti-step wizard flows
toggleSimple on/off switches
amp4emailAMP-powered interactive emails

POST /api/generate-email​

A simpler generation endpoint that calls Claude directly without the RAG pipeline. Faster but less context-aware.

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"
  }'

Response​

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

When to Use Which​

ScenarioEndpoint
Production email generation/api/generate (RAG pipeline)
Quick prototyping/api/generate-email (direct Claude)
Complex kinetic techniques/api/generate (has technique examples)
Simple static emails/api/generate-email (faster)