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",
  "assetReport": {
    "discovered": 1,
    "rehosted": 1,
    "retained": 0,
    "stripped": 0,
    "warnings": []
  },
  "group": null
}

{
  "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_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": "EMAIL_GROUP_NOT_FOUND",
    "type": "not_found",
    "message": "No email group exists with id 'grp_missing'.",
    "suggestion": "List groups with GET /v1/email-groups. Cross-brand ids surface as 404 to avoid leaking existence.",
    "docs": "https://docs.brew.new/api-reference/api/errors",
    "param": "targetGroupId"
  }
}

{
  "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": "PAYLOAD_TOO_LARGE",
    "type": "invalid_request",
    "message": "content must not exceed 5000000 UTF-8 bytes",
    "suggestion": "Reduce the payload size and retry.",
    "docs": "https://docs.brew.new/api-reference/api/errors",
    "param": "content"
  }
}

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

Emails

Import an email

Converts existing markup into a NEW, fully EDITABLE Brew email design on the brand canvas. Brew preserves source structure and attempts to rehost every discoverable safe public resource. If rehosting fails, a validated public URL may be retained with a warning; private, malformed, and blocked references are stripped.

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 and subjectLine (the design-default inbox subject).

FREE — no model and no credits. Conversion is a deterministic compiler, so there is no token spend to meter and no credit gate. Normal request limits still apply: 5,000,000 UTF-8 bytes, 256 remote resources, 8 concurrent fetches, 10 MB per resource, and 50 MB aggregate downloads. Optional targetGroupId (grp_… or ungrouped) or targetGroupName (resolve-or-create) — not both; omit to land Ungrouped. Unknown targetGroupId → 404 EMAIL_GROUP_NOT_FOUND. Returns 201 with { emailId, emailVersionId, html, previewImage?, assetReport, group, subjectLine? }.

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",
  "assetReport": {
    "discovered": 1,
    "rehosted": 1,
    "retained": 0,
    "stripped": 0,
    "warnings": []
  },
  "group": null
}

{
  "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_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": "EMAIL_GROUP_NOT_FOUND",
    "type": "not_found",
    "message": "No email group exists with id 'grp_missing'.",
    "suggestion": "List groups with GET /v1/email-groups. Cross-brand ids surface as 404 to avoid leaking existence.",
    "docs": "https://docs.brew.new/api-reference/api/errors",
    "param": "targetGroupId"
  }
}

{
  "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": "PAYLOAD_TOO_LARGE",
    "type": "invalid_request",
    "message": "content must not exceed 5000000 UTF-8 bytes",
    "suggestion": "Reduce the payload size and retry.",
    "docs": "https://docs.brew.new/api-reference/api/errors",
    "param": "content"
  }
}

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

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

Minimum string length: 1

title

string

Required string length: 1 - 200

subjectLine

string

Inbox subject line to set on the design (subjectLine — distinct from title, the canvas name). Sends still take an explicit per-send subject; this is the design's default, seeded into the send dialog and returned by GET /v1/emails?emailId=.

Required string length: 1 - 250

baseUrl

string<uri>

targetGroupId

string

Existing canvas group id (grp_…), or ungrouped. Mutually exclusive with targetGroupName.

Required string length: 1 - 64

targetGroupName

string

Resolve-or-create a group by this name. Mutually exclusive with targetGroupId.

Required string length: 1 - 60

Response

The design was imported + persisted. Free — no model runs. 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

group

object | null

required

Show child attributes

assetReport

object

required

Show child attributes

previewImage

string<uri>

subjectLine

string

⌘I

Get started

Overview

Core concepts

Guides

MCP server

CLI

Public API v1

Import an email

Authorizations

Headers

Body

Response