---
title: "Edit an email design"
method: PATCH
path: "/v1/emails/{emailId}"
tags: ["Emails"]
---

# Edit an email design

`PATCH /v1/emails/{emailId}`

Applies a natural-language `prompt` edit (optionally a `emailVersionId` source pin + `contentUrls`) to an existing design: the Brew email agent edits the design’s current latest version (or the pinned version) and writes a new `version: "latest"` row on the same `emailId` (the previous head is demoted to a numeric historical version).

USAGE-metered — the agent’s actual token spend is charged. Returns the generated-email shape with the new `emailVersionId`.

## Path parameters

- `emailId` string, required — Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.

## Request body

- EmailEditRequest
  - `prompt` string, required — 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.
  - `emailVersionId` string — Pin the edit to a specific source version (from `list_email_designs` `include: ["versions"]`). Omit to edit the current latest.
  - `contentUrls` string[] — Up to 8 URLs whose content grounds the edit (e.g. the product page the new section should describe).

## Response `200`

Updated design (a new `latest` version row was written) or a text response if the agent returned prose instead of a design. USAGE-metered: the agent’s actual token usage is charged (no fixed price).

- union
  - object
    - `emailId` string, required
    - `emailVersionId` string, required
    - `html` string, required
    - `previewImage` string, uri
  - object
    - `response` string, required

## Other responses

- `400` — The request body or query string was invalid (unknown key, wrong type, or missing required field). Strict schemas reject unknown keys — including `brandId`, which is always resolved from the API key.
- `401` — The API key was missing, invalid, or revoked.
- `402` — The org's remaining credit balance is below what this operation requires. Credit cost is published PER-OPERATION (see `GET /v1/help`): content/media operations charge a flat cost, while AI generation (email generate/edit/import, image generation) is usage-metered — charged by actual model usage rather than a flat price. `details.cost` carries the amount the runtime required for THIS call. Check your balance up front via `GET /v1/usage`. No `Retry-After` — credits reset at the billing-period boundary.
- `403` — The caller does not have the required `emails` permission.
- `404` — The design (or the pinned `emailVersionId`) does not exist in the API-key brand.
- `409` — The design is currently being generated and cannot be edited until it completes.
- `422` — The brand has not finished extraction.
- `429` — The request hit the rolling rate limit window.
- `500` — Unexpected internal error.
- `503` — The credit balance could not be verified (a transient billing dependency outage). The gate fails closed rather than do paid work it cannot meter. Retryable — `Retry-After` indicates when.

---

[API](https://skmtc.net/brew/apis/brew-public-api-v1.md) · [All operations](https://skmtc.net/brew/apis/brew-public-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/brew/brew-public-api-v1/versions/db96cfedc6c5/schema)