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

# Import an email

> Converts existing markup into a NEW, fully EDITABLE Brew email design on the brand canvas. Brew rebuilds the markup into a clean, fully editable design, and EVERY external image is fetched, optimized, and RE-HOSTED on the Brew CDN (no hot-linking third-party assets).

`content` is the raw markup as a STRING; `format` describes what you supply: `html` (an HTML email document or fragment), `mjml` (MJML markup), or `jsx` (React-Email JSX) — all converted into a clean, editable design. Pass `baseUrl` to resolve relative image paths. Optional `title`.

USAGE-metered: the agent’s actual token in/out is billed (no fixed price, no `X-Credit-Cost` header). The call gates on a non-empty credit balance. Returns `201` with the SAME shape as `POST /v1/emails`: `{ emailId, emailVersionId, html, previewImage? }`.



## OpenAPI

````yaml /api-reference/openapi-public-v1.yaml post /v1/emails/import
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/import:
    post:
      tags:
        - Emails
      summary: Import an email
      description: >-
        Converts existing markup into a NEW, fully EDITABLE Brew email design on
        the brand canvas. Brew rebuilds the markup into a clean, fully editable
        design, and EVERY external image is fetched, optimized, and RE-HOSTED on
        the Brew CDN (no hot-linking third-party assets).


        `content` is the raw markup as a STRING; `format` describes what you
        supply: `html` (an HTML email document or fragment), `mjml` (MJML
        markup), or `jsx` (React-Email JSX) — all converted into a clean,
        editable design. Pass `baseUrl` to resolve relative image paths.
        Optional `title`.


        USAGE-metered: the agent’s actual token in/out is billed (no fixed
        price, no `X-Credit-Cost` header). The call gates on a non-empty credit
        balance. Returns `201` with the SAME shape as `POST /v1/emails`: `{
        emailId, emailVersionId, html, previewImage? }`.
      operationId: importEmail
      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
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailImportRequest'
            examples:
              html:
                summary: Import an HTML email
                value:
                  format: html
                  title: Spring sale
                  content: >-
                    <html><body><h1>Spring sale</h1><p>20% off
                    everything.</p><img src="https://example.com/banner.png"
                    alt="banner"></body></html>
              mjml:
                summary: Import MJML markup
                value:
                  format: mjml
                  content: >-
                    <mjml><mj-body><mj-section><mj-column><mj-text>Spring sale —
                    20% off</mj-text></mj-column></mj-section></mj-body></mjml>
              jsx:
                summary: Import React-Email JSX
                value:
                  format: jsx
                  content: >-
                    <Html><Body><Container><Heading>Welcome</Heading><Text>Thanks
                    for joining.</Text></Container></Body></Html>
      responses:
        '201':
          description: >-
            The design was imported + persisted. Usage-metered: the agent’s
            actual token usage is charged. `emailVersionId` pins the exact
            version for sends + automation 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: content
        '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
        '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 markup could not be converted into a valid email (e.g. it failed
            to render, or produced no usable design).
          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_IMPORT_FAILED
                  type: invalid_request
                  message: >-
                    The supplied markup could not be imported as an email: the
                    content could not be rendered to a valid email.
                  suggestion: >-
                    Check that `content` is valid for the declared `format` and
                    retry.
                  docs: https://docs.brew.new/api-reference/api/errors
                  param: content
        '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:
    EmailImportRequest:
      type: object
      properties:
        format:
          type: string
          enum:
            - html
            - mjml
            - jsx
        content:
          type: string
          minLength: 1
          maxLength: 5000000
        title:
          type: string
          minLength: 1
          maxLength: 200
        baseUrl:
          type: string
          format: uri
      required:
        - format
        - content
      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

````