API Introduction

Overview

Brew Public API v1 gives you programmatic access to the same core flows that power the product. Use it to:

Manage contacts and contact fields.
List saved audiences.
List verified sending domains.
Generate and list emails.
List public templates.
Start send jobs for saved emails.

Brand management lives in the Brew dashboard — the public API does not expose endpoints to create, list, or edit brands. Each API key is bound to exactly one brand at creation time and can never be retargeted later. A brand can have any number of keys (dev, staging, production, per-service, per-teammate); each one acts on the same single brand it was created against. Need a key for a different brand? Switch brands in the dashboard and create a new key. Create and manage your API keys at brew.new/settings/api. The full endpoint reference in this docs site is generated from Brew’s OpenAPI source of truth. That means the human-written overview on this page explains the flow. The generated endpoint pages explain the exact request and response contract.

Base URL

https://brew.new/api

All current public endpoints are under the /v1 prefix.

Authentication

Every request needs a Brew API key. Create and manage keys at brew.new/settings/api. You can send it in either header:

Authorization: Bearer brew_your_api_key

X-API-Key: brew_your_api_key

Keep API keys on your server only. Do not put them in browser code.

Brand Scoping

Every API key is bound to exactly one brand at creation time. The brand is resolved from the key on every request — no public endpoint accepts a brandId field in its request body or query string. To operate on a different brand, switch brands in the dashboard at brew.new/settings/api and create a new key for that brand.

Scope	Endpoints	Behavior
Brand-scoped (filtered to the key brand automatically)	`GET/POST/PATCH/DELETE /v1/contacts`, `GET/POST/DELETE /v1/fields`, `GET /v1/audiences`, `GET /v1/domains`, `GET/POST /v1/emails`, `PATCH /v1/emails/{emailId}`, `POST /v1/sends`	Reads filter to the key brand. Mutations write only to the key brand. Cross-brand `emailId` / `audienceId` references on `PATCH /v1/emails/{emailId}` and `POST /v1/sends` surface as `404` (not `403`) so the API never confirms the existence of resources in another brand.
Organization-wide (not constrained to a brand)	`GET /v1/templates`	Returns the public template catalog.

If you send a brandId field — body or query — to any /v1/* endpoint, the request fails with 400 INVALID_REQUEST and param: "brandId". Strip the field; the brand always comes from the key. Brands themselves are managed only in the Brew dashboard. The public API does not expose endpoints to create, list, or update brands.

Permission Scopes

Each API key carries a list of permission scopes. The dashboard defaults new keys to all. Routes require either the listed scope or all:

Permission	Endpoints
`contacts`	`GET /v1/contacts`, `POST /v1/contacts`, `PATCH /v1/contacts`, `DELETE /v1/contacts`, `GET /v1/fields`, `POST /v1/fields`, `DELETE /v1/fields`, `GET /v1/audiences`
`emails`	`GET /v1/domains`, `GET /v1/emails`, `POST /v1/emails`, `GET /v1/templates`, `POST /v1/sends`
`all`	every endpoint above

Sending a request with a key that lacks the required permission returns 403 INSUFFICIENT_PERMISSIONS with the missing scope name in the error envelope’s param field.

Quick Start

Get an API key

Go to brew.new/settings/api and create a key. The key is bound to whatever brand is active in the dashboard at creation time — switch brands first if you want a key for a different brand.

Check that auth works

Use a simple read endpoint like domains:

curl -H "Authorization: Bearer brew_your_api_key" \
  https://brew.new/api/v1/domains

Generate an email

Create a saved email with a prompt:

curl -X POST "https://brew.new/api/v1/emails" \
  -H "Authorization: Bearer brew_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: email-generate-001" \
  -d '{
    "prompt": "Create a welcome email for new subscribers"
  }'

Send it

Use the returned emailId and one verified domainId:

curl -X POST "https://brew.new/api/v1/sends" \
  -H "Authorization: Bearer brew_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-001" \
  -d '{
    "emailId": "email_123",
    "domainId": "domain_123",
    "subject": "Welcome to Brew",
    "emails": ["user@example.com"]
  }'

How The API Fits Together

Think about the API in four parts.

Recipient Data

GET /v1/contacts
POST /v1/contacts
PATCH /v1/contacts
DELETE /v1/contacts
GET /v1/fields
POST /v1/fields
DELETE /v1/fields
GET /v1/audiences

Use these endpoints to manage contacts, custom contact fields, and saved audience groups.

Sender Identity

GET /v1/domains

Domains give sends a verified sender identity. Brand design context is automatic — every API key is bound to a brand created in the Brew dashboard, and email generation grounds itself in that brand.

Email Creation

GET /v1/emails
POST /v1/emails
GET /v1/templates

Templates are public reference emails. Emails are your org’s saved generated emails.

Delivery

POST /v1/sends

Sends are asynchronous. The API accepts the send job and returns a queued or scheduled result with a runId.

Current Public v1 Surface

Method	Endpoint	Purpose
`GET`	`/v1/contacts`	List contacts, count contacts, or look up one contact by email
`POST`	`/v1/contacts`	Upsert one or many contacts
`PATCH`	`/v1/contacts`	Patch a contact
`DELETE`	`/v1/contacts`	Delete one or many contacts
`GET`	`/v1/fields`	List contact fields
`POST`	`/v1/fields`	Create a contact field
`DELETE`	`/v1/fields`	Delete a contact field
`GET`	`/v1/audiences`	List saved audiences
`GET`	`/v1/domains`	List verified sending domains
`GET`	`/v1/emails`	List latest saved emails
`POST`	`/v1/emails`	Generate a new email
`PATCH`	`/v1/emails/{emailId}`	Edit a saved email; persists a fresh `version: "latest"` row and demotes the previous head
`GET`	`/v1/templates`	List public templates
`POST`	`/v1/sends`	Start a send job

Idempotency

POST endpoints support idempotency with the Idempotency-Key header. PATCH /v1/emails/{emailId} also accepts an Idempotency-Key for safe edit replays (the SDK does not auto-generate one for PATCH; callers opt in by passing the header). Use it on:

POST /v1/contacts
POST /v1/fields
POST /v1/emails
PATCH /v1/emails/{emailId}
POST /v1/sends

If you retry the same request with the same key and the same body, Brew returns the original response instead of doing the work twice.

Rate Limits And Debugging Headers

Successful responses include helpful headers:

x-request-id
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

When you contact support, always include the x-request-id.

TypeScript SDK

If you prefer typed wrappers over raw HTTP, Brew also ships an official TypeScript SDK.

TypeScript SDK

Use @brew.new/sdk for typed requests, retries, idempotency, and a resource-oriented client surface.

Public API v1 Reference

Browse the generated endpoint pages from the current OpenAPI spec.

Public API v1

Browse every generated endpoint page from the current OpenAPI spec.

SDK Overview

Start with the official TypeScript SDK.

Need Help?

Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you:

Self-Service Tools
Talk to Our Team

Search Documentation

Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.

ChatGPT/Claude Integration

Click “Open in ChatGPT” at the top right of any page to analyze documentation with ChatGPT or Claude for deeper insights.

Overview

Public API v1

Overview

Base URL

Authentication

Brand Scoping

Permission Scopes

Quick Start

How The API Fits Together

Recipient Data

Sender Identity

Email Creation

Delivery

Current Public v1 Surface

Idempotency

Rate Limits And Debugging Headers

TypeScript SDK

TypeScript SDK

Public API v1 Reference

What To Read Next

Public API v1

SDK Overview

Need Help?

Search Documentation

ChatGPT/Claude Integration

Schedule a Call

Call Us Directly

Slack Channel

Email Support

Overview

Public API v1

Documentation Index

​Overview

​Base URL

​Authentication

​Brand Scoping

​Permission Scopes

​Quick Start

​How The API Fits Together

​Recipient Data

​Sender Identity

​Email Creation

​Delivery

​Current Public v1 Surface

​Idempotency

​Rate Limits And Debugging Headers

​TypeScript SDK

TypeScript SDK

Public API v1 Reference

​What To Read Next

Public API v1

SDK Overview

​Need Help?

Search Documentation

ChatGPT/Claude Integration

Schedule a Call

Call Us Directly

Slack Channel

Email Support

Overview

Base URL

Authentication

Brand Scoping

Permission Scopes

Quick Start

How The API Fits Together

Recipient Data

Sender Identity

Email Creation

Delivery

Current Public v1 Surface

Idempotency

Rate Limits And Debugging Headers

TypeScript SDK

What To Read Next

Need Help?