Edit an email design
Two kinds of change, combinable in one call — at least one of prompt / subjectLine is required:
prompt— a natural-language AI edit (optionally aemailVersionIdsource pin +contentUrls): the Brew email agent edits the design’s current latest version (or the pinned version) and writes a newversion: "latest"row on the sameemailId(the previous head is demoted to a numeric historical version). USAGE-metered — the agent’s actual token spend is charged. AsubjectLinesent alongside is applied to the new head after the edit completes.subjectLinealone — a deterministic in-place envelope patch: no AI run, no new version, FREE. Returns the CURRENT head in the generated-email shape.emailVersionIdrequiresprompt(a pin is meaningless for an envelope patch).
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"eml_2SmZOWV3ZQ7W5x6g3m4p"
Body
A natural-language prompt edit (optional emailVersionId source pin, optional contentUrls) and/or a subjectLine to set on the design — at least one of prompt / subjectLine. 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 list_email_designs include: ["versions"]). 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).
8Inbox 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 subjectLine-only patch — no new version, free), or a text response if the agent returned prose instead of a design.