TypeScript Resource Surface

Every resource and method in the Brew TypeScript SDK, from contacts and emails to sends and automations, with the HTTP endpoint each maps to.

Current Client Surface

The TypeScript SDK is resource-oriented.

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

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

Resources and Methods

Resource	Methods
brew.analytics	overview(), automations(), events(), eventsAll(), eventCounts({ groupBy?, bucket? })
brew.apiKeys	list(), create(), revoke()
brew.audiences	list(), get(), create(), fromEvents(), duplicate(), update(), delete()
brew.automations	list(), get(), create(), patch(), publish() / unpublish() (convenience wrappers over patch({ published })), delete(), test(), run()
brew.automations.audienceRuns	list(), get(), pause(), resume(), cancel()
brew.automations.runs	list(), get(), cancel()
brew.automations.triggerInstances	list(), listAll(), get()
brew.automations.triggers	list(), get(), create(), patch(), delete(), fire(), readiness(), getContract(), putContract(), validatePayload()
brew.brand	get() ({ include } embeds identity / emailDesign / imageStyle / logos), patch() / update(), getImages({ q?, kind?, sort?, limit?, cursor? }), deleteImage(assetId)
brew.brands	list(), get({ brandId }), create() (organization keys with the brands scope)
brew.chats	list({ limit?, cursor? }), listAll(), get(chatId)
brew.contacts	list(), get(), search(), searchAll(), count(), countBy(), upsert(), upsertMany(), patch(), delete(), deleteMany(), validate(), importCsv()
brew.content	generateImage(), gif({ from }), transform({ operation }), htmlToPng(), addImage({ imageUrl } | { imageUrls } | { uploadId }), createImageUpload({ fileName, contentType, size }), uploadImage({ file, fileName, contentType? }) (opens the upload, sends the bytes, and adds the image; see Upload a Local Image)
brew.domains	list(), get(), add(), verify(), health({ domainId, include? }), updateSettings(), delete()
brew.domains.unsubscribes	list(), add(), remove(), import(), export() (a marketing domain’s own unsubscribe list)
brew.emailGroups	list(), get(), create(), update(), delete()
brew.emails	list(), get(), generate(), import(), importFigma(), clone(), edit(), restore(), delete(), auditEmail(), getAudit(), previewClients(), getClientPreview(), export(), send()
brew.emails.comments	list({ emailId, include?, limit?, cursor? }) or list({ emailId, commentId, messagesCursor? }) (a design’s open comment threads, or one thread), listAllMessages({ emailId, commentId }) (one thread’s messages, newest first; see Comments)
brew.emails.inboxPlacementTests	create(), list(), get()
brew.fields	list(), get(), create(), delete()
brew.flows	list(), get()
brew.health	get()
brew.help	get()
brew.insights	list({ state?, severity?, include?, limit?, cursor? }), get(insightId) (see Read Brew Insights)
brew.integrations	list()
brew.notifications	list({ type?, limit?, cursor? }), listAll({ type? })
brew.payloadContracts	infer()
brew.sends	list(), listAll(), get(), cancel(), pause(), resume()
brew.templates	list(), get()
brew.usage	get()

A client is pinned to one brand at a time. A brand-scoped key resolves its own, so you pass nothing. An organization-scoped key names one: set brandId in the client config, or call brew.withBrand(brandId) for a client that differs only in the brand it acts on. Either way the SDK sends it as the X-Brand-Id header, never as a brandId body field.

brands, templates, flows, usage, and apiKeys are organization-level and never send that pin. See Organization and brand scope and API authentication for the complete scoping and permission contract.

Every collection has two reads. list(query) pages the collection; get(id) returns the bare row, the same object a write returns. The id is a positional argument, never a query filter, and include is a detail-read option that embeds heavier fields:

List	Detail read	include opt-ins
brew.audiences.list()	get(audienceId, { include? })	count, build
brew.automations.list()	get(automationId, { include? })	graph, versions
brew.automations.audienceRuns.list()	get(audienceRunId)	none
brew.automations.runs.list()	get(automationRunId, { include? })	logs
brew.automations.triggerInstances.list()	get(triggerInstanceId)	none
brew.automations.triggers.list()	get(triggerEventId, { include? })	skill
brew.contacts.list()	get(email, { include? })	openProfile (needs the emails scope as well)
brew.domains.list()	get(domainId)	none
brew.emailGroups.list()	get(groupId)	none
brew.emails.list()	get(emailId, { include?, emailVersionId?, runId? })	html, versions
brew.emails.inboxPlacementTests.list({ emailId })	get(emailId, testId)	none
brew.fields.list()	get(fieldName)	none
brew.flows.list()	get(slug, { include? })	html
brew.insights.list()	get(insightId)	none
brew.sends.list()	get(sendId, { include? })	events
brew.templates.list()	get(templateId, { include? })	html

These reads also take include, outside the detail-read pattern:

Method	include opt-ins
brew.brand.get({ include? })	identity, emailDesign, imageStyle, logos
brew.fields.list({ include? })	coverage
brew.domains.health({ domainId, include? })	scoreHistory, scoreRuns
brew.insights.list({ include? })	pulse, report, suggestions, memo
brew.emails.comments.list({ emailId, include? })	messages
brew.contacts.search({ include? })	openProfile (an array in the request body)

Passing an id as a list filter now returns 400. If you are migrating from a list({ emailId }) call that read data[0], see the v1 migration guide.

One read sits outside that shape: brew.contacts.search({ filters, audienceId?, search?, sort, count?, include?, cursor }) stays for filter bodies richer than the list() query, and brew.contacts.get(email) is the single-address read. include: ['openProfile'] on a search attaches each contact’s open-time profile and caps the page at 10 contacts.

The public SDK surface is deterministic-only: brew.automations and brew.automations.triggers do not expose AI authoring methods. AI body generation is still available on brew.emails.generate({ prompt }); chain it with brew.automations.create({ … }) to assemble automations programmatically. To ingest existing markup as an editable design, use brew.emails.import({ format, content }).

Paginated list and search methods use the standard { data, pagination } envelope. See Pagination for cursor semantics. Manual-audience run history joined that shape in v1: brew.automations.audienceRuns.list({ automationId?, status?, limit?, cursor? }) now pages like every other list instead of capping at limit. sends.listAll, automations.triggerInstances.listAll, contacts.searchAll, analytics.eventsAll, chats.listAll, and notifications.listAll are async iterators that page through the whole result set for you via the shared autoPaginate helper, and emails.comments.listAllMessages walks one comment thread back to its first message. Those are the SDK’s auto-pagers; every other list is paged by hand with cursor. notifications.listAll keeps going through short and empty pages, because a notifications page can hold fewer rows than limit while hasMore is true.

The SDK exposes the full strictly typed manual-audience lifecycle:

const preview = await brew.automations.run({
  automationId: 'M3nRk8LqW2xT5vBp9YcZd',
  dryRun: true,
})

const started = await brew.automations.run(
  {
    automationId: 'M3nRk8LqW2xT5vBp9YcZd',
    scheduledAt: '2026-07-21T15:00:00.000Z',
  },
  { idempotencyKey: 'launch-renewal-2026-07-21' },
)

// Pause, resume and cancel are three methods taking the run id, not one
// `control({ action })` call.
if ('audienceRunId' in started) {
  await brew.automations.audienceRuns.pause(started.audienceRunId)
  await brew.automations.audienceRuns.resume(started.audienceRunId)
  await brew.automations.audienceRuns.cancel(started.audienceRunId)
}

brew.brand.get() is read-only. It returns the brand the client acts on (the key’s own brand, or the pinned one) plus its extraction readiness. brew.brands is different: it lists, creates, and polls brands across the organization.

brew.help.get() hits GET /v1/help, a no-auth, machine-readable catalog (auth, scopes, rate limits, per-operation credit metering, the error envelope, and the full endpoint list) any MCP server or agent can parse to self-discover the API.

Common Flow: Trigger → Emails → Automation → Publish → Fire

End-to-end deterministic recipe: create a custom trigger, mint each email body in parallel, assemble the graph referencing those emailIds, publish, and fire. Every step returns a typed result.

The subject and previewText below carry merge tags, resolved against the trigger payload when the event fires.

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

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

// 1. Create the trigger (deterministic shape, provider is hardcoded brew_api).
//    Create returns the bare trigger row (HTTP 201).
const trigger = await brew.automations.triggers.create({
  title: 'Subscription Renewed',
  description: 'Fires when a subscription is renewed.',
  payloadSchema: {
    type: 'object',
    fields: [
      { key: 'email', type: 'string', required: true },
      { key: 'plan', type: 'string', required: true },
      { key: 'amount', type: 'int', required: true },
    ],
  },
})

// 2. Pre-mint each email body. These rows are referenced by sendEmail
//    nodes inside the automation graph.
const [welcome, gettingStarted] = await Promise.all([
  brew.emails.generate({
    prompt: 'Thank-you email for a successful renewal.',
  }),
  brew.emails.generate({
    prompt:
      'Getting-started tips for renewed subscribers, focus on the Pro features.',
  }),
])

// 3. Assemble the automation graph; sendEmail nodes reference the
//    pre-minted emailIds + emailVersionIds.
const automation = await brew.automations.create({
  name: 'Renewal welcome flow',
  triggerEventId: trigger.triggerEventId,
  nodes: [
    {
      id: 'trg',
      label: 'On renewal',
      type: 'trigger',
      config: { triggerEventId: trigger.triggerEventId },
    },
    {
      id: 'send_welcome',
      label: 'Welcome',
      type: 'sendEmail',
      config: {
        emailId: welcome.emailId,
        emailVersionId: welcome.emailVersionId,
        domainId: 'dom_brand_primary',
        subject: 'Welcome back, {{ firstName | there }}!',
        previewText: 'Quick thanks + 2 things to try first.',
      },
    },
    {
      id: 'wait_2d',
      label: 'Wait 2 days',
      type: 'wait',
      config: { duration: 2, unit: 'days' },
    },
    {
      id: 'send_getting_started',
      label: 'Getting started',
      type: 'sendEmail',
      config: {
        emailId: gettingStarted.emailId,
        emailVersionId: gettingStarted.emailVersionId,
        domainId: 'dom_brand_primary',
        subject: 'Getting started with Pro',
        previewText: 'Three feature tips for your first week.',
      },
    },
  ],
  connections: [
    { from: 'trg', to: 'send_welcome' },
    { from: 'send_welcome', to: 'wait_2d' },
    { from: 'wait_2d', to: 'send_getting_started' },
  ],
})

// 4. Publish (convenience wrapper over patch({ published: true })).
await brew.automations.publish({ automationId: automation.automationId })

// 5. Fire the trigger with a real payload. The idempotency key is a
//    request option, not a body field.
const fire = await brew.automations.triggers.fire(
  {
    triggerEventId: trigger.triggerEventId,
    payload: {
      email: '[e-mail]',
      plan: 'Pro',
      amount: 4200,
    },
  },
  { idempotencyKey: 'renewal-jane-2026-04-08' },
)
// The 202 body is bare: no `{ success, code, details }` envelope.
console.log('Started automation runs:', fire.automationRunIds)

// 6. Poll the run lifecycle with the detail read.
const run = await brew.automations.runs.get(fire.automationRunIds[0]!, {
  include: 'logs',
})
console.log('Status:', run.status)

Reading Sends and Trigger Instances

Sends read and write at their own root. The write is brew.emails.send(input) (pass test: true for a one-off QA send), and the reads are brew.sends.list(query) and brew.sends.get(sendId, { include? }). Nothing about a send lives under brew.analytics any more, and analytics keeps exactly three reports: overview, automations, and the unified events feed.

Fired-trigger instances moved the same way, from analytics to brew.automations.triggerInstances.

// Send an email design to a target (write).
const accepted = await brew.emails.send({
  emailId: 'V1StGXR8_Z5jdHi6B',
  domainId: 'kx7bkh53hasmfeh5kd7sqgykt187g8ww',
  audienceId: 'jn7a8w4q8m9k2p1x7c3b5v6n9h7s2d4f',
  subject: 'Launch update',
  scheduledAt: '2026-07-01T09:00:00.000Z',
})

// The 202 carries `sendId` only. The old `runId` is gone.
// Pull the send back before it goes out (idempotent, already-canceled is a no-op).
const { status } = await brew.sends.cancel(accepted.sendId) // → 'canceled'

// Poll its lifecycle + stats, with the per-recipient event feed inlined.
// `get` returns the bare row, not a one-element list.
const send = await brew.sends.get(accepted.sendId, { include: 'events' })
console.log(send.status, send.stats?.delivered)
for (const ev of send.events ?? []) {
  console.log(ev.eventType, ev.recipient)
}

// All sends for one design, and the whole set as an async iterator.
const { data: forEmail } = await brew.sends.list({
  emailId: 'V1StGXR8_Z5jdHi6B',
})
for await (const row of brew.sends.listAll({ kind: 'campaign' })) {
  console.log(row.sendId, row.status)
}

// Fired-trigger instances (the audit trail of every trigger fire).
const { data: instances } = await brew.automations.triggerInstances.list({
  triggerEventId: 'user_signed_up',
})
const instance = await brew.automations.triggerInstances.get(
  instances[0]!.triggerInstanceId,
)

A send row reports one status vocabulary with runs, audience builds and inbox-placement tests: queued, scheduled, running, paused, completed, partially_completed, failed, canceled. The old sent, partially_sent and sending spellings are gone, and a status filter typed against them returns 400.

AutomationNodeInput: A Per-Kind Discriminated Union

AutomationNodeInput is a discriminated union by type; setting node.type narrows node.config automatically. The five node kinds map 1:1 to the server-side Zod schemas:

node.type	node.config shape
trigger	{ triggerEventId? }
sendEmail	{ emailId, emailVersionId, domainId, subject, previewText } (all five required)
wait	{ duration, unit: 'minutes' | 'hours' | 'days' | 'weeks' }
filter	{ logicalOperator, conditions[] }
split	{ mode: 'percentage' | 'condition', … }

Each sendEmail node’s subject / previewText support {{ variable | fallback }} interpolation against the trigger payload.

Source of Truth

The SDK follows the Brew OpenAPI contract. If you want the raw HTTP shape behind any method, use the API reference in this docs site.

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.