Skip to main content
POST
/
v1
/
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

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>