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, subjectLine (the design-default inbox subject; createSend still takes a per-send subject), 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? } 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; 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).
8An existing design (emailId from run_data_command (db find emails) or GET /v1/emails) to use as the style/layout reference for the new email.
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, order-confirmation, shipping-update, receipt, cart-abandonment, subscription, password-reset, verification, security-alert, account-update, event-invitation, event-reminder, feedback-request, re-engagement, referral, support, business, internal, notification, 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, newsletter, promotional, product-launch, product-update, order-confirmation, shipping-update, receipt, cart-abandonment, subscription, password-reset, verification, security-alert, account-update, event-invitation, event-reminder, feedback-request, re-engagement, referral, support, business, internal, notification, general Inbox 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 - 250File 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?