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."
}
'{
"response": "No email was generated."
}Generate an email design
Generates a new design through the Brew email agent. Designs are pure: no send state, no type. Sending happens later with createSend, or a sendEmail node in an automation references the returned emailId and emailVersionId. Usage-metered: the agent’s actual token usage is billed.
Use when you have a brief and want Brew to author on brand. For existing markup use importEmail; for a Figma frame use importFigmaDesign.
Input prompt; optional category (steers the design treatment only: transactional categories get receipt or reset conventions, while delivery for those flows is a triggered automation on a transactional-purpose domain), contentUrls, referenceEmailId, title (the canvas name, 1 to 200 characters; omit and Brew derives one from the subject line or the prompt), subjectLine (the design-default inbox subject; createSend still takes a per-send subject), lang (the language of the copy, ISO 639-1; omit and Brew detects it from the finished body), and groupId (grp_… or ungrouped) or groupName (resolve or create), not both; omit to land Ungrouped. Supports Idempotency-Key.
Returns 201 { emailId, emailVersionId, html, previewImage?, group, subjectLine?, title? } when a design was persisted, or 200 { response } when the agent answered in prose without writing a design.
Errors 404 REFERENCE_EMAIL_NOT_FOUND for an unknown referenceEmailId; 404 EMAIL_GROUP_NOT_FOUND for an unknown groupId; 422 BRAND_NOT_READY while the brand is still extracting; 502 EMAIL_GENERATION_FAILED when the agent could not produce a design; 409 EMAIL_RESULT_UNAVAILABLE when the design was saved but its completed result could not be returned (read the saved emailVersionId from error.details; do not repeat generation); 402 INSUFFICIENT_CREDITS on an empty balance.
See also editEmail, importEmail, createSend.
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."
}
'{
"response": "No email was generated."
}Authorizations
Send your Brew API key as Authorization: Bearer brew_xxx.
Headers
Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.
1 - 100The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise 400 BRAND_ID_REQUIRED — there is no default brand); list ids with GET /v1/brands. Brand-scoped credentials may omit it, and sending a different brand returns 403 BRAND_SCOPE_MISMATCH. A brand outside your organization returns 404 BRAND_NOT_FOUND.
1 - 64Body
Generation prompt plus optional source URLs / reference design. The brand comes from the credential (or the X-Brand-Id header on an organization-scoped one) and must not be passed in the body.
What the email is about — campaign goal, key content, offer, tone. The more specific (product names, dates, discount, audience), the better the design.
1Up to 8 source URLs to build the email FROM — each is crawled and synthesized into one email (newsletters, recaps, product roundups).
8The emailId of an existing design to redraw in this brand's voice — one of this brand's own designs (GET /v1/emails) or a public gallery template (GET /v1/templates). Its layout and structure are the reference; the copy, imagery and styling become this brand's.
Email category that steers the design treatment (exemplars, hero recipe, personalization) — mirrors what the in-app agent infers per request. One of: welcome, onboarding, newsletter, content, event-invitation, event-reminder, event-recap, product-launch, product-update, product-pitch, promotional, cart-abandonment, re-engagement, subscription, feedback-request, referral, company-news, fundraising, order-confirmation, shipping-update, receipt, password-reset, verification, security-alert, account-update, notification, support, internal, business, general. Omit for a general treatment. Transactional categories (receipt, password-reset, order-confirmation, …) steer receipt/reset design conventions; to DELIVER those emails, wire the design into an automation with a trigger and a transactional-purpose sending domain, then fire the trigger.
welcome, onboarding, newsletter, content, event-invitation, event-reminder, event-recap, product-launch, product-update, product-pitch, promotional, cart-abandonment, re-engagement, subscription, feedback-request, referral, company-news, fundraising, order-confirmation, shipping-update, receipt, password-reset, verification, security-alert, account-update, notification, support, internal, business, general Canvas name, 2-4 words (e.g. 'Newsletter Welcome'). Omit and Brew names it.
1 - 200Inbox subject line to set on the design (subjectLine — distinct from title, the canvas name). Sends still take an explicit per-send subject; this is the design's default, seeded into the send dialog and returned by GET /v1/emails/{emailId}.
1 - 250ISO 639-1 language code of the email's copy (or zh-Hans / zh-Hant). Omit and Brew's language model reads it from the finished body; a value you set is kept and never re-detected. Becomes the HTML document's lang (and dir for right-to-left languages) on every send and export. One of: en, de, fr, es, pt, it, nl, pl, sv, da, no, fi, cs, sk, hu, ro, bg, el, tr, ru, uk, hr, sr, sl, lt, lv, et, ca, ar, he, fa, ur, hi, bn, th, vi, id, ms, tl, ja, ko, zh-Hans, zh-Hant, sw, af.
en, de, fr, es, pt, it, nl, pl, sv, da, no, fi, cs, sk, hu, ro, bg, el, tr, ru, uk, hr, sr, sl, lt, lv, et, ca, ar, he, fa, ur, hi, bn, th, vi, id, ms, tl, ja, ko, zh-Hans, zh-Hant, sw, af File the design under an existing group (grp_…), or ungrouped. Mutually exclusive with groupName.
1 - 64File the design under a group resolved (or created) by this name. Mutually exclusive with groupId.
1 - 60Response
The agent answered in prose without writing a design ({ response }).
1Was this page helpful?