Generate an email design

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.

POST /v1/emails

cURL

basic

curl --request POST \
  --url https://brew.new/api/v1/emails \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "Create a welcome email for new customers who joined Brew today."
}
'

200

{
  "response": "No email was generated."
}

Authorizations

bearerAuthapiKeyAuth

Authorization · string · header · default: Bearer brew_your_api_key · required

Send your Brew API key as Authorization: Bearer brew_xxx.

Headers

Idempotency-Key · string

Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.

Required string length: 1 - 100

Body

application/json

Generation prompt plus optional source URLs / reference design. The brand is resolved from the API key and must not be passed.

prompt · string · required

Minimum string length: 1

contentUrls · string<uri>[]

Maximum array length: 8

referenceEmailId · string

category · enum<string>

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.

Available options: welcome, newsletter, promotional, product-launch, product-update, cart-abandonment, event-invitation, event-reminder, feedback-request, re-engagement, referral, business, internal, general

Response

200

application/json

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

response · string · required

Minimum string length: 1