Skip to main content
POST
/
v1
/
emails
curl --request POST \
  --url https://brew.new/api/v1/emails \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "Create a welcome email for new customers who joined Brew today."
}
'
{
  "response": "No email was generated."
}
{
  "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": "prompt"
  }
}
{
  "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": "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"
  }
}
{
  "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": "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"
  }
}
{
  "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

Generation prompt plus optional source URLs / reference design. The brand is resolved from the API key and must not be passed.

​
prompt
string
required
Minimum string length: 1
​
contentUrls
string<uri>[]
Maximum array length: 8
​
referenceEmailId
string
​
category
enum<string>

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.

Available options:
welcome,
newsletter,
promotional,
product-launch,
product-update,
cart-abandonment,
event-invitation,
event-reminder,
feedback-request,
re-engagement,
referral,
business,
internal,
general

Response

The agent answered in prose without writing a design ({ response }).

​
response
string
required
Minimum string length: 1