v1

latestOpenAPI 3.1.02026-07-2670105729.6 KB

Emails

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

Headers

Idempotency-Keystring

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

Request body

promptstring required

What the email is about — campaign goal, key content, offer, tone. The more specific (product names, dates, discount, audience), the better the design.

contentUrlsstring[]

Up to 8 source URLs to build the email FROM — each is crawled and synthesized into one email (newsletters, recaps, product roundups).

referenceEmailIdstring

An existing design (emailId from list_email_designs) to use as the style/layout reference for the new email.

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

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

responsestring required