# Brew Help Docs - [Welcome to Brew](https://docs.brew.new/get-started/welcome.md): Brew is the AI-native email platform for modern teams and AI agents. Describe the email and Brew designs it on brand, builds the audience, and sends it. - [Add Your Brand](https://docs.brew.new/get-started/add-your-brand.md): Brew extracts your brand from your website in about 30 seconds and writes it up as email-design.md, a brand file you can edit. Every email starts on-brand. - [Send Your First Email](https://docs.brew.new/get-started/send-your-first-email.md): Send your first on-brand email in Brew, refine it with one prompt, and receive a test in your inbox when you're new to the app. - [Verify Your Sending Domain](https://docs.brew.new/get-started/verify-your-sending-domain.md): Add your sending domain and its DNS records so Brew can send on your behalf, either automatically through Entri or by hand. About five minutes. - [What You Can Send With Brew](https://docs.brew.new/get-started/what-you-can-send.md): Brew is built for permission-based marketing email and transactional sends. Here's what qualifies, what doesn't, and the limits Brew enforces. - [The Interface](https://docs.brew.new/create-emails/the-interface.md): A map of the Brew interface: the chat, how canvases work, and where Emails, Automations, imports, and settings live, with links to each. - [Emails vs Automations](https://docs.brew.new/create-emails/emails-vs-automations.md): Brew builds two types of email, one-off Emails and triggered Automations. Here is how to tell which one a given job needs before you build it. - [Emails](https://docs.brew.new/create-emails/emails.md): One-off emails you write, schedule, and send to a saved audience. Other tools call these campaigns, and Brew generates them from a prompt. - [Automations](https://docs.brew.new/create-emails/automations.md): Reference for Brew automations, including nodes, triggers, lifecycle states, merge tags, connected events, and validation errors. - [Build an Automation](https://docs.brew.new/create-emails/build-an-automation.md): Create, test, and publish event-triggered email flows in Brew before they reach real contacts when you need reliable lifecycle email. - [Prompt Guide](https://docs.brew.new/create-emails/prompt-guide.md): How to write prompts that produce great emails on the first try: structure, mentions, attachments, and multi-output prompting in Brew. - [Templates](https://docs.brew.new/create-emails/templates.md): Browse emails from other brands or save your own, then let Brew remix any template into a new email that already matches your brand. - [Merge Tags](https://docs.brew.new/create-emails/merge-tags.md): Reference for Brew merge tags and Liquid templating: syntax, fallbacks, nested payloads, which fields resolve, and what renders when one doesn't. - [Email Tools](https://docs.brew.new/create-emails/email-tools.md): The tools Brew uses behind the scenes when generating an email, covering brand and design, images, email creation, and live research. - [Preview in Real Inboxes](https://docs.brew.new/create-emails/preview-in-real-inboxes.md): Render a design across real email clients (Gmail, Outlook, Apple Mail, iOS, and Yahoo) and get a screenshot per client before you send. - [Audit an Email](https://docs.brew.new/create-emails/audit-email.md): Audit an email before sending to catch broken links, missing unsubscribe content, oversized assets, copy problems, and accessibility issues. - [Comments](https://docs.brew.new/create-emails/comments.md): Leave comments on any element of an email so your team can review and approve in Brew, with tagged teammates notified by email. - [Send Options](https://docs.brew.new/create-emails/send-options.md): Four ways to time a send: right away, at a scheduled time, inside delivery windows, or ramped gradually to warm up a domain. - [Brand Identity](https://docs.brew.new/brand/brand-identity.md): Manage your brand's details, links, email design system, and image style in one place, so every email Brew generates inherits them. - [Assets](https://docs.brew.new/brand/assets.md): Find, upload, edit, and delete the logos and images Brew puts in your emails, on the Assets page or from an agent over MCP and the API. - [Set a Design Baseline](https://docs.brew.new/brand/design-baseline.md): Everything about email-design.md and image-style.md: what they contain, and how to shape them, including from an email you already like. - [Unsubscribe page](https://docs.brew.new/brand/unsubscribe.md): Customize the page subscribers land on when they opt out, and review unsubscribe reasons and volume for the brand in one view. - [Multiple Brands](https://docs.brew.new/brand/multiple-brands.md): Run more than one brand from a single Brew account, each with its own identity, audience, domain, and API key. Every plan includes multiple brand workspaces. - [Inbox Icons](https://docs.brew.new/brand/inbox-icons.md): Show your brand logo or a personal photo beside your emails in recipients' inboxes, which lifts recognition and open rates before anyone reads a word. - [Add Contacts](https://docs.brew.new/audience/add-contacts.md): Bring opted-in contacts into Brew by CSV upload, manual entry, a connected integration, or the API, with optional validation as they arrive. - [Manage Contacts](https://docs.brew.new/audience/manage-contacts.md): Manage contact properties, read a contact's full activity timeline, handle unsubscribes, and keep your audience clean over time. - [Validate Contacts](https://docs.brew.new/audience/validate-contacts.md): Check any address before you send. Each contact comes back valid, risky, or invalid, and the verdict is saved on the contact. - [Create Audiences](https://docs.brew.new/audience/create-audiences.md): Segment your contacts to send the right email to the right people. Describe the audience in plain English or build filters by hand. - [Audience Hygiene](https://docs.brew.new/audience/audience-hygiene.md): Keep your contact list clean and engaged so your emails reach the inbox, using validation, engagement tiers, and regular re-engagement. - [Reading Analytics](https://docs.brew.new/analytics/reading-analytics.md): Analytics opens as a list of your one-time sends and live Automations, with click-through detail pages and an Events log behind every number. - [Key Metrics](https://docs.brew.new/analytics/key-metrics-and-terms.md): Every metric in Brew analytics with its formula and how it's tracked, covering open, click, conversion, bounce, complaint, and unsubscribe rate. - [Glossary](https://docs.brew.new/analytics/glossary.md): Plain definitions for the email marketing terms you'll meet across Brew, from authentication and deliverability to segments and suppression. - [Settings](https://docs.brew.new/settings/settings.md): Manage your Brew account from one page: sending domains, API keys, MCP connections, AI model choice, and usage and credits across your workspace. - [Plans and Limits](https://docs.brew.new/settings/plans-and-limits.md): Every Brew plan with its monthly AI credits, email sends, sending domains, and brand workspaces, so you or your agent can pick a tier without opening the app. - [Security & Compliance](https://docs.brew.new/security-and-compliance.md): How Brew protects your data: security practices, encryption, GDPR compliance, subprocessors, and acceptable use standards for sending. - [Brew University](https://docs.brew.new/brew-university.md): Eight short video walkthroughs covering brand setup, email creation, audiences, automations, and MCP, so you can learn Brew by watching. - [Video: Extract Your Brand and Create On-Brand Emails](https://docs.brew.new/brew-university/extract-your-brand.md): Four-minute video walkthrough of brand setup in Brew, the companion to the Add Your Brand guide, from website import to your email design MD. - [Video: Create Consistent On-Brand Email Designs](https://docs.brew.new/brew-university/consistent-email-designs.md): Eight-minute video on refining a design until it is repeatable, the companion to the Design Baseline guide on golden references and design MD updates. - [Video: Create, Edit, and Send Emails](https://docs.brew.new/brew-university/create-edit-send-emails.md): Six-minute video of the full loop from prompt to analytics, the companion to the Send Your First Email guide, ending on the four delivery options. - [Video: Check Your Email Rendering and Inbox Placement](https://docs.brew.new/brew-university/rendering-and-inbox-placement.md): Five-minute video on pre-send checks in Brew, the companion to the Preview in Real Inboxes guide, covering render previews and placement tests. - [Video: Import Contacts and Create Targeted Audiences](https://docs.brew.new/brew-university/import-contacts-and-audiences.md): Five-minute video on importing a CSV and building reusable audiences, the companion to the Add Contacts and Create Audiences guides. - [Video: Set Up Powerful Email Automations](https://docs.brew.new/brew-university/email-automations.md): Seven-minute video walking a failed-payment flow end to end, the companion to the Build an Automation guide, covering wait, filter, and split nodes. - [Video: Import Figma, HTML, and Inbox Emails](https://docs.brew.new/brew-university/import-designs.md): Four-minute video on three ways to bring an existing design into Brew, the companion to the Templates guide: Figma URL, pasted HTML, or forwarding. - [Video: Connect Claude with MCP](https://docs.brew.new/brew-university/connect-claude-with-mcp.md): Eight-minute video on adding Brew to Claude Desktop over MCP, the companion to the Connect Your Client guide, ending with a scheduled send. - [Build a Welcome Flow](https://docs.brew.new/recipes/build-a-welcome-flow.md): Set up a multi-step onboarding sequence that runs automatically every time someone signs up, from the trigger event through to the final email. - [Send a Segmented Newsletter](https://docs.brew.new/recipes/send-a-segmented-newsletter.md): Generate one weekly digest and tailor it to several audience segments, so each group gets a version that fits. No code required. - [Run a One-Off Flow to a Saved Audience](https://docs.brew.new/recipes/run-a-one-off-flow.md): Use a manual-audience automation to send a multi-step sequence (waits, filters, splits and all) to a saved audience, on demand. - [Lifecycle Emails for SaaS and B2B](https://docs.brew.new/recipes/lifecycle-emails-saas-b2b.md): The six lifecycle emails every software company should be sending, from welcome through dunning and winback, with the prompts to build each one. - [Lifecycle Emails for E-Commerce](https://docs.brew.new/recipes/lifecycle-emails-ecommerce.md): The emails every store should be sending (welcome, receipts, abandoned cart, shipping, win-back) and the prompts to build them in Brew. - [QA an Email Before a Big Send](https://docs.brew.new/recipes/qa-before-a-big-send.md): A pre-send routine that catches broken layouts, dead links, missing unsubscribe content, and copy problems before an email leaves. - [Launch from a Waitlist](https://docs.brew.new/recipes/launch-from-a-waitlist.md): Confirm every waitlist signup the moment they join, keep them warm, and run the launch-day sequence when you open the doors. - [Run Your Email Ops from an AI Agent](https://docs.brew.new/recipes/run-brew-from-an-ai-agent.md): Connect Brew to ChatGPT, Claude, Grok, Cursor, or Codex over MCP, then draft, QA, and send an email without ever leaving the chat window. - [Create in Brew, Send From HubSpot](https://docs.brew.new/recipes/create-in-brew-send-from-hubspot.md): Keep HubSpot as your CRM and sending platform while Brew handles email creation, so every send stays on brand without a designer. - [Migrate From Mailchimp to Brew](https://docs.brew.new/migrations/mailchimp.md): Move contacts, consent states, segments, templates, and automations from Mailchimp into Brew, with a cutover order that avoids double-sends. - [Migrate From Brevo to Brew](https://docs.brew.new/migrations/brevo.md): Move email contacts, templates, segments, and automations from Brevo into Brew, including the API swap and what to do with SMS, WhatsApp, and CRM. - [Migrate From Customer.io to Brew](https://docs.brew.new/migrations/customerio.md): Move profiles, Liquid templates, event-driven segments, and API calls from Customer.io into Brew, with a cutover order that avoids double-sends. - [Migrate From Loops to Brew](https://docs.brew.new/migrations/loops.md): Move contacts, campaigns, workflows, and transactional sends from Loops into Brew, with the API swap and a cutover order that avoids double-sends. - [Integrations](https://docs.brew.new/integrations/integrations.md): Connect Brew to the ESPs, auth providers, commerce platforms, design tools, and AI agents you already run, and see what each connection does. - [Braze](https://docs.brew.new/integrations/export/braze.md): Export email templates directly to Braze, ready to use in your Braze campaigns and Canvases. Design in Brew, export in one click. - [Brevo](https://docs.brew.new/integrations/export/brevo.md): Connect Brevo (formerly Sendinblue) with one-click OAuth to export Brew templates as marketing or transactional templates. - [Customer.io](https://docs.brew.new/integrations/export/customerio.md): Deliver any Brew email through your Customer.io account with an App API key, and import templates into Design Studio manually when you need them. - [HubSpot](https://docs.brew.new/integrations/export/hubspot.md): Connect HubSpot with one-click OAuth and push Brew emails into Marketing Hub, so you design in Brew and keep sending inside HubSpot. - [Iterable](https://docs.brew.new/integrations/export/iterable.md): Export email templates directly to Iterable, ready to use in your Iterable campaigns and journeys. Design in Brew, export in one click. - [Klaviyo](https://docs.brew.new/integrations/export/klaviyo.md): Connect Klaviyo with one-click OAuth and export Brew emails as reusable CODE templates, keeping your sending and flows where they already run. - [Mailchimp](https://docs.brew.new/integrations/export/mailchimp.md): Connect Mailchimp with one-click OAuth and export Brew emails as ready-to-use templates, keeping your sending and audiences where they already run. - [Mailgun](https://docs.brew.new/integrations/export/mailgun.md): Export email templates from Brew straight into Mailgun for transactional and marketing sends, so design happens here and delivery stays there. - [Mailjet](https://docs.brew.new/integrations/export/mailjet.md): Export email templates from Brew straight into Mailjet for marketing and transactional sends, so design happens here and delivery stays there. - [OneSignal](https://docs.brew.new/integrations/export/onesignal.md): Export email templates directly to OneSignal, ready to use in your OneSignal email campaigns and automations. Design in Brew, export in one click. - [Postmark](https://docs.brew.new/integrations/export/postmark.md): Export email templates from Brew straight into Postmark for transactional and broadcast sends, so design happens here and delivery stays there. - [Twilio SendGrid](https://docs.brew.new/integrations/export/sendgrid.md): Export emails from Brew to Twilio SendGrid as dynamic templates, ready to send from your SendGrid account. Setup takes a few minutes. - [Clerk](https://docs.brew.new/integrations/import/clerk.md): Trigger Brew automations from Clerk webhook events, user signups, organization changes, paid subscriptions, and waitlist entries. - [RevenueCat](https://docs.brew.new/integrations/import/revenuecat.md): Trigger Brew automations from RevenueCat purchase, renewal, cancellation, and billing-issue events across App Store, Play Store, Stripe, and Web Billing. - [Shopify](https://docs.brew.new/integrations/import/shopify.md): Trigger Brew automations from Shopify customer, order, checkout, cart, and fulfillment events, and sync shopper data onto your contacts as it arrives. - [Stripe](https://docs.brew.new/integrations/import/stripe.md): Trigger Brew automations from Stripe events like new subscriptions, failed payments, and cancellations, with billing context synced onto each contact. - [Stytch](https://docs.brew.new/integrations/import/stytch.md): Trigger Brew automations from Stytch Consumer or B2B webhook events, user lifecycle, member changes, and organization activity. - [Supabase](https://docs.brew.new/integrations/import/supabase.md): Trigger Brew automations from Supabase auth events including signups, email confirmation, password changes, and bans, with user data synced as they fire. - [WorkOS](https://docs.brew.new/integrations/import/workos.md): Trigger Brew automations from WorkOS user, authentication, password-reset, organization, SCIM, and invitation events across your enterprise auth stack. - [Figma](https://docs.brew.new/integrations/import/figma.md): Connect your design tool so you can paste a frame URL into chat and get a responsive, on-brand email back without rebuilding the layout by hand. - [Slack](https://docs.brew.new/integrations/import/slack.md): Create and edit emails from your team chat with the Brew assistant, so a draft can go from idea to review without anyone opening the app. - [Typeform](https://docs.brew.new/integrations/import/typeform.md): Pull survey responses into Brew so your emails reflect what your audience is actually saying, and so a submission can trigger a follow-up. - [Use Brew With AI Agents](https://docs.brew.new/integrations/ai-agents/use-brew-with-ai-agents.md): Wire Brew into any AI agent or the app it builds, over MCP, the TypeScript SDK, or the REST API, with a pattern for each. - [Send Emails with Lovable](https://docs.brew.new/integrations/ai-tools/lovable.md): Add email sending to an app you built in Lovable using the Brew API, wiring automations to your app's real events without leaving your stack. - [API Introduction](https://docs.brew.new/api-reference/api/api-introduction.md): Understand the Brew Public API v1, authenticate to a brand, map core resources, and choose the right reference or SDK path. - [Send Your First Email from Code](https://docs.brew.new/api-reference/guides/send-your-first-email-from-code.md): Call the Brew API with curl to generate an on-brand email and receive a test in your inbox when you are new to the Public API. - [API Catalog](https://docs.brew.new/api-reference/api/api-catalog.md): Run any of Brew's eleven API capabilities live against your brand from the dashboard, then copy the exact request as code or as a prompt for your agent. - [Authentication & Security](https://docs.brew.new/api-reference/api/authentication.md): Brew Public API v1 authentication: brand and organization keys, permission scopes, key lifecycle, and production security best practices. - [Organization and Brand Credentials](https://docs.brew.new/api-reference/api/organization-and-brand-scope.md): How a Brew credential is scoped to one brand or a whole organization, when to send X-Brand-Id, and what ORG_SCOPE_REQUIRED and INSUFFICIENT_ROLE mean. - [Data Model](https://docs.brew.new/api-reference/api/data-model.md): The entities behind Brew's Public API v1, how they link, and what every identifier looks like, for builders joining sends, runs, and events. - [Rate Limits](https://docs.brew.new/api-reference/api/rate-limits.md): Per-route rate limit policies, the response headers that report your remaining budget, and the canonical 429 retry cookbook for Public API v1. - [Idempotency](https://docs.brew.new/api-reference/api/idempotency.md): Idempotency-Key contract for the Brew Public API v1, 24h replay window, 409 IDEMPOTENCY_CONFLICT semantics, recommended key patterns. - [Pagination](https://docs.brew.new/api-reference/api/pagination.md): Cursor-based pagination conventions for list endpoints in the Brew Public API v1, limits, cursors, hasMore, and the standard iteration loop. - [Batch Operations](https://docs.brew.new/api-reference/api/batch-operations.md): Batch contact upsert + delete on the Brew Public API v1, payload limits, partial-success contract, per-row error reporting. - [Async Jobs & Polling](https://docs.brew.new/api-reference/api/async-jobs.md): Long-running operations on the Brew Public API v1, how to fire automation runs, queue email sends, and poll for completion without webhooks. - [Credits](https://docs.brew.new/api-reference/api/credits.md): How credits work on the Brew Public API v1: usage-metered AI generation, fixed media costs, credit headers, and checking your balance with GET /v1/usage. - [Events & Webhooks](https://docs.brew.new/api-reference/api/events-and-webhooks.md): Event-driven integration with the Brew Public API v1: fire a trigger from your backend today, receive outbound webhooks when they ship. - [Errors](https://docs.brew.new/api-reference/api/errors.md): The standard error envelope, the full Brew Public API v1 error code catalog, and recovery guidance for every code you can receive. - [Response Headers](https://docs.brew.new/api-reference/api/response-headers.md): Every header the Brew Public API v1 sets on responses, request correlation, rate limits, idempotency, deprecation, caching. - [API Design Notes](https://docs.brew.new/api-reference/api/design-notes.md): Why Brew's API uses idempotency, partial-success batches, and polling before outbound webhooks, with context for builders. - [Migrate to the New v1 Surface](https://docs.brew.new/api-reference/api/v1-migration.md): Every route, field, status, and error rename in the Brew Public API v1 cleanup, with the old spelling next to the new one so you can grep your code. - [Check Brand Readiness Before Sending](https://docs.brew.new/api-reference/guides/check-brand-readiness.md): Use GET /v1/brand to confirm the API key's brand has finished extraction before generating or sending emails from the Brew Public API. - [Upload a Local Image](https://docs.brew.new/api-reference/guides/upload-a-local-image.md): Add an image file from your machine to the brand library with the Brew API in three free calls: open an upload, send the bytes, then add it. - [Monitor Campaign Sends](https://docs.brew.new/api-reference/guides/monitor-campaign-sends.md): List sends, poll a single send's lifecycle and stats, read its per-recipient events, and fire a test send with the Brew Public API v1. - [Explore Per-Contact Engagement](https://docs.brew.new/api-reference/guides/per-contact-engagement.md): Pull one contact's engagement timeline across email, automation, trigger, and inbound events, plus the open-time profile behind their best send time. - [Read Brew Insights](https://docs.brew.new/api-reference/guides/read-brew-insights.md): List the findings Brew Insights keeps about your brand's email, check how fresh they are, and read one in full with its frozen metrics. - [Typed Payload Contracts](https://docs.brew.new/api-reference/guides/typed-payload-contracts.md): Generate TypeScript contracts for trigger payloads, store and version them, dry-run payloads, and gate drift in CI before a fire reaches production. - [Brew MCP Server](https://docs.brew.new/api-reference/mcp/overview.md): Connect Brew to ChatGPT, Claude, Grok, Cursor, Codex, and any AI agent over the Model Context Protocol, and see what an agent can do once connected. - [MCP Quickstart](https://docs.brew.new/api-reference/mcp/quickstart.md): Connect Brew to ChatGPT, Claude, Grok, Cursor, or Codex with OAuth, then run your first email-marketing workflow end to end from chat. - [Connect Your Client](https://docs.brew.new/api-reference/mcp/connect-your-client.md): Per-client setup for the Brew MCP server across ChatGPT, Claude, Grok, Cursor, Codex, VS Code, and every other major MCP client, using OAuth. - [MCP Tools](https://docs.brew.new/api-reference/mcp/tools.md): The full Brew MCP tool catalog by topic: email, automations, contacts and audiences, domains, brand, images and media, and account. - [MCP Workflows](https://docs.brew.new/api-reference/mcp/workflows.md): Guided email-marketing recipes for agents. Launch an email send, build a segment, set up an automation, analyze results, and personalize with a CRM MCP. - [Sync a CRM Into Brew Over MCP](https://docs.brew.new/api-reference/mcp/sync-a-crm.md): Pull CRM fields into Brew contacts with an MCP assistant: create custom fields, map properties, run the sync, and verify counts before you send. - [Sync Brew and Attio Over MCP](https://docs.brew.new/api-reference/mcp/attio.md): Map Attio's record and list-entry attributes to Brew, sync the fields you filter on, and write email engagement back onto the Attio entry. - [MCP Authentication & Scoping](https://docs.brew.new/api-reference/mcp/authentication-and-scoping.md): How the Brew MCP server authenticates (a native OAuth connector or an API key), scopes a connection to one brand or a whole organization, and makes writes safe. - [Brew CLI](https://docs.brew.new/api-reference/cli/overview.md): brew-cli puts the whole Brew platform in your terminal: one typed command for every Public API operation, built for humans, scripts, CI, and AI agents. - [Installation](https://docs.brew.new/api-reference/cli/installation.md): Install brew-cli with Homebrew, a prebuilt binary, or npm, then run your first command. - [Authentication](https://docs.brew.new/api-reference/cli/authentication.md): Authenticate brew-cli with a Brew API key, understand brand vs organization scoping, and point the CLI at different environments. - [Commands](https://docs.brew.new/api-reference/cli/commands.md): What the Brew CLI includes: every Public API operation as a typed command, plus the conventions all commands share. - [Common Flows](https://docs.brew.new/api-reference/cli/common-flows.md): Copy-runnable brew-cli sequences for the work teams do most: launch a campaign, QA a design, build an automation, and report on performance. - [Use from AI Agents](https://docs.brew.new/api-reference/cli/agents.md): What makes brew-cli dependable inside coding agents: automatic JSON, semantic exit codes, and a confirmation protocol that never hangs. - [List email designs](https://docs.brew.new/api-reference/public-v1/emails/list-email-designs.md): Lists the brand’s designs, newest first on the `sortBy` timestamp, as `{ data, pagination }`. Each row carries `emailId`, the latest `emailVersionId`, `title`, `status`, `previewImage` (when captured), `updatedAt`, `group` (`{ groupId, groupName }` or `null` when Ungrouped) and its creator. - [Generate an email design](https://docs.brew.new/api-reference/public-v1/emails/generate-an-email-design.md): Generates a new design through the Brew email agent. Designs are pure: no send state, no type. Sending happens later with `createSend`, or a `sendEmail` node in an automation references the returned `emailId` and `emailVersionId`. Usage-metered: the agent's actual token usage is billed. - [Get an email design](https://docs.brew.new/api-reference/public-v1/emails/get-an-email-design.md): Reads one design as the bare `EmailDetail` row: `emailId`, the `emailVersionId` (the pin for `POST /v1/sends` and sendEmail nodes), `title`, `status`, `previewStatus`, `subjectLine`, `previewText`, `previewImage`, `updatedAt`, `group` and `createdBy` / `createdByUserId` (the design’s creator, shared… - [Delete an email design](https://docs.brew.new/api-reference/public-v1/emails/delete-an-email-design.md): Hard-deletes every version of the design. Idempotent — a miss resolves with `deleted: false` plus a `reason` instead of a 404: `already_deleted` (this id was hard-deleted earlier; `deletedAt` carries when) or `not_found` (no such design on this brand, including cross-brand ids). An `already_deleted`… - [Edit an email design](https://docs.brew.new/api-reference/public-v1/emails/edit-an-email-design.md): Updates a design: an AI edit (`prompt`), its envelope (`title`, `subjectLine`, `groupId`), or both in one call. At least one of the four is required. A design renames and moves between groups here exactly like an audience, trigger, automation or group renames through its own PATCH. - [Import an email](https://docs.brew.new/api-reference/public-v1/emails/import-an-email.md): Converts existing markup into a new, fully editable Brew design. Source structure is preserved and every discoverable safe public resource is rehosted; when rehosting fails a validated public URL is kept with a warning, and private, malformed and blocked references are stripped. Free: a deterministi… - [Import a Figma frame](https://docs.brew.new/api-reference/public-v1/emails/import-a-figma-frame.md): Deterministically converts one selected Figma frame into a new editable Brew email design. No model runs and no credits are charged. - [Clone an email design](https://docs.brew.new/api-reference/public-v1/emails/clone-an-email-design.md): Creates a NEW design by copying the persisted source snapshot exactly. This is a deterministic database fork: it does not invoke an AI agent, reinterpret markup, re-host assets, or regenerate the preview. - [Restore a historical version](https://docs.brew.new/api-reference/public-v1/emails/restore-a-historical-version.md): Non-destructive restore: clones the numbered version into a NEW `latest` row (demoting the current head) and returns the same generated-email shape as an edit, including the fresh `emailVersionId`. Like a prompt edit, it moves every automation `sendEmail` step pinned to the previous latest version o… - [Export a design to an ESP](https://docs.brew.new/api-reference/public-v1/emails/export-a-design-to-an-esp.md): Export a finished email DESIGN to a connected third-party ESP (Braze, Brevo, HubSpot, Klaviyo, Mailchimp, Mailjet, Iterable, Postmark, OneSignal, Mailgun, SendGrid) as a reusable TEMPLATE. This is NOT a Brew send — it creates a template in the destination platform and does NOT deliver to recipients,… - [Audit an email](https://docs.brew.new/api-reference/public-v1/emails/audit-an-email.md): Audits an email for production readiness in parallel: links, images, compliance, loaded size, client support, accessibility and judged copy, plus markup checks. - [Preview across clients & devices](https://docs.brew.new/api-reference/public-v1/emails/preview-across-clients-&-devices.md): Starts a durable rendering job for the selected email version across real email clients, including Gmail, Outlook, Apple Mail, iOS, and dark-mode variants. Omit emailVersionId to pin the current version at admission. - [List inbox placement tests](https://docs.brew.new/api-reference/public-v1/emails/list-inbox-placement-tests.md): Lists a design's recent inbox-placement (seed) tests, newest first, under `{ data, pagination }` as lean persisted snapshots: `testId`, `status`, subject and preview, `seedCount` and the `overall` placement bucket. Free; no provider poll. - [Run an inbox placement test](https://docs.brew.new/api-reference/public-v1/emails/run-an-inbox-placement-test.md): Test where the design’s latest version LANDS — inbox vs spam vs missing — across real mailbox providers (Gmail, Outlook, Yahoo, Apple, …). Brew provisions a Mailgun seed list and sends the email to the seed addresses through your REAL send pipeline on a VERIFIED sending `domainId`, so the result ref… - [Get inbox placement test results](https://docs.brew.new/api-reference/public-v1/emails/get-inbox-placement-test-results.md): Reads one inbox-placement (seed) test as the bare test resource. Free. - [Read a saved email audit](https://docs.brew.new/api-reference/public-v1/emails/read-a-saved-email-audit.md): Returns a bounded page of the normalized audit findings, including finding IDs, rule IDs, targets, remediation, and the audited content hash. Reading pages is free and never reruns the audit. Continue using pagination.cursor. Reports are retained for seven days; the report’s expiresAt is the separat… - [Read email rendering progress](https://docs.brew.new/api-reference/public-v1/emails/read-email-rendering-progress.md): Reads the existing rendering job and per-client results without submitting another provider test or charging again. Returns successful full-size image links, pending or failed clients with reasons and retryability, expiry, and credit reservation status. Poll the same previewId after nextPollAfterMs… - [List email groups](https://docs.brew.new/api-reference/public-v1/emails/list-email-groups.md): Lists the brand’s email folders under `{ data, pagination }`. Named groups use `grp_*` ids; Ungrouped is always included as `{ groupId: "ungrouped", groupName: "Ungrouped" }`. `emailCount` is capped at 100. A named group a person created carries `createdByUserId` and, when they can be named, `create… - [Create an email group](https://docs.brew.new/api-reference/public-v1/emails/create-an-email-group.md): Creates a named email folder. Returns `201` with `{ groupId, groupName, emailCount }`. Pass `emailIds` (up to 50) to move existing designs in, in the same transaction as the create; the response then adds `moved` and `notMoved` (`not_found`, `generating`, `not_movable`, `folder_full` or `retry`; res… - [Get an email group](https://docs.brew.new/api-reference/public-v1/emails/get-an-email-group.md): Reads one email folder as the bare `EmailGroupSummary` (`groupId`, `groupName`, `emailCount`, plus `createdByUserId` when a person created it, and `createdBy` when they can be named). - [Delete an email group](https://docs.brew.new/api-reference/public-v1/emails/delete-an-email-group.md): Deletes a named folder. Member emails move to Ungrouped. Ungrouped cannot be deleted (`400`). Idempotent — an unknown / cross-brand id resolves with `{ deleted: false }`. - [Update an email group](https://docs.brew.new/api-reference/public-v1/emails/update-an-email-group.md): Renames a named folder (`name`), moves existing designs into it (`emailIds`, up to 50, one request against the rate limit), or both, in one transaction. A move adds `moved` and `notMoved` (`not_found`, `generating`, `not_movable`, `folder_full` or `retry`; resend `retry` ids) to the response. Ungrou… - [Send an email](https://docs.brew.new/api-reference/public-v1/emails/send-an-email.md): Sends an email design. Polymorphic on `test`: a campaign send mints a new `Send` (the unit of delivery and analytics) and delivers to a saved audience or an inline list through a verified domain; `test: true` delivers one synchronous QA copy to a single address and writes no send row. - [Cancel a send](https://docs.brew.new/api-reference/public-v1/emails/cancel-a-send.md): Cancels a scheduled or queued send before it goes out, or STOPS any in-flight campaign send. A campaign that is `running` or `paused` is canceled the same way the in-app Stop button does it: the remaining recipients are never delivered while already-sent ones stay sent (every shape re-checks livenes… - [Pause a gradual send](https://docs.brew.new/api-reference/public-v1/emails/pause-a-gradual-send.md): Manually pauses an in-flight GRADUAL (domain-warmup) send. The ramp stops before its next chunk and holds its current batch until `POST /v1/sends/{sendId}/resume` (or a cancel). A send that is not a `running` gradual send returns `409 SEND_NOT_PAUSABLE`. Brand-scoped: an unknown / cross-brand `sendI… - [Resume a paused gradual send](https://docs.brew.new/api-reference/public-v1/emails/resume-a-paused-gradual-send.md): Resumes a manually paused GRADUAL send. The ramp picks the resume up at its next hold check (seconds after a short pause, up to an hour after a long one); the unsent tail is re-spread and later batches shift so missed intervals do not compress into a burst. A send held at the plan limit resumes on i… - [List email comments](https://docs.brew.new/api-reference/public-v1/emails/list-email-comments.md): Lists one design's open comment threads, newest activity first, under `{ data, pagination }`, as the canvas pins show them: `commentId`, `target` (whole email or one element), the 12 most recent `participants` with `participantCount`, `messageCount`, the latest message preview and a link to the thre… - [List sends](https://docs.brew.new/api-reference/public-v1/sends/list-sends.md): Lists sends, newest first, under `{ data, pagination }`. A send is the unit of delivery and analytics: one design delivered to a target through one domain. Rows carry the sender and subject snapshot, `status`, delivery accounting and, once delivered, lifetime `stats`. - [Get a send](https://docs.brew.new/api-reference/public-v1/sends/get-a-send.md): Reads one send (campaign or automation) as the bare `Send` row: identity and join keys, the sender and subject snapshot, `status`, `approvalState`, delivery accounting, gradual-send progress and lifetime `stats`. - [Brand overview (totals, rates, timeseries)](https://docs.brew.new/api-reference/public-v1/analytics/brand-overview-totals-rates-timeseries.md): Windowed brand overview: the exact read behind the app's Analytics metric cards and chart (same per-recipient dedup and machine open and click exclusion), so API, MCP and page numbers always agree. Defaults to the last 7 days. - [Automation performance](https://docs.brew.new/api-reference/public-v1/analytics/automation-performance.md): Windowed per-automation performance + scoped `totals` + the resolved `range`. Defaults to the last 30 days. Reflects LIVE runs only (test runs never contribute). Totals include every matching automation independently from the displayed row `limit`. Narrow with the `automationId` filter; bound the wi… - [Unified events feed](https://docs.brew.new/api-reference/public-v1/analytics/unified-events-feed.md): Read-only feed of the brand's analytics events (email, automation, trigger, inbound), newest first, over a `from`/`to` window that defaults to the last 7 days. Email rows carry the send behind them (`sendId`, `emailId`), so a page joins back to `GET /v1/sends/{sendId}`. - [List automations](https://docs.brew.new/api-reference/public-v1/automations/list-automations.md): Lists the brand’s automations under `{ data, pagination }` as LEAN rows: identity, `name`, `version`, `published`, `paused` and live-version state, `emailIds`, `updatedAt` and attribution; the graph is omitted. - [Create an automation](https://docs.brew.new/api-reference/public-v1/automations/create-an-automation.md): Deterministic create: the body carries the full graph (`{ name, triggerEventId?, nodes, connections }`). - [Get an automation](https://docs.brew.new/api-reference/public-v1/automations/get-an-automation.md): Reads one automation as the bare row, LEAN by default (graph omitted), with `published`, `paused`, `pausedAt`, the live version it serves, its creator (`createdBy`, `createdByUserId`) and, while live, the live version’s publisher (`publishedBy`, `publishedByUserId`). - [Delete an automation](https://docs.brew.new/api-reference/public-v1/automations/delete-an-automation.md): Cascade-deletes the automation: every version row, runs, and logs. Referenced email DESIGNS are shared resources and always survive. Idempotent — an unknown id resolves with `deleted: false`. - [Update or publish an automation](https://docs.brew.new/api-reference/public-v1/automations/update-or-publish-an-automation.md): One endpoint, two mutually exclusive modes: update the graph (a new `automationVersionId` on the same `automationId`) or change lifecycle state (`published`, `paused`). The modes cannot be combined: update first, then `PATCH { "published": true }`. - [Test an automation](https://docs.brew.new/api-reference/public-v1/automations/test-an-automation.md): Runs the saved automation END-TO-END through the real workflow in TEST mode — works on drafts and for both event and manual-audience automations; every node executes (filters/splits evaluate against `payload`, and `contact.` conditions read the test recipient’s contact unless `payload` supplie… - [Run a manual-audience automation](https://docs.brew.new/api-reference/public-v1/automations/run-a-manual-audience-automation.md): Launches a MANUAL-AUDIENCE automation against the audience bound to its trigger node. `dryRun: true` previews without sending; `scheduledAt` launches later, at most 1 year ahead. Percentage-based `gradualSend` delivers each send step in custom hour or calendar-day batches and supports manual pause/r… - [List manual-audience runs](https://docs.brew.new/api-reference/public-v1/automations/list-manual-audience-runs.md): Lists manual-audience launches (each "Run" of a manual-audience automation), newest first, under `{ data, pagination }`: status, recipient totals and the per-node funnel. - [Get a manual-audience run](https://docs.brew.new/api-reference/public-v1/automations/get-a-manual-audience-run.md): Reads one manual-audience launch as the bare `AudienceRun` row: `status`, `approvalState`, `pauseReason` while paused, recipient totals, per-node `nodeStats`. A gradual run carries its authored ramp; the batch progress of each send step is on its own send (`nodeStats[].sendId`). - [Pause a manual-audience run](https://docs.brew.new/api-reference/public-v1/automations/pause-a-manual-audience-run.md): Holds a running manual-audience launch at its next step boundary. Delivery already in flight for the current step completes; nothing further goes out until `resumeAudienceRun`. - [Resume a manual-audience run](https://docs.brew.new/api-reference/public-v1/automations/resume-a-manual-audience-run.md): Continues a paused launch, or restarts a FAILED one under a fresh workflow run: it picks up at the first send step that never delivered and skips every step the failed run finished, so nothing is resent. `resumedFrom` reports which case ran. A launch held at the plan limit (`pauseReason: plan_limit`… - [Cancel a manual-audience run](https://docs.brew.new/api-reference/public-v1/automations/cancel-a-manual-audience-run.md): Stops a manual-audience launch for good. Emails already sent are NOT recalled and a canceled run cannot be resumed. - [List automation runs](https://docs.brew.new/api-reference/public-v1/automations/list-automation-runs.md): Lists recent runs (event executions and test runs), newest first, under `{ data, pagination }`. Rows are lean: identity, `automationVersionId`, `definitionHash`, `triggerInstanceId`, `mode`, `status` and timestamps. - [Get an automation run](https://docs.brew.new/api-reference/public-v1/automations/get-an-automation-run.md): Reads one run as the bare row: the automation and version it executed (`automationVersionId` is a valid publish pin, `definitionHash` the graph fingerprint), the fire behind it (`triggerInstanceId`), `mode`, `status` and timestamps. - [Cancel an automation run](https://docs.brew.new/api-reference/public-v1/automations/cancel-an-automation-run.md): Stops ONE run (an event execution or a test run). Marks it `canceled` (first-terminal-wins: a late completion from the dying workflow can never overwrite it), wakes a run parked on a wait node so it observes the cancel now, and terminates the durable workflow run so a step stuck retrying is freed to… - [List triggers](https://docs.brew.new/api-reference/public-v1/automations/list-triggers.md): Lists every trigger the brand has under `{ data, pagination }`: `provider: "brew_api"` for API-created customs and `provider: "clerk" | "stripe" | …` for integration-provisioned triggers. Each row carries its `payloadSchema`. - [Create a trigger](https://docs.brew.new/api-reference/public-v1/automations/create-a-trigger.md): Creates a custom trigger event definition — the contract automations subscribe to. Body carries `{ title, description?, payloadSchema }`; the server mints `triggerEventId` and hardcodes `provider: "brew_api"`. Integration triggers (clerk, stripe, shopify, …) are provisioned by the corresponding inte… - [Get a trigger](https://docs.brew.new/api-reference/public-v1/automations/get-a-trigger.md): Reads one trigger as the bare row: `triggerEventId`, `title`, `provider`, `payloadSchema` and timestamps. - [Delete a trigger](https://docs.brew.new/api-reference/public-v1/automations/delete-a-trigger.md): Deletes a custom trigger. Refused with `409 TRIGGER_HAS_DEPENDENT_AUTOMATIONS` while automations still reference it (`details.referencingAutomations` lists each blocker). Idempotent — an already-gone trigger resolves with `deleted: false`. - [Update a trigger](https://docs.brew.new/api-reference/public-v1/automations/update-a-trigger.md): Updates one or more editable fields (`title`, `description`, `payloadSchema`). Whether a trigger fires is governed solely by `automation.published` on each wired automation — there is no per-trigger off-switch. Integration-provisioned triggers are immutable here (`422 TRIGGER_IMMUTABLE`). While a pu… - [Check a trigger is ready to fire](https://docs.brew.new/api-reference/public-v1/automations/check-a-trigger-is-ready-to-fire.md): Reports whether a fire would start anything right now, and everything a caller needs to wire one. Runs the same credential, brand scope and permission gates a real fire hits, without firing. - [Fire a trigger](https://docs.brew.new/api-reference/public-v1/automations/fire-a-trigger.md): Fires the trigger: validates the payload against the stored contract, upserts the contact it describes, then starts one run per published automation attached to the trigger. - [Get a trigger payload contract](https://docs.brew.new/api-reference/public-v1/automations/get-a-trigger-payload-contract.md): The payload contract for the trigger: the STORED contract when one has been declared (`source: "stored"`, with `contractHash`, `version`, `enforcement`), otherwise the derived one (`source: "derived_from_schema"`, built from the trigger’s flat `payloadSchema`). - [Declare a trigger payload contract](https://docs.brew.new/api-reference/public-v1/automations/declare-a-trigger-payload-contract.md): Declares the stored payload contract for the trigger, changes how it is enforced, or both, in one call. `fields` and `enforcement` are both optional, so arming enforcement is `{ "enforcement": "strict" }`. While a PUBLISHED automation consumes the trigger the change must stay backward compatible (th… - [Validate a trigger payload](https://docs.brew.new/api-reference/public-v1/automations/validate-a-trigger-payload.md): Dry-runs a payload against the trigger's contract — the SAME validator the live path runs, against the stored contract when one exists (derived otherwise; `source` says which). Nothing fires, sends, or writes. - [Infer a payload contract from an example](https://docs.brew.new/api-reference/public-v1/automations/infer-a-payload-contract-from-an-example.md): Drafts a contract from a real example payload: paste the JSON your system sends and get back typed `fields` — integers and floats split automatically, full ISO timestamps become `date`, object/array shapes are walked recursively. Every inferred field is `required: true` (relax explicitly). - [List trigger instances](https://docs.brew.new/api-reference/public-v1/automations/list-trigger-instances.md): Lists fired trigger-event instances, newest first, under `{ data, pagination }`: the audit log of every inbound fire, from the API (`source: "api"`) or an integration webhook (`source: "integration"`). Each row links the fire to the automations it matched and the runs it started (`automationRunIds`)… - [Get a trigger instance](https://docs.brew.new/api-reference/public-v1/automations/get-a-trigger-instance.md): Reads one fired trigger-event instance as the bare row: its `state`, the automations it matched, the `automationRunIds` it started and the `rejectionReason` when it was refused. - [List contacts](https://docs.brew.new/api-reference/public-v1/contacts/list-contacts.md): Lists the brand’s contacts under `{ data, pagination }`, newest first by default. - [Create or update contacts](https://docs.brew.new/api-reference/public-v1/contacts/create-or-update-contacts.md): Upserts a single contact OR a batch (`{ contacts: [...] }`, up to 1000 rows). Unknown custom fields auto-create field definitions on the brand, typed from the batch (native booleans/numbers, ISO-date strings → `date`, anything else `string`). - [Get a contact](https://docs.brew.new/api-reference/public-v1/contacts/get-a-contact.md): Reads one contact as the bare `Contact` row: core columns, `subscribed`, `consent`, validation state and `customFields`. - [Delete a contact](https://docs.brew.new/api-reference/public-v1/contacts/delete-a-contact.md): Deletes the contact. Idempotent — an unknown email resolves with `deleted: false`. For bulk deletion use `POST /v1/contacts/batch-delete`. - [Update a contact](https://docs.brew.new/api-reference/public-v1/contacts/update-a-contact.md): Patches fields on the contact (`{ fields: { : } }` — core columns or custom fields) and/or records marketing consent provenance (`{ consent: { source, capturedAt?, policyVersion?, evidence? } }`, never re-subscribing an opt-out). Send one or both. Returns `{ contact, updated }` where `… - [Get contacts](https://docs.brew.new/api-reference/public-v1/contacts/get-contacts.md): The single "Get Contacts" read. Structured search over the brand’s contacts: free-text `search`, `filters` (`{ field, operator, value }` combined with `logic: "and" | "or" | "none"`; the allowed operators depend on the field’s type — see the `operator` schema — and an unsupported pairing is a `400`,… - [Validate email deliverability](https://docs.brew.new/api-reference/public-v1/contacts/validate-email-deliverability.md): Batch deliverability check (up to 100 addresses) — run BEFORE importing or sending. Each address is classified `valid` (safe), `risky` (deliverable but flagged — e.g. role account, disposable, catch-all), or `invalid` (undeliverable / do-not-send), with a machine-readable `reason` and a `didYouMean`… - [Bulk-import contacts from CSV](https://docs.brew.new/api-reference/public-v1/contacts/bulk-import-contacts-from-csv.md): Parse a raw CSV string and upsert the rows as contacts (≤ 1000). By default each column header maps to a field of the same name (`email` is required). A header that spells a core field, ignoring case, spaces, `_` and `-`, or whose field key equals it (`First.Name`), maps to it: `Email`, `First Name`… - [Batch-delete contacts](https://docs.brew.new/api-reference/public-v1/contacts/batch-delete-contacts.md): Deletes up to 1000 contacts by email. Returns the deleted count plus `notFound[]` for emails that had no contact. Addresses are lookup keys, not re-validated: any address a contact was stored under matches, and one that matches nothing lands in `notFound[]` instead of failing the batch. - [List contact fields](https://docs.brew.new/api-reference/public-v1/contact-fields/list-contact-fields.md): Lists core contact columns and custom field definitions under `{ data, pagination }`. Use the field names in audience filters, contact search, and `{{ field | fallback }}` merge tags. Add `?include=coverage` to decorate each row with fill stats — the % of contacts holding a non-empty value plus the… - [Create a contact field](https://docs.brew.new/api-reference/public-v1/contact-fields/create-a-contact-field.md): Creates a custom field definition (`{ fieldName, fieldType: "string" | "number" | "date" | "bool" }`). Returns `201` with the bare definition. (Contact upserts also auto-create unknown fields — explicit creation is for pinning the type up front.) - [Get a contact field](https://docs.brew.new/api-reference/public-v1/contact-fields/get-a-contact-field.md): Reads one contact field definition (a core column or a custom field) as the bare row: `fieldName`, `fieldType` and its filter/sort/search flags. - [Delete a contact field](https://docs.brew.new/api-reference/public-v1/contact-fields/delete-a-contact-field.md): Deletes a custom field and clears its value from every contact. The values cannot be recovered, and a field created later with the same name starts empty. - [List audiences](https://docs.brew.new/api-reference/public-v1/audiences/list-audiences.md): Lists the brand’s saved audiences under `{ data, pagination }`. Each row carries its contact `filters`, the cached member `count` and ISO timestamps; an audience is the recipient target for `createSend`. - [Create an audience](https://docs.brew.new/api-reference/public-v1/audiences/create-an-audience.md): Creates a saved audience from a name + filter set (`{ filters: [{ field, operator, value? }], logicalOperator: "and" | "or" }`). Returns `201` with the bare audience row. An `email in [...]` clause listing more than 100 addresses is converted automatically: a fresh date custom field is stamped on th… - [Get an audience](https://docs.brew.new/api-reference/public-v1/audiences/get-an-audience.md): Reads one saved audience as the bare `Audience` row. - [Delete an audience](https://docs.brew.new/api-reference/public-v1/audiences/delete-an-audience.md): Deletes the audience. Idempotent — an unknown id resolves with `deleted: false`. - [Update an audience](https://docs.brew.new/api-reference/public-v1/audiences/update-an-audience.md): Updates `name` and/or `filters` (at least one required). Pass the latest row’s `updatedAt` as `expectedUpdatedAt` to reject stale read-modify-write edits. Returns the bare updated row. Replacement filters follow the same email-list rule as create: an `email in [...]` clause over 100 addresses is con… - [Create an audience from analytics events](https://docs.brew.new/api-reference/public-v1/audiences/create-an-audience-from-analytics-events.md): Creates a frozen audience snapshot from the same membership filters as `/events`: 1–10 canonical event types, an absolute window up to 90 days (`from` may be omitted when `sendId` is set — the window then derives from that send), optional send/email ids, multi-select automation/audience ids, recipie… - [Duplicate an audience](https://docs.brew.new/api-reference/public-v1/audiences/duplicate-an-audience.md): Creates a deterministic copy of the saved audience’s live filters with a server-generated “(copy)” name. Contacts are not copied; both audiences resolve against the same contact records. - [List domains](https://docs.brew.new/api-reference/public-v1/domains/list-domains.md): Lists the brand’s sending domains under `{ data, pagination }`: ALL lifecycle states by default, so a caller mid-verification can read `pending` rows and their DNS `records`. - [Add a domain](https://docs.brew.new/api-reference/public-v1/domains/add-a-domain.md): Registers a sending domain with the provider. Optional `sendingPurpose` is `marketing` (default; campaigns, audience sends, automations) or `transactional` (event-triggered automation mail — no unsubscribe link required, merely-unsubscribed contacts still receive it). Returns `201` with the bare row… - [Get a domain](https://docs.brew.new/api-reference/public-v1/domains/get-a-domain.md): Reads one sending domain as the bare `Domain` row: verification `status`, DNS `records`, `sendable`, `sendingPurpose` and the `openTracking`/`clickTracking` flags. Sender defaults are write-only here: the row does not echo them. - [Delete a domain](https://docs.brew.new/api-reference/public-v1/domains/delete-a-domain.md): Removes the domain from the provider and deletes the local row. Idempotent — an unknown id resolves with `deleted: false`. - [Update domain settings](https://docs.brew.new/api-reference/public-v1/domains/update-domain-settings.md): Updates sender defaults (`defaultSenderName`, `defaultFromEmail`, `defaultReplyToEmail`) and/or `sendingPurpose` — at least one required. `defaultFromEmail` is the sender MAILBOX (the text before `@`) — the host is always this domain, so a full address is accepted and reduced to its local part; `def… - [Verify a domain](https://docs.brew.new/api-reference/public-v1/domains/verify-a-domain.md): Re-checks the DNS records with the provider and refreshes the row. Empty body. Safe to poll — keep calling until `sendable: true` (DNS propagation can take minutes to hours). Returns the bare refreshed row. - [List a domain's unsubscribes](https://docs.brew.new/api-reference/public-v1/domains/list-a-domains-unsubscribes.md): Every MARKETING sending domain is its own unsubscribe list, keyed by the domain's host inside the brand's contacts. Returns one page (`{ data, pagination }`, newest first). Each row carries `scope`: `domain` (on this host's list), `all` (the brand-wide opt-out — `subscribed: false` on the contact, w… - [Add addresses to a domain's unsubscribe list](https://docs.brew.new/api-reference/public-v1/domains/add-addresses-to-a-domains-unsubscribe-list.md): Suppresses up to 1,000 addresses from THIS marketing domain's mail. An existing contact is suppressed for this host only — sends from OTHER marketing domains still reach it; set `subscribed: false` on the contact for a brand-wide opt-out. An address with no contact is created already globally unsubs… - [Remove an address from a domain's unsubscribe list](https://docs.brew.new/api-reference/public-v1/domains/remove-an-address-from-a-domains-unsubscribe-list.md): Takes one address off THIS domain's list (resubscribes it to this host only). Idempotent — `removed: false` when the address was not on the list. Never clears the brand-wide opt-out: `globallyUnsubscribed: true` means every marketing send still skips the contact until `PATCH /v1/contacts/{email}` se… - [Import a CSV into a domain's unsubscribe list](https://docs.brew.new/api-reference/public-v1/domains/import-a-csv-into-a-domains-unsubscribe-list.md): Migrates an unsubscribe list (another ESP's export) into THIS marketing domain's list. `csv` is the file text: an `email` header — or any column of addresses, or one headerless column; pass `column` to name the header when detection fails (`400` otherwise). Synchronous and bounded: 10,000 rows per c… - [Export a domain's unsubscribe list](https://docs.brew.new/api-reference/public-v1/domains/export-a-domains-unsubscribe-list.md): The whole list as CSV text (`Email,Scope,Unsubscribed At,Source,Send ID`) inside the JSON envelope — the v1 transport is JSON-only. Capped at 50,000 rows or ~4 MB of CSV, whichever comes first, so the response stays under the platform body limit (`truncated: true` beyond; narrow with `?scope=`). - [Get domain health](https://docs.brew.new/api-reference/public-v1/domains/get-domain-health.md): The domain's deliverability health in one FREE read: a `verdict` (`healthy` / `at_risk` / `critical`) with actionable `signals`, DNS/auth state incl. DMARC, active percentage-based gradual sends, sampled bounce/complaint activity from campaign and automation sends, workspace reputation, and inbox-pl… - [List templates](https://docs.brew.new/api-reference/public-v1/templates/list-templates.md): Lists public templates under { data, pagination }. The default full representation includes HTML. Set representation=summary for metadata, previewImage, viewUrl, and referenceEmailId without HTML. Supports exact brand and category filters; query matches title text or an exact template identifier. se… - [Get a public template](https://docs.brew.new/api-reference/public-v1/templates/get-a-public-template.md): Returns metadata, preview and canonical links, and referenceEmailId for one public template. Add include=html to inspect its rendered content. Large HTML is returned as a downloadable content.url instead of truncated JSON. - [List flows](https://docs.brew.new/api-reference/public-v1/templates/list-flows.md): Lists public email flows, one brand’s real onboarding or newsletter sequence with the day each email landed, as cards under `{ data, pagination, total }`. Organization-wide: the same bounded corpus the gallery shows (a few hundred flows), paged with `limit`/`cursor`. - [Get a flow](https://docs.brew.new/api-reference/public-v1/templates/get-a-flow.md): One public flow as the bare row, with `anchor` (what day 0 means) and every step’s `subject`, `previewText`, `dayOffset`, `delayDays`, `category`, `previewImage` and `emailId`. Organization-wide. - [Get the brand bound to this API key](https://docs.brew.new/api-reference/public-v1/brand/get-the-brand-bound-to-this-api-key.md): Returns `{ brand }` — the single brand bound to the API key. Check `ready` (`status === "completed"`) before calling `POST /v1/emails`, which returns `422 BRAND_NOT_READY` until brand extraction finishes. - [Update brand identity + design system](https://docs.brew.new/api-reference/public-v1/brand/update-brand-identity-+-design-system.md): Partial update of the writable design artifacts in one call. `identity` shallow-merges the provided fields; `emailDesign` / `imageStyle` replace the markdown design-system documents the email agent follows. Provide at least one. Returns the touched fields in the `GET /v1/brand` shape. - [Get brand images](https://docs.brew.new/api-reference/public-v1/brand/get-brand-images.md): The brand’s asset library, as the Assets page shows it: logos, brand images (from the site or uploaded, including the social preview and site screenshot) and images made with Brew. Omit `?q=` to BROWSE it (free), newest first or `?sort=oldest`. Pass `?q=` for SEMANTIC search over brand and generated… - [Delete a brand image](https://docs.brew.new/api-reference/public-v1/brand/delete-a-brand-image.md): Removes one image from the brand library and from image search, as Delete image on the Assets page does. Its file stays hosted at its URL, so emails already using it keep rendering. - [List the brands this credential can reach](https://docs.brew.new/api-reference/public-v1/brands/list-the-brands-this-credential-can-reach.md): Organization-scoped credentials see every brand in the organization; a brand-scoped credential sees exactly the one brand it is bound to. - [Create a brand and start its extraction](https://docs.brew.new/api-reference/public-v1/brands/create-a-brand-and-start-its-extraction.md): Starts an asynchronous brand extraction that crawls the site and builds the design system. Returns `201` immediately with `status: "extracting"` — poll `GET /v1/brands/{brandId}` until `ready` is `true` (typically 1–3 minutes) before calling `POST /v1/emails`, which returns `422 BRAND_NOT_READY` unt… - [Get one brand’s lifecycle state](https://docs.brew.new/api-reference/public-v1/brands/get-one-brand’s-lifecycle-state.md): The polling endpoint for `POST /v1/brands`. Reports `status`, `progress` and `phase` while extracting, and `error` when extraction failed. Terminal states are `completed` and `failed`. - [Generate an image](https://docs.brew.new/api-reference/public-v1/content/generate-an-image.md): Generates an image via the Brew AI image pipeline. `text-to-image` (default) creates from a prompt; `image-editing` edits `image1` (required) guided by the prompt. Returns a CDN-hosted URL, and saves the image to the brand’s generated images (`GET /v1/brand/images?kind=generated`). Usage-metered: ch… - [Generate a GIF](https://docs.brew.new/api-reference/public-v1/content/generate-a-gif.md): Produces a looping animated GIF (5-second source clip), routed by the `from` discriminator: `prompt` generates an on-brand still then animates it, `image` animates a source image (both via the AI gif workflow), and `video` converts a source MP4. Aspect ratio is one of `16:9`, `9:16`, `1:1`. Returns… - [Transform an image](https://docs.brew.new/api-reference/public-v1/content/transform-an-image.md): Deterministic image transform routed by the `operation` discriminator: `optimize` rehosts a palette PNG (resize ≤1200px), `resize` produces exact dimensions via the vision-guided fal pipeline (Sharp cover-crop fallback), `remove_background` returns a transparent PNG cutout (Bria RMBG 2.0). Returns t… - [Render HTML to a PNG](https://docs.brew.new/api-reference/public-v1/content/render-html-to-a-png.md): Renders an HTML document to a PNG screenshot hosted on the CDN. Credit-metered (fixed cost). - [Add image](https://docs.brew.new/api-reference/public-v1/content/add-image.md): Adds an image to the brand image library: fetches or reads it, converts it, stores it, and vector-indexes it so the email agent can find it. Free; no credits are charged. - [Create an image upload](https://docs.brew.new/api-reference/public-v1/content/create-an-image-upload.md): Opens a single-use upload for one local image file. POST the file's raw bytes to the returned `uploadUrl`, then call `addImage` with the `uploadId` to put it in the brand library. The bytes go straight to storage, so files up to 20 MB fit even though a JSON body is capped far lower. Free; no credits… - [Get usage](https://docs.brew.new/api-reference/public-v1/usage/get-usage.md): Returns the org usage snapshot: current plan, AI credit balance (limit/used/remaining — `null` = unlimited), monthly email-send quota, and the billing-period window. Check it before a credit-metered call. Billing belongs to the ORGANIZATION, so this needs an organization-scoped credential: a key bou… - [List integrations](https://docs.brew.new/api-reference/public-v1/integrations/list-integrations.md): Returns the product integration catalog for the brand in scope under `{ data, pagination }`, with a `connected` flag per provider. Connecting is a human Settings hop at `/integrations/{provider}` — never paste a connect URL into model output. Brand-scoped (`X-Brand-Id` on an org credential). No perm… - [List API keys](https://docs.brew.new/api-reference/public-v1/api-keys/list-api-keys.md): Lists one cursor page of API-key metadata for the active organization. Requires an exact `org:admin` Clerk session; API-key and OAuth actors receive `403`. Organization-level — takes no `X-Brand-Id`. `brandId` on a row is the key's binding, not the request actor. Stored secrets and hashes are never… - [Create an API key](https://docs.brew.new/api-reference/public-v1/api-keys/create-an-api-key.md): Mints a new API key through an exact `org:admin` Clerk session; API-key and OAuth actors receive `403`. The plaintext `key` is returned once and only its hash plus final preview are stored. This operation intentionally does not support response replay or `Idempotency-Key`, because replay would discl… - [Revoke an API key](https://docs.brew.new/api-reference/public-v1/api-keys/revoke-an-api-key.md): Revokes an API key in the active organization. Requires an exact `org:admin` Clerk session; API-key and OAuth actors receive `403`. - [Liveness probe](https://docs.brew.new/api-reference/public-v1/health/liveness-probe.md): No auth, no rate limit — a public liveness surface a dependent service (e.g. the Brew MCP server) can poll. Returns `{ status: "ok", version }`. - [Machine-readable API catalog](https://docs.brew.new/api-reference/public-v1/meta/machine-readable-api-catalog.md): No auth, no rate limit — a structured-JSON catalog an MCP server (or any agent) can parse to self-discover how to use Brew: auth, permission scopes, rate limits, flat credit costs, the error envelope, and the full endpoint list (derived from this same OpenAPI document, so it never drifts). Returns a… - [List chats](https://docs.brew.new/api-reference/public-v1/chats/list-chats.md): Lists the brand's Brew chats, most recently active first, under `{ data, pagination }`, as the app's chat list shows them: `chatId`, `title`, the opening prompt, Brew's latest reply, `status` (still streaming or not), `origin` (the chat app it started in; null for the Brew web app) and a link. No tr… - [Get chat context](https://docs.brew.new/api-reference/public-v1/chats/get-chat-context.md): Read a brand-scoped digest of a Brew chat for resuming the conversation in an external agent: the emails + automations it created/referenced (latest version, with preview), the trigger events it touched, and a trimmed tail of the transcript. Read-only and free. `404 CHAT_NOT_FOUND` for an unknown id… - [List insights](https://docs.brew.new/api-reference/public-v1/insights/list-insights.md): The brand’s Brew Insights as the Insights page ranks them, most severe first and then by score, under `{ data, pagination, freshness }`. Each row is one deterministic finding of the insight engine; the engine keeps at most 200 findings in view. - [Get an insight](https://docs.brew.new/api-reference/public-v1/insights/get-an-insight.md): One finding in full, as its page in Brew reads it: the list row’s fields plus `rationale`, `closedReason`, `closedAt`, `lastActedAt`, `churnCount`, the frozen `metrics`, `evidence` links, its `subject`, the detector’s `method` (what it measures, how, against what, and what resolves it), `generatedBy… - [List notifications](https://docs.brew.new/api-reference/public-v1/notifications/list-notifications.md): Lists the brand's notifications, newest first, under `{ data, pagination }`, as the app's bell shows them: generations, sends, imports, domain checks and score runs finishing or failing, plus comment mentions and replies. Each row has `type`, `status`, `title`, `subtitle`, a `url` into the app and t… - [SDK Overview](https://docs.brew.new/sdks/overview.md): Official Brew SDKs for programmatic email: what ships today, how to choose between the TypeScript SDK and the raw REST API, and where to start. - [Authentication](https://docs.brew.new/sdks/authentication.md): How to create a Brew API key, bind it to a brand, store it securely, and validate it works. Covers environment variable setup and SDK client creation. - [Generate Your Own SDK](https://docs.brew.new/sdks/openapi-codegen.md): Generate a typed Brew Public API v1 client in Python, Go, Ruby, Java, PHP, Swift, Kotlin, .NET, or any language supported by an OpenAPI 3.1 generator. - [TypeScript Installation](https://docs.brew.new/sdks/typescript/installation.md): Install @brew.new/sdk with npm, pnpm, yarn, or bun. Covers Node 20+ requirements, client options like timeout and retries, and a first request. - [TypeScript Quickstart](https://docs.brew.new/sdks/typescript/quickstart.md): Upsert contacts, browse templates, generate on-brand emails, list domains and audiences, and send your first email using the Brew TypeScript SDK. - [TypeScript Resource Surface](https://docs.brew.new/sdks/typescript/resources.md): Every resource and method in the Brew TypeScript SDK, from contacts and emails to sends and automations, with the HTTP endpoint each maps to. - [TypeScript Error Handling](https://docs.brew.new/sdks/typescript/error-handling.md): How to handle BrewApiError and transport failures in the Brew TypeScript SDK, with status-specific branches, retries, and safe defaults. - [Agentic Cookbook](https://docs.brew.new/sdks/typescript/agentic-cookbook.md): End-to-end deterministic recipes for AI agents using the Brew TypeScript SDK to build, publish, and monitor email automations programmatically. - [Changelog](https://docs.brew.new/changelog/overview.md): Release notes for Brew features and fixes, with links to the current guides so you can follow what shipped and use it today. - [Organization Keys: One Key for Every Brand](https://docs.brew.new/changelog/posts/organization-keys.md): One API key or MCP connection can now reach every brand in your organization. Name the brand on each call, or keep a key locked to one brand. - [Brew University](https://docs.brew.new/changelog/posts/brew-university.md): Eight short video walkthroughs, now playable inside Brew from the Home page in a mini player that expands, goes full screen, or opens on Loom. - [Transactional Email](https://docs.brew.new/changelog/posts/transactional-email.md): Send password resets, receipts, and verification codes from Brew. A transactional email is an automation on a domain you mark for transactional purpose. - [Email Audit](https://docs.brew.new/changelog/posts/email-audit.md): Check an email before it ships for broken links, unsubscribe content, oversized assets, copy, compatibility, and accessibility. - [Comments](https://docs.brew.new/changelog/posts/comments.md): Comment directly on an email, on a single element or the whole design, tag teammates, and keep email review and approvals inside Brew. - [Unified Analytics](https://docs.brew.new/changelog/posts/unified-analytics.md): Analytics opens as a list of everything you've sent, each row opening its own page, down to per-step numbers for every email in a flow. - [GIF Generation](https://docs.brew.new/changelog/posts/gif-generation.md): Ask Brew to animate any image into a GIF, art-directed by your brand's image-style.md, so motion in the inbox still looks unmistakably like you. - [The Brew CLI](https://docs.brew.new/changelog/posts/brew-cli.md): Every Public API operation is now a typed terminal command, built for scripts, CI, and AI agents, with a confirmation gate for irreversible sends. - [The API Catalog](https://docs.brew.new/changelog/posts/api-catalog.md): Eleven Brew capabilities now run right in the dashboard against your real brand, so you can try a call before you write the code that makes it. - [Contact Deliverability Validation](https://docs.brew.new/changelog/posts/validate-contacts.md): Check any address before you send. Each contact comes back valid, risky, or invalid, and the verdict is saved for filtering, segments, and imports. - [New Send Options: Intelligent Send and Gradual Send](https://docs.brew.new/changelog/posts/send-options.md): Two new ways to time a send. Intelligent send delivers inside time windows you set, and gradual send ramps daily volume to warm up a domain. - [Automations: List View, Manual-Audience Runs, and Switchable Triggers](https://docs.brew.new/changelog/posts/automations-list-view.md): Automations open as a list and every flow gets its own canvas. A saved audience can be the trigger, and triggers can change without a rebuild. - [Preview an Email Across Real Inboxes](https://docs.brew.new/changelog/posts/preview-emails-across-real-inboxes.md): See exactly how a design renders in Gmail, Outlook, Apple Mail, iOS, and Yahoo before you send it, with a screenshot from every client. - [Brew MCP](https://docs.brew.new/changelog/posts/mcp-oauth.md): Run your email marketing from Claude, Cursor, or any AI assistant over MCP. Connect by signing in with Brew, with no API key to copy. - [Multi-Brand](https://docs.brew.new/changelog/posts/multi-brand.md): Run more than one brand from a single Brew account. Each brand keeps its own brand file, contacts, domains, and analytics. - [Your Brand as Markdown](https://docs.brew.new/changelog/posts/bring-your-own-brand-file.md): Brew writes email-design.md and image-style.md from your site, editable like any doc, and reads your own brand files on top. - [Visual Email Editor](https://docs.brew.new/changelog/posts/visual-email-editor.md): Edit text, images, and links directly in the email preview. Click any element to change it without a prompt or a regenerate. - [Reference Emails](https://docs.brew.new/changelog/posts/reference-emails.md): Give Brew an email you like and it matches that layout on every new one you generate, so your sends stay visually consistent without a template. - [Trigger Emails from Stripe, Clerk, Shopify, and More](https://docs.brew.new/changelog/posts/trigger-emails-from-integrations.md): Connect an event source and its events fire your Brew automations directly, with no webhook glue to write and no per-event setup step. - [Connect Your DNS Automatically](https://docs.brew.new/changelog/posts/connect-dns-automatically.md): Verify your sending domain in one click, with no copying records into your DNS provider by hand. Supported registrars connect automatically. - [Send Your First Email with the Public API v1](https://docs.brew.new/changelog/posts/public-api-v1.md): Get a key and go from a prompt to a sent, on-brand email in about five lines of curl. The full v1 surface: designs, sends, analytics, and automations. - [ESP Integrations: Braze, Klaviyo, Mailchimp, and More](https://docs.brew.new/changelog/posts/esp-integrations.md): Connect the ESP you already use. Export a Brew email as a reusable template to eleven providers, or send directly through Customer.io. - [Templates Gallery](https://docs.brew.new/changelog/posts/templates-gallery.md): Browse and remix real email templates from other brands, or turn any email you've built or forwarded in into a reusable template. - [Analytics Dashboard](https://docs.brew.new/changelog/posts/analytics-dashboard.md): Track delivered, opened, clicked, and bounced events across emails, automations, and individual sends, with geographic data and recipient search. - [Brand Extraction](https://docs.brew.new/changelog/posts/brand-extraction.md): Enter any website URL and Brew extracts your logo, colors, fonts, and brand voice in about 30 seconds, then uses them on every email it makes. - [AI Email Creation](https://docs.brew.new/changelog/posts/ai-email-creation.md): Describe what you want in plain English and Brew generates a complete, responsive, on-brand email, ready to edit on the canvas or send as is. - [API Changelog](https://docs.brew.new/changelog/api.md): Breaking changes, new endpoints, renames, and SDK updates for the Brew Public API, newest first, with the migration each one needs. - [Terms of Service](https://docs.brew.new/legal/terms-of-service.md): The legal terms that govern your use of Brew's services, including accounts, acceptable use, payment, liability, and termination. - [Privacy Policy](https://docs.brew.new/legal/privacy-policy.md): How Brew collects, uses, shares, and protects your personal information, and the choices and rights you have over your data. - [Acceptable Use Policy](https://docs.brew.new/legal/acceptable-use-policy.md): The rules for sending with Brew: consent requirements, prohibited content and practices, and the sending standards every account must meet. - [Data Protection Addendum](https://docs.brew.new/legal/data-protection-addendum.md): The Data Protection Addendum that governs how Brew processes personal data on behalf of customers, including subprocessors and safeguards. - [GDPR and Your Data](https://docs.brew.new/legal/gdpr-and-your-data.md): How Brew supports GDPR compliance: your rights as a data subject, how personal data is processed, and how to make data requests. - [Subprocessors](https://docs.brew.new/legal/subprocessors.md): Current subprocessors and service providers Brew uses to deliver its services ## OpenAPI Specs - [openapi-public-v1](/api-reference/openapi-public-v1.yaml) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.