curl --request PATCH \
--url https://brew.new/api/v1/emails/{emailId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "Tighten the headline and replace the CTA copy with \"Get started today\"."
}
'{
"emailId": "2SmZOWV3ZQ7W5x6g3m4pA",
"emailVersionId": "8g3m4pA2SmZOWV3ZQ7W5x",
"html": "<!DOCTYPE html><html><body>Welcome to Brew.</body></html>",
"previewImage": "https://storage.example.com/emails/2SmZOWV3ZQ7W5x6g3m4pA.png",
"group": null
}Edit an email design
Updates a design: an AI edit (prompt), its envelope (title, subjectLine, lang, groupId), or both in one call. At least one of the five is required. A design renames and moves between groups here exactly like an audience, trigger, automation or group renames through its own PATCH.
Use when changing an existing design: rewording or restyling it with a prompt, renaming it (a clone starts as Copy of …), setting the inbox subject the design carries by default, or filing it in another group.
Input prompt runs the Brew email agent against the current latest version (or the emailVersionId pin, optionally grounded by contentUrls) and writes a new version: "latest" row on the same emailId (the previous head becomes a numeric historical version); usage-metered by actual token spend. title renames the design (its canvas name, 1 to 200 characters), subjectLine sets the default inbox subject, lang sets the language of the copy (kept from then on; Brew stops re-detecting it) and groupId moves it into an existing group (null = Ungrouped); any of them without prompt is ONE atomic in-place patch (no AI run, no new version, free). With prompt, the rename and move land first so the new version inherits them and the subject is applied to the new head. emailVersionId requires prompt.
Returns 200 with the generated-email shape: the NEW head after a prompt edit, or the CURRENT head after an envelope patch (with its title, subjectLine and group after the patch); a text response when the agent answered in prose.
Automations a prompt edit moves every automation sendEmail step pinned to the previous latest version onto the new one, in a new unpublished automation version (while a Brew agent is still building that automation, its in-progress draft is updated in place instead); the published version keeps its pin until the next publish. Steps pinned to an older version do not move. An envelope patch writes no version and moves nothing.
Errors 404 EMAIL_NOT_FOUND, EMAIL_VERSION_NOT_FOUND (a pin that is not one of this design’s versions), EMAIL_GROUP_NOT_FOUND (a groupId that is not one of this brand’s groups); 409 EMAIL_IN_PROGRESS while the design is still generating (or a concurrent edit moved the head between read and patch); 409 EMAIL_RESULT_UNAVAILABLE when the edit was saved but its completed result could not be returned (read the saved emailVersionId from error.details; do not repeat the edit); 422 BRAND_NOT_READY until the brand has finished extracting; 502 EMAIL_GENERATION_FAILED when the agent run fails (retry later); 400 INVALID_REQUEST for a body with none of the four fields, or emailVersionId without prompt.
See also cloneEmail (name the copy with title), restoreEmailVersion, listEmails.
curl --request PATCH \
--url https://brew.new/api/v1/emails/{emailId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "Tighten the headline and replace the CTA copy with \"Get started today\"."
}
'{
"emailId": "2SmZOWV3ZQ7W5x6g3m4pA",
"emailVersionId": "8g3m4pA2SmZOWV3ZQ7W5x",
"html": "<!DOCTYPE html><html><body>Welcome to Brew.</body></html>",
"previewImage": "https://storage.example.com/emails/2SmZOWV3ZQ7W5x6g3m4pA.png",
"group": null
}Authorizations
Send your Brew API key as Authorization: Bearer brew_xxx.
Headers
The 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 - 64Path Parameters
Design id returned by POST /v1/emails and listed by GET /v1/emails.
1 - 64"2SmZOWV3ZQ7W5x6g3m4pA"
Body
A natural-language prompt edit (optional emailVersionId source pin, optional contentUrls) and/or the envelope fields title, subjectLine, lang and groupId — at least one of the five. Identity lives on the path.
The edit to make, in plain language — e.g. "swap the hero for the spring campaign image and tighten the CTA copy". Scoped edits beat full rewrites. Omit to only patch title, subjectLine, lang or groupId (at least one of the five is required).
1Pin the edit to a specific source version (from GET /v1/emails/{emailId}?include=versions). Requires prompt. Omit to edit the current latest.
1 - 64Up to 8 URLs whose content grounds the edit (e.g. the product page the new section should describe).
8Rename the design (its canvas name, distinct from subjectLine). Deterministic and free; alone it patches the head in place, with prompt the new version inherits 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 - 250Set the language of the email (ISO 639-1, or zh-Hans / zh-Hant). Part of the free envelope patch: no AI run, no new version. Once set it is kept: Brew no longer re-detects it after edits. null clears a language you set, and Brew reads it again from the email.
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, null Move the design into this existing group (grp_…); null moves it to Ungrouped; omit to leave its group alone. Part of the free envelope patch: no AI run, no new version.
1 - 64Response
The edited design (a prompt edit writes a new latest version row and is USAGE-metered), the current head (a title / subjectLine envelope patch — no new version, free), or a text response if the agent returned prose instead of a design.
Was this page helpful?