Skip to main content

​
Overview

The Brew Public API v1 lets your backend create on-brand email designs, deliver test or production sends, manage contacts, and run automations. Create and manage API keys at brew.new/settings/api. The API is organized around four ideas:
  1. Emails are pure designs. A design has no send state or message type. Generate, edit, restore, or reuse it, then send it as often as needed.
  2. A send is the unit of delivery and analytics. A send has one sendId and owns its delivery status and recipient events.
  3. Analytics is read-only reporting. It reads sends and their recipient events, with separate views for one-off sends, automations, and the event feed.
  4. Automations are event-driven graphs. A trigger starts a graph of sendEmail, wait, filter, and split nodes for each matching contact.
Use the API to:
  • Generate, import, edit, and inspect email designs with /v1/emails.
  • Send to a saved audience, an inline list, or one address with POST /v1/sends. Use { test: true } for a synchronous test to one inbox.
  • Read delivery and engagement data from /v1/analytics.
  • Define triggers, publish automation graphs, and fire them from your backend.
  • Manage contacts, custom fields, audiences, domains, and templates for the key’s brand.
Each API key is bound to exactly one brand and resolves that brand automatically. No public endpoint accepts brandId in a body or query string, and clients do not send X-Brand-Id. The public template catalog is the one organization-wide read. The complete scope and error behavior lives in Authentication. The full endpoint contract is generated from the OpenAPI specification, while this page explains how the pieces fit together.

​
Base URL

All public endpoints use the /v1 prefix. The OpenAPI document also lists http://localhost:3000/api for local development.

​
Discover the API Programmatically

These public endpoints let an agent inspect the contract before it has a key: The dashboard API Catalog runs supported operations and can copy the resulting cURL, TypeScript, SDK, or Python call.

​
Authentication

Every request needs a Brew API key. Send it in either header:
Keep keys on your server. Authentication owns the scope list, permission table, brand-scoping rules, and key lifecycle.

​
How the API Fits Together

One-off delivery and event-driven delivery use the same design and send resources:
  1. Design: POST /v1/emails creates a persisted design from a prompt.
  2. Send: POST /v1/sends delivers it to an audience, inline list, or single address. { test: true } uses the Brew sender and needs no verified domain, audience, or send row.
  3. Analyze: GET /v1/analytics/sends reports lifecycle and recipient events. The lifetime per-send analytics path is GET /v1/analytics/campaigns.
  4. Automate: create a trigger and graph, publish with PATCH /v1/automations/{automationId} and { "published": true }, then fire POST /v1/automations/triggers/{triggerEventId}/fire.
Both delivery modes write to the sends entity. One-off rows use the API identifier kind: campaign; automation rows use kind: automation.

​
Quick Start

Follow Send Your First Email from Code to create a key, check GET /v1/brand, generate a saved design, send a test, and open it in your inbox with raw cURL. It uses the same test: true path described above, so no verified domain is required.

​
Current Public v1 Surface

The generated Public API v1 reference is the source of truth for request and response shapes. This map shows the current paths at a glance.

​
Cross-Cutting Rules

The owner pages contain the contracts. Use Idempotency for retry keys and replay behavior, Credits for usage and fixed costs, Rate limits for windows and recovery, Response headers for request and rate-limit headers, and Errors for the error envelope and code catalog.

Public API v1

Browse the generated endpoint pages from the current OpenAPI spec.

TypeScript SDK

Use the official typed client for retries, idempotency, and resource methods.

API Catalog

Run a capability in the dashboard and copy the exact request.

Brew CLI

Call the same API from your terminal, a script, or a CI job.

​
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:

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 explore it further with ChatGPT or Claude.