AI generation API

Build and revise complete HTML emails from natural language — the same engine behind the AI builder, exposed as two synchronous endpoints. Generate from a prompt, iterate with follow-up instructions, and everything stays editable in the visual builder.

How it works

Generation creates a template (provenance source: "api") and a chat session, so anything your integration produces opens in the visual builder with full history and per-step checkpoints; edits append to that history, and “Revert to checkpoint” works on API-made changes. By default the generator uses your brand profile and uploaded brand assets — colors, fonts, logo, voice — so drafts arrive on-brand; pass apply_brand: false for a neutral draft.

Both endpoints consume AI credits (estimate-then-settle from real token usage; 402 CREDITS_EXHAUSTED when depleted), require the emails scope, and share the ai rate-limit class (20 requests/minute). Calls are synchronous and may take up to two minutes; a breach returns a 504 SERVER_ERROR envelope with details.reason: "generation_timeout".

replay

Send an Idempotency-Key with generate calls — a replay returns the same template_uid instead of generating (and metering) twice. See idempotency.

Endpoints

Method	Endpoint	Description
POST	`/emails/generate`	Generate a new email. Required: `prompt` (≤4000 chars). Optional: `name`, `apply_brand` (default `true`). Returns `201` with `template_uid`, `html`, `tokens_used`, and a `subject_suggestion` when one can be derived.
PATCH	`/emails/{template_uid}`	Revise an existing template with an instruction (≤2000 chars). Returns the updated `html`, `tokens_used`, and a `checkpoint_id` usable in the builder's history.

# Generate, then iterate
curl -X POST https://emailflow.ai/api/v1/emails/generate \
  -H "Authorization: Bearer efa_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1c4d2c4e-launch-01" \
  -d '{"prompt": "A product-launch email with one hero section and a CTA to the docs", "name": "Launch announcement"}'

# Response (201)
{
  "template_uid": "6a2c5b1ebaf83",
  "name": "Launch announcement",
  "html": "...",
  "tokens_used": 3069,
  "subject_suggestion": "Introducing the EmailFlow AI API"
}

curl -X PATCH https://emailflow.ai/api/v1/emails/6a2c5b1ebaf83 \
  -H "Authorization: Bearer efa_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instruction": "Make the CTA button deep purple"}'

# Response (200)
{
  "template_uid": "6a2c5b1ebaf83",
  "html": "...",
  "tokens_used": 4040,
  "checkpoint_id": "api_edcb1899-0a9a-42bf-82db-9818c88ac476"
}

After generation

The returned html is a complete, self-contained email document — use it directly as campaign content, or fetch it again later via the templates resource (?include=html, filter source=api). Open the template in the app to continue in the chat editor exactly where the API left off — the API-seeded conversation and checkpoints are all there. A full generate-and-send recipe ships in the SDK cookbook.