curl --request POST \
  --url https://brew.new/api/v1/emails/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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>"
}
'

{
  "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"
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
    }
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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
  }
}

{
  "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"
  }
}

{
  "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
  }
}

Emails

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? }.

POST

emails

import

curl --request POST \
  --url https://brew.new/api/v1/emails/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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>"
}
'

{
  "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"
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
    }
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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
  }
}

{
  "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"
  }
}

{
  "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
  }
}

Authorizations

Authorization

string

header

default:Bearer brew_your_api_key

required

Send your Brew API key as Authorization: Bearer brew_xxx.

Headers

Idempotency-Key

string

Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.

Required string length: 1 - 100

X-Brand-Id

string

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.

Required string length: 1 - 64

Body

application/json

format

enum<string>

required

Available options:

html,

mjml,

jsx

content

string

required

Required string length: 1 - 5000000

title

string

Required string length: 1 - 200

baseUrl

string<uri>

Response

The design was imported + persisted. Usage-metered: the agent’s actual token usage is charged. emailVersionId pins the exact version for sends + automation nodes.

emailId

string

required

Minimum string length: 1

emailVersionId

string

required

Minimum string length: 1

html

string

required

previewImage

string<uri>

⌘I

Overview

Core concepts

Guides

MCP server

Public API v1

Import an email

Authorizations

Headers

Body

Response