SDK Overview

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.

Overview

Brew currently ships an official TypeScript SDK for the public API.

It is a thin, typed wrapper over the same /api/v1 endpoints documented in the API reference. The SDK does not invent a second contract. It follows the OpenAPI source of truth.

For the same coverage from a terminal, a script, or a CI job, see the Brew CLI. It wraps the same endpoints and ships as a Homebrew tap, an npm package, or a standalone binary.

Current SDK

SDK	Package	Install
TypeScript	@brew.new/sdk	npm install @brew.new/sdk

What You Get

• Typed request and response shapes.
• One client with resource methods like brew.contacts.upsert(...).
• Automatic retries for safe retry cases.
• Auto-generated idempotency keys on POST.
• Typed BrewApiError handling for non-2xx responses.

Current TypeScript SDK Resources

The TypeScript SDK exposes every public v1 resource. Reads are flat: one list() per resource that returns a { data, pagination } collection, or a single row when you pass its id (list({ emailId }), list({ audienceId }), …). ?include= opt-ins (html, versions, graph, count, events, logs) embed the heavier detail on demand.

Resource	Methods	Notes
brew.usage	get	Plan, credit balance, and email-send quota.
brew.analytics	overview, campaigns, automations, events, eventsAll	App-parity overview totals, rates, and timeseries plus the unified event explorer. overview() accepts composable source, automation, email, audience, trigger, domain, and time-window filters.
brew.analytics.sends	list, listAll	The single send read. list({ sendId, include: 'events' }) returns one send + its per-recipient events; list({ emailId }) filters to a design. Writes stay on brew.emails.send.
brew.analytics.triggerInstances	list, listAll	Fired-trigger instance history (list({ triggerInstanceId }) for one).
brew.automations	create, list, patch, publish, unpublish, delete, test, run	Deterministic graph; every sendEmail node pins emailVersionId. run({ automationId, dry_run?, scheduledAt?, gradualSend? }) previews or starts a manual-audience run. publish() / unpublish() are convenience wrappers over patch({ published }).
brew.automations.triggers	create, list, patch, delete, fire	Deterministic create (brew_api provider hardcoded server-side) → bare row. list({ triggerEventId }) for one; patch is metadata-only; gate firing via automation.published.
brew.automations.runs	list	Read-only per-recipient execution history. list({ automationRunId, include: 'logs' }) returns one run + its logs[].
brew.automations.audienceRuns	list, control	Manual-audience run lifecycle. List or fetch one run, then control({ audienceRunId, action: 'pause' | 'resume' | 'cancel' }).
brew.emails	generate, import, importFigma, clone, edit, list, auditAccessibility, previewClients, createInboxPlacementTest, getInboxPlacementResults, export, restore, delete, send	AI body generation via generate({ prompt }); import({ format, content }) ingests existing HTML/MJML/JSX into an editable design, and importFigma({ figmaUrl, format? }) transpiles a frame through the brand’s connected Figma integration and returns JSX or HTML (deterministic, free). list({ emailId, include: 'html,versions' }) returns one design (carries previewImage). previewClients renders it in real inboxes; createInboxPlacementTest / getInboxPlacementResults check whether it lands in inbox or spam. export({ provider }) writes it to a connected ESP. send(input) delivers a design. Pass test: true for a one-off QA send. Send reads live on brew.analytics.sends.
brew.sends	cancel, pause, resume	cancel(sendId) cancels a scheduled or queued send → { sendId, status: 'canceled' }. Idempotent (already-canceled → 200); 409 once the send is sending / sent / failed, 404 for an unknown / cross-brand id. pause(sendId) / resume(sendId) are the reversible pair for an in-flight gradual send, halting and restarting the ramp without discarding it.
brew.contacts	upsert, patch, delete, search, validate, importCsv	The contact read is search({ filters, audienceId?, search?, sort, count?, cursor }), by-email = a { field: 'email', operator: 'equals' } filter. upsert / delete take a single contact or a batch (≤ 1000).
brew.content	generateImage, gif, transform, htmlToPng, addImage	Credit-metered media generation + image ops. gif({ from }) and transform({ operation }) are discriminated unions.
brew.fields	list, create, delete	Custom contact fields.
brew.audiences	list, create, update, delete	Saved audiences. list({ audienceId, include: 'count' }) returns one audience + its live member count.
brew.domains	list, add, verify, health, updateSettings, delete	Sending domains. health({ domainId }) returns authentication, reputation, placement, warmup, score, and actionable signals in one read.
brew.brand	get, patch, update, getImages	Brand readiness + design context. get({ include }) embeds identity / emailDesign / imageStyle / logos; patch() (alias update()) writes them; getImages({ q?, type?, aspectRatio? }) searches the brand image library (q = credit-metered semantic search; no q = a free browse).
brew.templates	list	Org-wide public template catalog (rows carry html + previewImage).
brew.help	get	No-auth machine-readable API catalog (GET /v1/help).

Every authenticated resource above resolves to the one brand bound to the API key. The SDK does not send X-Brand-Id or accept a brandId request field. The public template catalog is the only organization-wide read; help and health are public. Create and manage brand-bound keys at brew.new/settings/api. See API authentication for the full scoping and permission contract.

Other Languages

The TypeScript SDK is the only one Brew currently ships as a typed, versioned wrapper. For Python / Go / Ruby / Java / PHP / Swift / Kotlin / .NET, generate a client from the canonical OpenAPI 3.1 spec. See Generate your own SDK for the recommended generators and one-command scaffolds. The spec lives at:

• https://brew.new/openapi/public-api-v1.yaml: served from the API host
• https://docs.brew.new/api-reference/openapi-public-v1.yaml: served from this docs site

If you want REST directly (no codegen), every endpoint works fine with curl / httpx / fetch. See the cURL examples on every generated Public API v1 endpoint page.

SDK or REST API

Use the SDK

Use the SDK when you want:

• Type safety.
• Less HTTP boilerplate.
• Built-in retries and idempotency support.
• A resource-oriented client surface.

import { createBrewClient } from '@brew.new/sdk'

const brew = createBrewClient({
  apiKey: process.env.BREW_API_KEY!,
})

const { data: domains } = await brew.domains.list()

Use REST directly

Use REST directly when you:

• Are not in TypeScript.
• Want direct control over raw requests.
• Are building your own wrapper.

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

Determinism vs AI Authoring

The SDK and HTTP surfaces are intentionally deterministic for graph authoring. AI is scoped to email body content only, via brew.emails.generate({ prompt }).

Layer	AI involved?
Trigger payload schema (brew.automations.triggers.create)	Never: the caller supplies explicit { key, type, required } fields.
Automation graph (brew.automations.create / patch)	Never: the caller supplies explicit { nodes, connections }.
Email body (brew.emails.generate)	Yes: the email subagent renders HTML from the prompt.
Subject / preview line (sendEmail.config.subject)	Optional {{ variable | fallback }} interpolation against the trigger payload, evaluated at fire time.

If you want free-form natural-language authoring of a whole graph, use the chat-side orchestrator in the dashboard instead.

Suggested Reading Order

1. Authentication
2. TypeScript Installation
3. TypeScript Quickstart
4. API Reference

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

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.

Talk to Our Team

Schedule a Call

Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions.

Call Us Directly

Need immediate assistance? Reach us at [phone] for urgent issues or time-sensitive questions.

Slack Channel

Our preferred support channel. You’ll receive an invite after signup for direct founder support and fast responses.

Email Support

Contact us at [e-mail] for detailed inquiries or if you prefer not to use Slack.