---
title: "Generate an email design"
method: POST
path: "/v1/emails"
tags: ["Emails"]
---

# Generate an email design

`POST /v1/emails`

Generates a new design through the Brew email agent. Emails are pure DESIGNS in the decoupled model — no send state, no type. Sending happens later — `POST /v1/sends` delivers the design to a target (a saved audience, an inline list, or a single address) via a verified domain (or fires a one-off test with `test: true`), or a `sendEmail` node in an automation graph references the returned `emailId` + `emailVersionId`.

Returns `201` with `{ emailId, emailVersionId, html, previewImage? }` when a design was persisted, or `200` with `{ response }` when the agent answered in prose without writing a design. Supports `Idempotency-Key` for safe retries.

## Headers

- `Idempotency-Key` string

## Request body

- EmailGenerateRequest
  - `prompt` string, required — What the email is about — campaign goal, key content, offer, tone. The more specific (product names, dates, discount, audience), the better the design.
  - `contentUrls` string[] — Up to 8 source URLs to build the email FROM — each is crawled and synthesized into one email (newsletters, recaps, product roundups).
  - `referenceEmailId` string — An existing design (`emailId` from `list_email_designs`) to use as the style/layout reference for the new email.
  - `category` 'welcome' | 'newsletter' | 'promotional' | 'product-launch' | 'product-update' | 'cart-abandonment' | 'event-invitation' | 'event-reminder' | 'feedback-request' | 're-engagement' | 'referral' | 'business' | 'internal' | 'general' — Marketing email category that steers the design treatment (exemplars, hero recipe, personalization) — mirrors what the in-app agent infers per request. One of: welcome, newsletter, promotional, product-launch, product-update, cart-abandonment, event-invitation, event-reminder, feedback-request, re-engagement, referral, business, internal, general. Omit for a general treatment. Transactional emails (receipts, password resets, order confirmations) are sent via automations with a trigger, not this endpoint.

## Response `200`

The agent answered in prose without writing a design (`{ response }`).

- EmailGenerateTextResponse
  - `response` string, required

## Other responses

- `201` — A design was persisted. Usage-metered: the actual token usage of the email agent is charged (no fixed price, so no `X-Credit-Cost` header). `emailVersionId` pins the exact version for sends + automation `sendEmail` nodes.
- `400` — The request body or query string was invalid (unknown key, wrong type, or missing required field). Strict schemas reject unknown keys — including `brandId`, which is always resolved from the API key.
- `401` — The API key was missing, invalid, or revoked.
- `402` — The org's remaining credit balance is below what this operation requires. Credit cost is published PER-OPERATION (see `GET /v1/help`): content/media operations charge a flat cost, while AI generation (email generate/edit/import, image generation) is usage-metered — charged by actual model usage rather than a flat price. `details.cost` carries the amount the runtime required for THIS call. Check your balance up front via `GET /v1/usage`. No `Retry-After` — credits reset at the billing-period boundary.
- `403` — The caller does not have the required `emails` permission.
- `404` — The brand bound to the API key is missing or not accessible.
- `409` — The same `Idempotency-Key` was reused with a different request body.
- `422` — The brand bound to the API key has not finished extraction — check `GET /v1/brand` for `ready: true` first.
- `429` — The request hit the rolling rate limit window.
- `500` — Unexpected internal error.
- `503` — The credit balance could not be verified (a transient billing dependency outage). The gate fails closed rather than do paid work it cannot meter. Retryable — `Retry-After` indicates when.

---

[API](https://skmtc.net/brew/apis/brew-public-api-v1.md) · [All operations](https://skmtc.net/brew/apis/brew-public-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/brew/brew-public-api-v1/versions/db96cfedc6c5/schema)