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

# Generate an email design

> Generates a new design through the Brew email agent. Emails are pure DESIGNS in the decoupled model — no send state, no type. Sending happens later — `POST /v1/sends` delivers the design to a target (a saved audience, an inline list, or a single address) via a verified domain (or fires a one-off test with `test: true`), or a `sendEmail` node in an automation graph references the returned `emailId` + `emailVersionId`.

Returns `201` with `{ emailId, emailVersionId, html, previewImage? }` when a design was persisted, or `200` with `{ response }` when the agent answered in prose without writing a design. Supports `Idempotency-Key` for safe retries.



## OpenAPI

````yaml /api-reference/openapi-public-v1.yaml post /v1/emails
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:
    post:
      tags:
        - Emails
      summary: Generate an email design
      description: >-
        Generates a new design through the Brew email agent. Emails are pure
        DESIGNS in the decoupled model — no send state, no type. Sending happens
        later — `POST /v1/sends` delivers the design to a target (a saved
        audience, an inline list, or a single address) via a verified domain (or
        fires a one-off test with `test: true`), or a `sendEmail` node in an
        automation graph references the returned `emailId` + `emailVersionId`.


        Returns `201` with `{ emailId, emailVersionId, html, previewImage? }`
        when a design was persisted, or `200` with `{ response }` when the agent
        answered in prose without writing a design. Supports `Idempotency-Key`
        for safe retries.
      operationId: generateEmail
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Optional idempotency key for safe retries. Reusing the same key with
            the same request body returns the original response for 24 hours.
          schema:
            type: string
            minLength: 1
            maxLength: 100
          example: api-request-2026-04-08-001
      requestBody:
        required: true
        description: >-
          Generation prompt plus optional source URLs / reference design. The
          brand is resolved from the API key and must not be passed.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailGenerateRequest'
            examples:
              basic:
                summary: Generate a design from a prompt
                value:
                  prompt: >-
                    Create a welcome email for new customers who joined Brew
                    today.
              fromContent:
                summary: Synthesize one email from up to 8 source URLs
                value:
                  prompt: Summarize this month’s product updates into a newsletter.
                  contentUrls:
                    - https://example.com/blog/product-launch
      responses:
        '200':
          description: >-
            The agent answered in prose without writing a design (`{ response
            }`).
          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/EmailGenerateTextResponse'
              example:
                response: No email was generated.
        '201':
          description: >-
            A design was persisted. Usage-metered: the actual token usage of the
            email agent is charged (no fixed price, so no `X-Credit-Cost`
            header). `emailVersionId` pins the exact version for sends +
            automation `sendEmail` nodes.
          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/EmailGenerateGeneratedResponse'
              example:
                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
        '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 brand bound to the API key is missing or not accessible.
          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_FOUND
                  type: not_found
                  message: The requested brand was not found.
                  suggestion: >-
                    Verify in the dashboard that the brand bound to this API key
                    still exists.
                  docs: https://docs.brew.new/api-reference/api/errors
        '409':
          description: The same `Idempotency-Key` was reused with a different request body.
          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: IDEMPOTENCY_CONFLICT
                  type: conflict
                  message: >-
                    The same idempotency key was reused with a different request
                    payload.
                  suggestion: Reuse the original payload or send a new idempotency key.
                  docs: https://docs.brew.new/api-reference/api/idempotency
        '422':
          description: >-
            The brand bound to the API key has not finished extraction — check
            `GET /v1/brand` for `ready: true` first.
          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 (GET /v1/brand →
                    ready) before generating 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:
    EmailGenerateRequest:
      type: object
      properties:
        prompt:
          type: string
          minLength: 1
        contentUrls:
          type: array
          items:
            type: string
            format: uri
          maxItems: 8
        referenceEmailId:
          type: string
        category:
          type: string
          enum:
            - welcome
            - newsletter
            - promotional
            - product-launch
            - product-update
            - cart-abandonment
            - event-invitation
            - event-reminder
            - feedback-request
            - re-engagement
            - referral
            - business
            - internal
            - general
          description: >-
            Marketing email category that steers the design treatment
            (exemplars, hero recipe, personalization) — mirrors what the in-app
            agent infers per request. One of: welcome, newsletter, promotional,
            product-launch, product-update, cart-abandonment, event-invitation,
            event-reminder, feedback-request, re-engagement, referral, business,
            internal, general. Omit for a general treatment. Transactional
            emails (receipts, password resets, order confirmations) are sent via
            automations with a trigger, not this endpoint.
      required:
        - prompt
      additionalProperties: false
    EmailGenerateTextResponse:
      type: object
      properties:
        response:
          type: string
          minLength: 1
      required:
        - response
      additionalProperties: false
    EmailGenerateGeneratedResponse:
      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
    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

````