API Introduction

The Brew Public API v1 lets your backend create email designs, send them, manage contacts, and run automations. For a terminal, Node application, or assistant, choose an interface first.

Base URL

https://brew.new/api

Every public endpoint starts with /v1. For example, GET /v1/brand means https://brew.new/api/v1/brand. The OpenAPI document also lists http://localhost:3000/api for local development.

Authentication

Create a key at Settings → API. Send it in either header:

Authorization: Bearer brew_your_api_key
X-API-Key: brew_your_api_key

A brand key resolves its own brand. An organization key selects one with X-Brand-Id. Brand-scoped endpoints reject brandId in a body or query string. Authentication owns permission scopes and key lifecycle; Organization and Brand Scope owns the credential and access rules.

Quick Start

Send Your First Email from Code checks brand readiness, creates a design, and sends a test with curl. No audience or verified domain is required for a test using Brew’s default sender.

How the API Fits Together

Task	Operation	Result
Generate a design	`POST /v1/emails`	Saved `emailId` and `emailVersionId`, or an explanatory `response`. Creating a design sends nothing.
Test the design	`POST /v1/sends` with `test: true`	Completed status and recipient; no production send row.
Deliver to subscribers	`POST /v1/sends` with a target and verified marketing domain	Accepted job with `sendId`. Acceptance is separate from delivery.
Monitor delivery	`GET /v1/sends/{sendId}?include=events`	The send row, lifetime `stats`, and a bounded event page.
Read brand reports	`GET /v1/analytics/{overview,automations,events}`	Totals, automation performance, or the unified event feed.
Start event-driven delivery	`POST /v1/automations/triggers/{triggerEventId}/fire`	Trigger instance and started automation run IDs. Requires a published automation.

For automations, create the trigger and graph, then publish with PATCH /v1/automations/{automationId} and { "published": true }. Event-driven transactional email uses a transactional-purpose domain on the automation. Emails and Automations explains the delivery modes. One-off production send rows retain the API identifier kind: campaign; automation rows use kind: automation. The Data Model maps designs, sends, triggers, runs, and events.

Current Public v1 Surface

The generated endpoint reference owns every request and response shape. Use its sidebar to find contacts, audiences, emails, sends, automations, domains, brand assets, media, and account operations. The API Catalog lets you try supported capabilities in Brew and copy their requests. Every operation on the surface, with the scope it needs and whether it costs credits, is in the table below. It is generated from the spec.

Every v1 operation

Method	Path	Summary	Scope	Credits	operationId
`GET`	`/v1/analytics/automations`	Automation performance	`automations`	no	`getAutomationAnalytics`
`GET`	`/v1/analytics/events`	Unified events feed	`emails`	no	`getEventsAnalytics`
`GET`	`/v1/analytics/overview`	Brand overview (totals, rates, timeseries)	`emails`	no	`getAnalyticsOverview`
`GET`	`/v1/api-keys`	List API keys	any key	no	`listApiKeys`
`POST`	`/v1/api-keys`	Create an API key	any key	no	`createApiKey`
`DELETE`	`/v1/api-keys/{keyId}`	Revoke an API key	any key	no	`revokeApiKey`
`GET`	`/v1/audiences`	List audiences	`audiences`	no	`listAudiences`
`POST`	`/v1/audiences`	Create an audience	`audiences`	no	`createAudience`
`DELETE`	`/v1/audiences/{audienceId}`	Delete an audience	`audiences`	no	`deleteAudience`
`GET`	`/v1/audiences/{audienceId}`	Get an audience	`audiences`	no	`getAudience`
`PATCH`	`/v1/audiences/{audienceId}`	Update an audience	`audiences`	no	`updateAudience`
`POST`	`/v1/audiences/{audienceId}/duplicate`	Duplicate an audience	`audiences`	no	`duplicateAudience`
`POST`	`/v1/audiences/from-events`	Create an audience from analytics events	`contacts`	no	`createAudienceFromEvents`
`GET`	`/v1/automations`	List automations	`automations`	no	`listAutomations`
`POST`	`/v1/automations`	Create an automation	`automations`	no	`createAutomation`
`DELETE`	`/v1/automations/{automationId}`	Delete an automation	`automations`	no	`deleteAutomation`
`GET`	`/v1/automations/{automationId}`	Get an automation	`automations`	no	`getAutomation`
`PATCH`	`/v1/automations/{automationId}`	Update or publish an automation	`automations`	no	`updateAutomation`
`POST`	`/v1/automations/{automationId}/run`	Run a manual-audience automation	`automations`	no	`runAutomation`
`POST`	`/v1/automations/{automationId}/test`	Test an automation	`automations`	no	`testAutomation`
`GET`	`/v1/automations/audience-runs`	List manual-audience runs	`automations`	no	`listAudienceRuns`
`GET`	`/v1/automations/audience-runs/{audienceRunId}`	Get a manual-audience run	`automations`	no	`getAudienceRun`
`POST`	`/v1/automations/audience-runs/{audienceRunId}/cancel`	Cancel a manual-audience run	`automations`	no	`cancelAudienceRun`
`POST`	`/v1/automations/audience-runs/{audienceRunId}/pause`	Pause a manual-audience run	`automations`	no	`pauseAudienceRun`
`POST`	`/v1/automations/audience-runs/{audienceRunId}/resume`	Resume a manual-audience run	`automations`	no	`resumeAudienceRun`
`GET`	`/v1/automations/runs`	List automation runs	`automations`	no	`listAutomationRuns`
`GET`	`/v1/automations/runs/{automationRunId}`	Get an automation run	`automations`	no	`getAutomationRun`
`POST`	`/v1/automations/runs/{automationRunId}/cancel`	Cancel an automation run	`automations`	no	`cancelAutomationRun`
`GET`	`/v1/automations/trigger-instances`	List trigger instances	`automations`	no	`listTriggerInstances`
`GET`	`/v1/automations/trigger-instances/{triggerInstanceId}`	Get a trigger instance	`automations`	no	`getTriggerInstance`
`GET`	`/v1/automations/triggers`	List triggers	`automations`	no	`listTriggers`
`POST`	`/v1/automations/triggers`	Create a trigger	`automations`	no	`createTrigger`
`DELETE`	`/v1/automations/triggers/{triggerEventId}`	Delete a trigger	`automations`	no	`deleteTrigger`
`GET`	`/v1/automations/triggers/{triggerEventId}`	Get a trigger	`automations`	no	`getTrigger`
`PATCH`	`/v1/automations/triggers/{triggerEventId}`	Update a trigger	`automations`	no	`updateTrigger`
`GET`	`/v1/automations/triggers/{triggerEventId}/contract`	Get a trigger payload contract	`automations`	no	`getTriggerContract`
`PUT`	`/v1/automations/triggers/{triggerEventId}/contract`	Declare a trigger payload contract	`automations`	no	`setTriggerContract`
`POST`	`/v1/automations/triggers/{triggerEventId}/contract/validate`	Validate a trigger payload	`automations`	no	`validateTriggerPayload`
`POST`	`/v1/automations/triggers/{triggerEventId}/fire`	Fire a trigger	`automations`	no	`fireTrigger`
`GET`	`/v1/automations/triggers/{triggerEventId}/readiness`	Check a trigger is ready to fire	`automations`	no	`checkTriggerReady`
`POST`	`/v1/automations/triggers/brew-events`	Get or create an unsubscribe trigger	`automations`	no	`ensureBrewEventTrigger`
`GET`	`/v1/brand`	Get the brand bound to this API key	any key	no	`getBrand`
`PATCH`	`/v1/brand`	Update brand identity + design system	`emails`	no	`updateBrand`
`GET`	`/v1/brand/images`	Get brand images	`emails`	yes	`getBrandImages`
`DELETE`	`/v1/brand/images/{assetId}`	Delete a brand image	`emails`	no	`deleteBrandImage`
`GET`	`/v1/brands`	List the brands this credential can reach	any key	no	`listBrands`
`POST`	`/v1/brands`	Create a brand and start its extraction	`brands`	no	`createBrand`
`GET`	`/v1/brands/{brandId}`	Get one brand’s lifecycle state	any key	no	`getBrandById`
`POST`	`/v1/canvas/sessions`	Create an authenticated email canvas embed session	`emails`	no	`createCanvasSession`
`DELETE`	`/v1/canvas/sessions/{sessionId}`	Revoke a canvas session	`emails`	no	`revokeCanvasSession`
`POST`	`/v1/canvas/sessions/{sessionId}/refresh`	Refresh a canvas session	`emails`	no	`refreshCanvasSession`
`GET`	`/v1/chats`	List chats	`emails`	no	`listChats`
`GET`	`/v1/chats/{chatId}`	Get chat context	`emails`	no	`getChatContext`
`GET`	`/v1/contacts`	List contacts	`contacts`	no	`listContacts`
`POST`	`/v1/contacts`	Create or update contacts	`contacts`	yes	`upsertContacts`
`DELETE`	`/v1/contacts/{email}`	Delete a contact	`contacts`	no	`deleteContact`
`GET`	`/v1/contacts/{email}`	Get a contact	`contacts`	no	`getContact`
`PATCH`	`/v1/contacts/{email}`	Update a contact	`contacts`	no	`updateContact`
`POST`	`/v1/contacts/batch-delete`	Batch-delete contacts	`contacts`	no	`batchDeleteContacts`
`POST`	`/v1/contacts/import-csv`	Bulk-import contacts from CSV	`contacts`	yes	`importContactsCsv`
`POST`	`/v1/contacts/search`	Get contacts	`contacts`	no	`searchContacts`
`POST`	`/v1/contacts/validate`	Validate email deliverability	`contacts`	yes	`validateContacts`
`POST`	`/v1/content/add-image`	Add image	`emails`	no	`addImage`
`POST`	`/v1/content/generate-image`	Generate an image	`emails`	yes	`generateImage`
`POST`	`/v1/content/gif`	Generate a GIF	`emails`	yes	`createGif`
`POST`	`/v1/content/html-to-png`	Render HTML to a PNG	`emails`	yes	`htmlToPng`
`POST`	`/v1/content/image-uploads`	Create an image upload	`emails`	no	`createImageUpload`
`POST`	`/v1/content/transform`	Transform an image	`emails`	yes	`transformImage`
`GET`	`/v1/domains`	List domains	`domains`	no	`listDomains`
`POST`	`/v1/domains`	Add a domain	`domains`	no	`addDomain`
`DELETE`	`/v1/domains/{domainId}`	Delete a domain	`domains`	no	`deleteDomain`
`GET`	`/v1/domains/{domainId}`	Get a domain	`domains`	no	`getDomain`
`PATCH`	`/v1/domains/{domainId}`	Update domain settings	`domains`	no	`updateDomain`
`GET`	`/v1/domains/{domainId}/health`	Get domain health	`domains`	no	`getDomainHealth`
`GET`	`/v1/domains/{domainId}/unsubscribes`	List a domain’s unsubscribes	`domains`	no	`listDomainUnsubscribes`
`POST`	`/v1/domains/{domainId}/unsubscribes`	Add addresses to a domain’s unsubscribe list	`domains`	no	`addDomainUnsubscribes`
`DELETE`	`/v1/domains/{domainId}/unsubscribes/{email}`	Remove an address from a domain’s unsubscribe list	`domains`	no	`removeDomainUnsubscribe`
`GET`	`/v1/domains/{domainId}/unsubscribes/export`	Export a domain’s unsubscribe list	`domains`	no	`exportDomainUnsubscribes`
`POST`	`/v1/domains/{domainId}/unsubscribes/import`	Import a CSV into a domain’s unsubscribe list	`domains`	no	`importDomainUnsubscribes`
`POST`	`/v1/domains/{domainId}/verify`	Verify a domain	`domains`	no	`verifyDomain`
`GET`	`/v1/email-groups`	List email groups	`emails`	no	`listEmailGroups`
`POST`	`/v1/email-groups`	Create an email group	`emails`	no	`createEmailGroup`
`DELETE`	`/v1/email-groups/{groupId}`	Delete an email group	`emails`	no	`deleteEmailGroup`
`GET`	`/v1/email-groups/{groupId}`	Get an email group	`emails`	no	`getEmailGroup`
`PATCH`	`/v1/email-groups/{groupId}`	Update an email group	`emails`	no	`updateEmailGroup`
`GET`	`/v1/emails`	List email designs	`emails`	no	`listEmails`
`POST`	`/v1/emails`	Generate an email design	`emails`	yes	`generateEmail`
`DELETE`	`/v1/emails/{emailId}`	Delete an email design	`emails`	no	`deleteEmail`
`GET`	`/v1/emails/{emailId}`	Get an email design	`emails`	no	`getEmail`
`PATCH`	`/v1/emails/{emailId}`	Edit an email design	`emails`	yes	`editEmail`
`POST`	`/v1/emails/{emailId}/client-previews`	Preview across clients & devices	`emails`	yes	`previewEmailAcrossClients`
`POST`	`/v1/emails/{emailId}/clone`	Clone an email design	`emails`	no	`cloneEmail`
`GET`	`/v1/emails/{emailId}/comments`	List email comments	`emails`	no	`listEmailComments`
`POST`	`/v1/emails/{emailId}/export`	Export a design to an ESP	`emails`	no	`exportEmailDesign`
`GET`	`/v1/emails/{emailId}/inbox-placement-tests`	List inbox placement tests	`emails`	no	`listInboxPlacementTests`
`POST`	`/v1/emails/{emailId}/inbox-placement-tests`	Run an inbox placement test	`emails`	yes	`createInboxPlacementTest`
`GET`	`/v1/emails/{emailId}/inbox-placement-tests/{testId}`	Get inbox placement test results	`emails`	no	`getInboxPlacementTest`
`POST`	`/v1/emails/{emailId}/restore`	Restore a historical version	`emails`	no	`restoreEmailVersion`
`POST`	`/v1/emails/audit`	Audit an email	`emails`	yes	`auditEmail`
`GET`	`/v1/emails/audits/{auditId}`	Read a saved email audit	`emails`	no	`getEmailAudit`
`GET`	`/v1/emails/client-previews/{previewId}`	Read email rendering progress	`emails`	no	`getEmailRendering`
`POST`	`/v1/emails/figma`	Import a Figma frame	`emails`	no	`importFigmaDesign`
`POST`	`/v1/emails/import`	Import an email	`emails`	no	`importEmail`
`GET`	`/v1/fields`	List contact fields	`contacts`	no	`listContactFields`
`POST`	`/v1/fields`	Create a contact field	`contacts`	no	`createContactField`
`DELETE`	`/v1/fields/{fieldName}`	Delete a contact field	`contacts`	no	`deleteContactField`
`GET`	`/v1/fields/{fieldName}`	Get a contact field	`contacts`	no	`getContactField`
`GET`	`/v1/flows`	List flows	any key	no	`listFlows`
`GET`	`/v1/flows/{slug}`	Get a flow	any key	no	`getFlow`
`GET`	`/v1/health`	Liveness probe	none (no auth)	no	`getHealth`
`GET`	`/v1/help`	Machine-readable API catalog	none (no auth)	no	`getHelp`
`GET`	`/v1/insights`	List insights	`emails`	no	`listInsights`
`GET`	`/v1/insights/{insightId}`	Get an insight	`emails`	no	`getInsight`
`GET`	`/v1/integrations`	List integrations	any key	no	`listIntegrations`
`GET`	`/v1/notifications`	List notifications	any key	no	`listNotifications`
`POST`	`/v1/payload-contracts/infer`	Infer a payload contract from an example	any key	no	`inferPayloadContract`
`GET`	`/v1/sends`	List sends	`sends`	no	`listSends`
`POST`	`/v1/sends`	Send an email	`sends`	no	`createSend`
`GET`	`/v1/sends/{sendId}`	Get a send	`sends`	no	`getSend`
`POST`	`/v1/sends/{sendId}/cancel`	Cancel a send	`sends`	no	`cancelSend`
`POST`	`/v1/sends/{sendId}/pause`	Pause a gradual send	`sends`	no	`pauseSend`
`POST`	`/v1/sends/{sendId}/resume`	Resume a paused gradual send	`sends`	no	`resumeSend`
`GET`	`/v1/templates`	List templates	any key	no	`listTemplates`
`GET`	`/v1/templates/{templateId}`	Get a public template	any key	no	`getTemplate`
`GET`	`/v1/usage`	Get usage	any key	no	`getUsage`

Discover the API Programmatically

These endpoints work without a key:

Endpoint	Returns
`GET /v1/help`	Authentication, scopes, limits, credit costs, errors, and the endpoint catalog.
`GET /v1/llms.txt`	The API surface as prose for agents.
`GET /v1/health`	Liveness `status` and `version`.

The canonical OpenAPI document is public-api-v1.yaml.

Cross-Cutting Rules

Each shared contract has one owner:

Authentication and Organization and Brand Scope: permissions and credential scope.
Errors: error envelope, codes, and recovery.
Idempotency: retry keys, replay windows, and conflicts.
Pagination and Batch Operations: cursors and bulk work.
Async Jobs: follow accepted work through completion.
Rate Limits, Credits, and Response Headers: limits, costs, and diagnostics.
v1 Migration: replace older routes and response shapes.

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.

Ask ChatGPT or Claude

Click here to open the Copy page menu at the top of this page, then send the page to ChatGPT, Claude, or your editor.

Start Here

Public API v1

API Contracts

API Guides

MCP Server

CLI

SDKs

Base URL

Authentication

Quick Start

How the API Fits Together

Current Public v1 Surface

Discover the API Programmatically

Cross-Cutting Rules

Need Help?

Search Documentation

Ask ChatGPT or Claude

Schedule a Call

Call Us Directly

Slack Channel

Email Support

​Base URL

​Authentication

​Quick Start

​How the API Fits Together

​Current Public v1 Surface

​Discover the API Programmatically

​Cross-Cutting Rules

​Need Help?

Search Documentation

Ask ChatGPT or Claude

Schedule a Call

Call Us Directly

Slack Channel

Email Support

Base URL

Authentication

Quick Start

How the API Fits Together

Current Public v1 Surface

Discover the API Programmatically

Cross-Cutting Rules

Need Help?