Agentic Cookbook

Send an email or build, test, publish, and fire a Brew automation with the TypeScript SDK, using saved designs and stable retry keys.

Use these recipes when your application or agent sends emails or manages automations through the SDK. You supply the trigger contract and graph; emails.generate() creates the email content.

Build a Welcome Automation

Start with a configured brand and a verified marketing domain. Set BREW_API_KEY to a brand key and BREW_DOMAIN_ID to the intended domain. For an organization key, pin a brand first.

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

const apiKey = process.env.BREW_API_KEY
const domainId = process.env.BREW_DOMAIN_ID
if (!apiKey || !domainId) throw new Error('Set BREW_API_KEY and BREW_DOMAIN_ID.')
const brew = createBrewClient({ apiKey })

const domain = await brew.domains.get(domainId)
if (!domain.sendable || domain.sendingPurpose !== 'marketing') {
  throw new Error('Choose a verified marketing domain.')
}

const trigger = await brew.automations.triggers.create({
  title: 'User Signed Up',
  payloadSchema: {
    type: 'object',
    fields: [
      { key: 'email', type: 'string', required: true },
      { key: 'firstName', type: 'string', required: false },
    ],
  },
})

const welcome = await brew.emails.generate({
  prompt: 'Create and save a friendly welcome email for opted-in contacts.',
})
if (!('emailId' in welcome)) throw new Error(welcome.response)

const automation = await brew.automations.create({
  name: 'Welcome flow',
  triggerEventId: trigger.triggerEventId,
  nodes: [
    {
      id: 'signup', label: 'Signup', type: 'trigger',
      config: { triggerEventId: trigger.triggerEventId },
    },
    {
      id: 'welcome', label: 'Welcome', type: 'sendEmail',
      config: {
        emailId: welcome.emailId,
        emailVersionId: welcome.emailVersionId,
        domainId,
        subject: 'Welcome, {{ firstName | there }}!',
        previewText: 'Here is how to get started.',
      },
    },
  ],
  connections: [{ from: 'signup', to: 'welcome' }],
})
console.log(automation.automationId, trigger.triggerEventId)

The automation starts as a draft. Creating it sends nothing.

Keep the returned IDs for the following steps. SDK Resources lists node and request conventions.

Test Before Publishing

Continue with the client and automation above. Omit testRecipient for a run that sends no mail.

const test = await brew.automations.test({
  automationId: automation.automationId,
  payload: { email: '[e-mail]', firstName: 'QA' },
})
const runId = test.automationRunIds[0]
if (!runId) throw new Error('No test run started.')

const run = await brew.automations.runs.get(runId, { include: 'logs' })
console.log(run.status, run.logs, run.testCoverage)

Repeat the run read until it finishes. Test waits fast-forward. Adding testRecipient delivers test emails to that address.

Inspect testCoverage for paths the run did not visit; use scenario to simulate engagement or force split branches.

After reviewing the test, publish and check readiness:

await brew.automations.publish({ automationId: automation.automationId })
const readiness = await brew.automations.triggers.readiness(trigger.triggerEventId)
console.log(readiness.ready, readiness.blockers)

Publishing enables future trigger events to start runs. The SDK applies the change directly. Readiness checks the credential and published automations without firing.

Fire from Your Backend

Send the real event payload after publishing. Use one retry key per source event.

const fire = await brew.automations.triggers.fire(
  {
    triggerEventId: trigger.triggerEventId,
    payload: { email: '[e-mail]', firstName: 'Jane' },
  },
  { idempotencyKey: 'signup-event-001' },
)
console.log(fire.triggerInstanceId, fire.automationRunIds, fire.notStarted)

This starts live runs. The recipient must have opted in for marketing. For transactional flows, choose a transactional-purpose domain and a suitable event such as an order or password reset.

Inspect the fire with automations.triggerInstances.get(fire.triggerInstanceId). Read each started run with automations.runs.get(runId, { include: 'logs' }). The retry key is a request option; Idempotency owns replay behavior.

Reuse a Saved Design

Search ready designs before generating another one:

const page = await brew.emails.list({ search: 'welcome', status: 'ready' })
const existing = page.data[0]
let reusableEmailId = existing?.emailId
if (!reusableEmailId) {
  const generated = await brew.emails.generate({ prompt: 'Create and save a welcome email.' })
  if (!('emailId' in generated)) throw new Error(generated.response)
  reusableEmailId = generated.emailId
}
const design = await brew.emails.get(reusableEmailId, { include: 'versions' })
console.log(design)

The list returns one page. Pagination explains how to inspect further pages.

Send to an Audience

With a configured brew client, choose a ready design, a verified marketing domain, and an opted-in audience. Replace the IDs below and send yourself a test before launching:

const send = await brew.emails.send(
  {
    emailId: 'YOUR_EMAIL_ID',
    domainId: 'YOUR_DOMAIN_ID',
    audienceId: 'YOUR_AUDIENCE_ID',
    subject: 'Your October newsletter',
  },
  { idempotencyKey: 'newsletter-send-001' },
)
if (!('sendId' in send)) throw new Error('Expected a production-send response.')
console.log(send.sendId, send.status)

This starts a production send directly. Keep sendId for brew.sends.get(sendId). pending_approval means an administrator must approve the send before delivery. Monitor Email Sends owns statuses and delivery results.

Edit a Published Graph

Use automations.patch({ automationId, nodes, connections }) to save graph edits as a draft. Then publish that version with automations.publish({ automationId, automationVersionId }).

Graph edits and published cannot share one patch request. The existing live version continues until you publish the new one.

For manual-audience flows, use automations.run({ automationId, dryRun: true }) to preview, then omit dryRun to launch. Keep the returned audienceRunId for audienceRuns.pause(), resume(), or cancel().

See Error Handling and the Error Catalog for recovery.

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.

Ask ChatGPT or Claude

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

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.