> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brew.new/llms.txt
> Use this file to discover all available pages before exploring further.

# Edit an email design

> 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`.



## OpenAPI

````yaml /api-reference/openapi-public-v1.yaml patch /v1/emails/{emailId}
openapi: 3.1.0
info:
  title: Brew Public API v1
  version: 1.0.0
  description: >-
    Generated from the Brew app Zod contracts (`lib/<domain>/contracts.ts`).
    This file is the source of truth for the public API documentation.


    ## Resource paths


    Identity lives in the URL path (`/v1/analytics/sends/{sendId}`), never in a
    query param or request body. Collections are plural top-level segments
    (`/v1/emails`); query params exist only for collection pagination + simple
    filters. Relationships are sub-resources (`/v1/emails/{emailId}/sends`), and
    non-CRUD operations are explicit action sub-paths
    (`/v1/automations/{automationId}/test`).


    ## Response envelopes


    - Lists: `{ data: Row[], pagination: { limit, cursor: string | null, hasMore
    } }`, loop `while (cursor !== null)`.

    - Get-one and writes: the bare resource (creates return `201`; async sends
    `202`).

    - Deletes: `{ <idField>, deleted: boolean }`, idempotent (already-gone ids
    resolve with `deleted: false`).

    - Errors: `{ error: { code, type, message, param?, suggestion, docs } }`.
    Branch on the stable `code`.

    - ONE exception: `POST /v1/automations/triggers/{triggerEventId}/fire`
    responds with the legacy fire envelope `{ success, status, code, message,
    receivedAt, details }` (shared with internal webhook infrastructure).


    ## Brand scoping


    API keys are always scoped to a specific brand. The brand is resolved from
    the key on every request. **No public endpoint accepts a `brandId` field**
    in its request body or query string, sending one returns `400
    INVALID_REQUEST`. Resources that exist in a different brand surface as `404`
    (never `403`), so the API does not leak cross-brand existence. `GET
    /v1/templates` is organization-wide and not constrained to the key brand.
    Brands themselves are managed in the Brew dashboard.


    ## Idempotency


    Send an `Idempotency-Key` header (≤ 100 chars) on any POST your code might
    retry. Same key + same body within 24h returns the original response; same
    key + different body returns `409 IDEMPOTENCY_CONFLICT`.
  contact:
    name: Brew Support
    url: https://docs.brew.new
    email: support@brew.new
servers:
  - url: https://brew.new/api
    description: Production
  - url: http://localhost:3000/api
    description: Local development
security:
  - bearerAuth: []
  - apiKeyAuth: []
tags:
  - name: Emails
    description: >-
      Email designs and sending. Generate a design with the Brew email agent,
      edit, version, restore, then send it: `POST /v1/sends` delivers a design
      to a target (a saved audience, an inline list, or a single address) via a
      verified domain, and `POST /v1/sends/test` fires a one-off test. Sending
      is not campaign-specific. Send reads (list, status, per-send event feeds)
      live under Analytics (`/v1/analytics/sends`).
  - name: Analytics
    description: >-
      Read-only cross-resource analytics: lifetime per-campaign KPIs, windowed
      automation performance, the unified event feed, send reads
      (`/v1/analytics/sends`), and the fired-trigger audit log
      (`/v1/analytics/trigger-instances`).
  - name: Automations
    description: >-
      Automation graphs, deterministic create from explicit `nodes` +
      `connections`, update, version, publish / unpublish, test. Includes
      trigger event definitions + the fire endpoint (`/v1/automations/triggers`)
      and run history (`/v1/automations/runs`).
  - name: Contacts
    description: Create, search, patch, and delete contacts. Email is the primary key.
  - name: Contact Fields
    description: List, create, and delete custom contact field definitions.
  - name: Audiences
    description: Saved contact filter sets, a recipient target for sends.
  - name: Domains
    description: 'Sending domains: add, read DNS records, verify, configure sender defaults.'
  - name: Templates
    description: Public template gallery (read-only) usable as generation references.
  - name: Brand
    description: The single brand bound to the API key.
  - name: Chats
    description: >-
      Read a brand-scoped digest of a Brew chat (referenced
      emails/automations/triggers + a trimmed transcript) so an external agent
      can resume the conversation.
  - name: Meta
    description: >-
      Public discovery surface (no auth): the machine-readable API catalog
      (`/v1/help`).
paths:
  /v1/emails/{emailId}:
    patch:
      tags:
        - Emails
      summary: Edit an email design
      description: >-
        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`.
      operationId: editEmail
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 64
            description: >-
              Design id returned by `POST /v1/emails` and listed by `GET
              /v1/emails`.
            example: eml_2SmZOWV3ZQ7W5x6g3m4p
          required: true
          description: >-
            Design id returned by `POST /v1/emails` and listed by `GET
            /v1/emails`.
          name: emailId
          in: path
      requestBody:
        required: true
        description: >-
          A natural-language `prompt` edit, with an optional `emailVersionId`
          source pin and optional `contentUrls`. Identity lives on the path.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailEditRequest'
            examples:
              aiEdit:
                summary: AI prompt edit
                value:
                  prompt: >-
                    Tighten the headline and replace the CTA copy with "Get
                    started today".
      responses:
        '200':
          description: >-
            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).
          headers:
            x-request-id:
              schema:
                type: string
                description: >-
                  Unique request identifier. Share this with support when
                  debugging a request.
                example: req_8cac13fd94e6420cacdd75a1aa403a28
              required: true
              description: >-
                Unique request identifier. Share this with support when
                debugging a request.
            X-RateLimit-Limit:
              schema:
                type: integer
                description: Requests allowed in the current rolling rate limit window.
                example: 100
              required: true
              description: Requests allowed in the current rolling rate limit window.
            X-RateLimit-Remaining:
              schema:
                type: integer
                description: Requests remaining in the current rolling rate limit window.
                example: 99
              required: true
              description: Requests remaining in the current rolling rate limit window.
            X-RateLimit-Reset:
              schema:
                type: integer
                description: >-
                  Unix timestamp in seconds for when the rolling window fully
                  resets.
                example: 1712592360
              required: true
              description: >-
                Unix timestamp in seconds for when the rolling window fully
                resets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailGenerateResponse'
              examples:
                generated:
                  summary: Generated design
                  value:
                    emailId: eml_2SmZOWV3ZQ7W5x6g3m4p
                    emailVersionId: emv_2SmZOWV3ZQ7W5x6g3m4p_v1
                    html: <!DOCTYPE html><html><body>Welcome to Brew.</body></html>
                    previewImage: >-
                      https://storage.example.com/emails/eml_2SmZOWV3ZQ7W5x6g3m4p.png
                textOnly:
                  summary: Text response
                  value:
                    response: No email was generated.
        '400':
          description: >-
            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.
          headers:
            x-request-id:
              schema:
                type: string
                description: >-
                  Unique request identifier. Share this with support when
                  debugging a request.
                example: req_8cac13fd94e6420cacdd75a1aa403a28
              required: true
              description: >-
                Unique request identifier. Share this with support when
                debugging a request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
              example:
                error:
                  code: INVALID_REQUEST
                  type: invalid_request
                  message: Request validation failed.
                  suggestion: Fix the field reported in `param` and retry.
                  docs: https://docs.brew.new/api-reference/api/errors
                  param: prompt
        '401':
          description: The API key was missing, invalid, or revoked.
          headers:
            x-request-id:
              schema:
                type: string
                description: >-
                  Unique request identifier. Share this with support when
                  debugging a request.
                example: req_8cac13fd94e6420cacdd75a1aa403a28
              required: true
              description: >-
                Unique request identifier. Share this with support when
                debugging a request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
              example:
                error:
                  code: INVALID_API_KEY
                  type: authentication_error
                  message: The provided API key is invalid.
                  suggestion: Check the API key format and retry with a valid active key.
                  docs: https://docs.brew.new/api-reference/api/authentication
        '402':
          description: >-
            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.
          headers:
            x-request-id:
              schema:
                type: string
                description: >-
                  Unique request identifier. Share this with support when
                  debugging a request.
                example: req_8cac13fd94e6420cacdd75a1aa403a28
              required: true
              description: >-
                Unique request identifier. Share this with support when
                debugging a request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
              example:
                error:
                  code: INSUFFICIENT_CREDITS
                  type: payment_required
                  message: >-
                    This operation required more credits than the 0 remaining on
                    the 'free' plan. See the per-operation cost in GET /v1/help.
                  suggestion: >-
                    Upgrade your plan or wait for the next billing period to
                    reset. Check your balance up front with GET /v1/usage.
                  docs: https://docs.brew.new/api-reference/api/credits
                  details:
                    cost: 2
                    remaining: 0
                    planKey: free
        '403':
          description: The caller does not have the required `emails` permission.
          headers:
            x-request-id:
              schema:
                type: string
                description: >-
                  Unique request identifier. Share this with support when
                  debugging a request.
                example: req_8cac13fd94e6420cacdd75a1aa403a28
              required: true
              description: >-
                Unique request identifier. Share this with support when
                debugging a request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
              example:
                error:
                  code: INSUFFICIENT_PERMISSIONS
                  type: authorization_error
                  message: The caller does not have the required permission.
                  suggestion: Use an API key or session with the required permission.
                  docs: https://docs.brew.new/api-reference/api/authentication
                  param: emails
        '404':
          description: >-
            The design (or the pinned `emailVersionId`) does not exist in the
            API-key brand.
          headers:
            x-request-id:
              schema:
                type: string
                description: >-
                  Unique request identifier. Share this with support when
                  debugging a request.
                example: req_8cac13fd94e6420cacdd75a1aa403a28
              required: true
              description: >-
                Unique request identifier. Share this with support when
                debugging a request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
              examples:
                emailNotFound:
                  summary: Unknown emailId
                  value:
                    error:
                      code: EMAIL_NOT_FOUND
                      type: not_found
                      message: No email exists with id 'eml_x'.
                      suggestion: List designs with GET /v1/emails.
                      docs: https://docs.brew.new/api-reference/api/errors
                      param: emailId
                versionNotFound:
                  summary: Pinned emailVersionId does not belong to this design
                  value:
                    error:
                      code: EMAIL_VERSION_NOT_FOUND
                      type: not_found
                      message: Email 'eml_x' has no version 'emv_other'.
                      suggestion: >-
                        List versions with GET
                        /v1/emails?emailId=&include=versions.
                      docs: https://docs.brew.new/api-reference/api/errors
                      param: emailVersionId
        '409':
          description: >-
            The design is currently being generated and cannot be edited until
            it completes.
          headers:
            x-request-id:
              schema:
                type: string
                description: >-
                  Unique request identifier. Share this with support when
                  debugging a request.
                example: req_8cac13fd94e6420cacdd75a1aa403a28
              required: true
              description: >-
                Unique request identifier. Share this with support when
                debugging a request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
              example:
                error:
                  code: EMAIL_IN_PROGRESS
                  type: conflict
                  message: >-
                    Email 'eml_x' is currently being generated and cannot be
                    edited until it completes.
                  suggestion: >-
                    Wait a few seconds and retry. Streaming emails finalize
                    automatically.
                  docs: https://docs.brew.new/api-reference/api/errors
                  param: emailId
        '422':
          description: The brand has not finished extraction.
          headers:
            x-request-id:
              schema:
                type: string
                description: >-
                  Unique request identifier. Share this with support when
                  debugging a request.
                example: req_8cac13fd94e6420cacdd75a1aa403a28
              required: true
              description: >-
                Unique request identifier. Share this with support when
                debugging a request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
              example:
                error:
                  code: BRAND_NOT_READY
                  type: invalid_request
                  message: The requested brand is not ready for email generation.
                  suggestion: Wait for brand extraction to complete before editing emails.
                  docs: https://docs.brew.new/api-reference/api/errors
        '429':
          description: The request hit the rolling rate limit window.
          headers:
            x-request-id:
              schema:
                type: string
                description: >-
                  Unique request identifier. Share this with support when
                  debugging a request.
                example: req_8cac13fd94e6420cacdd75a1aa403a28
              required: true
              description: >-
                Unique request identifier. Share this with support when
                debugging a request.
            X-RateLimit-Limit:
              schema:
                type: integer
                description: Requests allowed in the current rolling rate limit window.
                example: 100
              required: true
              description: Requests allowed in the current rolling rate limit window.
            X-RateLimit-Remaining:
              schema:
                type: integer
                description: Requests remaining in the current rolling rate limit window.
                example: 99
              required: true
              description: Requests remaining in the current rolling rate limit window.
            X-RateLimit-Reset:
              schema:
                type: integer
                description: >-
                  Unix timestamp in seconds for when the rolling window fully
                  resets.
                example: 1712592360
              required: true
              description: >-
                Unix timestamp in seconds for when the rolling window fully
                resets.
            Retry-After:
              schema:
                type: integer
                description: Seconds to wait before retrying the request.
                example: 42
              required: true
              description: Seconds to wait before retrying the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
              example:
                error:
                  code: RATE_LIMITED
                  type: rate_limit
                  message: Too many requests.
                  suggestion: Wait for the retry window before sending another request.
                  docs: https://docs.brew.new/api-reference/api/rate-limits
                  retryAfter: 42
        '500':
          description: Unexpected internal error.
          headers:
            x-request-id:
              schema:
                type: string
                description: >-
                  Unique request identifier. Share this with support when
                  debugging a request.
                example: req_8cac13fd94e6420cacdd75a1aa403a28
              required: true
              description: >-
                Unique request identifier. Share this with support when
                debugging a request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
              example:
                error:
                  code: INTERNAL_ERROR
                  type: internal_error
                  message: An unexpected error occurred.
                  suggestion: Retry the request. If it keeps failing, contact support.
                  docs: https://docs.brew.new/api-reference/api/errors
        '503':
          description: >-
            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.
          headers:
            x-request-id:
              schema:
                type: string
                description: >-
                  Unique request identifier. Share this with support when
                  debugging a request.
                example: req_8cac13fd94e6420cacdd75a1aa403a28
              required: true
              description: >-
                Unique request identifier. Share this with support when
                debugging a request.
            Retry-After:
              schema:
                type: integer
                description: Seconds to wait before retrying the request.
                example: 42
              required: true
              description: Seconds to wait before retrying the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
              example:
                error:
                  code: SERVICE_UNAVAILABLE
                  type: service_unavailable
                  message: >-
                    Your credit balance could not be verified because a billing
                    dependency is temporarily unavailable.
                  suggestion: Retry the request after a short delay.
                  docs: https://docs.brew.new/api-reference/api/credits
                  retryAfter: 2
components:
  schemas:
    EmailEditRequest:
      type: object
      properties:
        prompt:
          type: string
          minLength: 1
        emailVersionId:
          type: string
          minLength: 1
          maxLength: 64
        contentUrls:
          type: array
          items:
            type: string
            format: uri
          maxItems: 8
      required:
        - prompt
      additionalProperties: false
    EmailGenerateResponse:
      anyOf:
        - type: object
          properties:
            emailId:
              type: string
              minLength: 1
            emailVersionId:
              type: string
              minLength: 1
            html:
              type: string
            previewImage:
              type: string
              format: uri
          required:
            - emailId
            - emailVersionId
            - html
          additionalProperties: false
        - type: object
          properties:
            response:
              type: string
              minLength: 1
          required:
            - response
          additionalProperties: false
    ApiErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              minLength: 1
            type:
              type: string
              enum:
                - authentication_error
                - authorization_error
                - invalid_request
                - not_found
                - not_implemented
                - conflict
                - rate_limit
                - payment_required
                - service_unavailable
                - internal_error
            message:
              type: string
              minLength: 1
            param:
              type: string
              minLength: 1
            suggestion:
              type: string
              minLength: 1
            docs:
              type: string
              format: uri
            retryAfter:
              type: integer
              minimum: 0
            details:
              type: object
              additionalProperties: {}
          required:
            - code
            - type
            - message
            - suggestion
            - docs
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Send your Brew API key as `Authorization: Bearer brew_xxx`.'
      x-default: Bearer brew_your_api_key
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Send your Brew API key as `X-API-Key: brew_xxx`.'
      x-default: brew_your_api_key

````