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), or both in one call. At least one of the three is required. A design renames 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 …), or setting the inbox subject the design carries by default.
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) and subjectLine sets the default inbox subject; either or both without prompt is a deterministic in-place patch (no AI run, no new version, free). With prompt, the rename lands first so the new version inherits it 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 (title and subjectLine echo the values set); a text response when the agent answered in prose.
Errors 404 EMAIL_NOT_FOUND, EMAIL_VERSION_NOT_FOUND (a pin that is not one of this design’s versions); 409 EMAIL_IN_PROGRESS while the design is still generating (or a concurrent edit moved the head between read and patch); 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 three 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 and subjectLine — at least one of the three. 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 set subjectLine (at least one of the two is required).
1Pin the edit to a specific source version (from run_data_command (db find emails emailId=<id>) or GET /v1/emails). 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 - 250Response
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?