Skip to main content
Looking for user-facing product updates? See the main changelog. Everything below is scoped to the Public API v1 surface and the TypeScript SDK.
ChangedNew
MCP contact imports ask for approval first; the image, GIF and image-edit tools return to MCP outside Claude

MCP Import Approval and Media Tools

  • MCP import_contacts and import_contacts_csv return a confirmation request first on OAuth and organization connections. The request shows how many rows create a subscribed contact, how many opt out, and the consent record the call wrote. Repeat the call with confirmed: true and the returned confirmation_id to run it. A consent argument doesn’t skip the request. dryRun: true and brand API-key connections don’t pause. POST /v1/contacts/import and POST /v1/contacts/import-csv are unchanged. See Confirmation.
  • generate_image, create_gif and transform_image are MCP tools again on every client except Claude. Claude web, Claude Desktop and Claude Code don’t list them and can’t call them. Over MCP, generate_image takes prompt, mode, aspectRatio, image1 and image2. The adCreative inputs stay on POST /v1/content/generate-image. search_brand_images still lists logos and brand images only.
  • Images and GIFs the email agent generates are saved to the brand’s Assets page from every entry point. A design made or edited over MCP used to keep its generated images out of the library, and generated GIFs were never saved. Both now land under Generated, as images from the app and POST /v1/emails already did.
New
List the live events connected sources send, read one, and get its trigger

Live Integration Events

Connected live sources list the events they send: a PostHog project’s own events, and the Stripe and Shopify app catalogs (GetBrew/brew-v2#2411). Each one can start an automation.
  • New GET /v1/integrations/events (listIntegrationEvents) returns { data, sources, pagination }, source by source. Each event has an eventId, the provider’s eventKey, Brew’s label and lifecycle stage, its modelRoles, volume30d, and its triggerEventId once it is a trigger. Filter with provider, query and kind. A page can hold fewer rows than limit, so follow the cursor until hasMore is false.
  • New GET /v1/integrations/events/{eventId} (describeIntegrationEvent) returns one event with each property’s template variable, and whether it holds personal data (isPersonal) or is suggested for personalization (isPersonalization). An event listed without its properties, or described more than a day ago, is described at the provider first, on the account’s read budget. propertiesStatus says how current the properties are: current, stored, rate_limited (with retryAfterSeconds when the provider gave one) or unavailable. A spent budget still answers 200 with what Brew stored.
  • Both reads need the automations scope, the same scope as the trigger request.
  • New POST /v1/automations/triggers/integration-events (ensureIntegrationEventTrigger) takes { "eventId": "..." } and returns the event’s trigger as IntegrationEventTriggerSaved: the trigger row without brewEvent and skill, plus created and the same propertiesStatus and retryAfterSeconds. It answers 201 when it creates the trigger and 200 with created: false afterwards. The provider starts sending the event once an automation using it is published.
  • New error codes INTEGRATION_EVENT_NOT_FOUND (404, an unknown or other-brand eventId) and INTEGRATION_RECONNECT_REQUIRED (409, a catalog event whose trigger left with its connection). The trigger request can also answer 409 TRIGGER_LIMIT_REACHED.
  • Trigger rows can carry provider: "posthog".
  • MCP list_integration_events, describe_integration_event and ensure_integration_event_trigger. The next SDK release adds brew.integrations.events.list(), brew.integrations.events.get() and brew.automations.triggers.ensureIntegrationEvent(), and the next CLI release adds integrations events list, integrations events get and automations triggers ensure-integration-event.
ChangedFixed
Pausing a run held at the plan limit is refused; automation run lifecycle fixes and doc corrections

Automation Run Lifecycle Fixes

  • Pausing a manual-audience run held at the plan limit returns 409 RUN_NOT_PAUSABLE (GetBrew/brew-v2#2838). It used to return 200 paused and keep the hold, so the run still resumed on its own once the monthly send allowance had room. This covers POST /v1/automations/audience-runs/{audienceRunId}/pause and MCP pause_audience_run. Cancel the run to stop it. Pausing a run its operator already paused still returns 200 and changes nothing, like a gradual send.
  • PATCH /v1/automations/{automationId} with { "paused": true } on a manual-audience automation returns 422 AUTOMATION_NOT_PAUSABLE, as documented, instead of 422 AUTOMATION_NOT_PUBLISHED. A manual-audience automation is never published; pause its runs instead.
  • Canceling an event or test run between two steps adds no log row; the run’s status and error record the cancel. The step that just finished keeps its own outcome; before, a closing skipped row landed on it, so a delivered send read as skipped.
  • Doc corrections, with no behavior change:
    • POST /v1/automations/audience-runs/{audienceRunId}/cancel no longer lists 503 RUN_STOP_FAILED, which it never returns. A repeat cancel returns 409 RUN_NOT_CANCELLABLE; MCP cancel_audience_run no longer calls it idempotent.
    • 409 RUN_NOT_PAUSED is returned for any run that is neither paused nor failed, not only a running one.
    • DELETE /v1/automations/{automationId} deletes event and test runs. Manual-audience runs that had not finished are canceled and kept, so GET /v1/automations/audience-runs still lists them.
    • MCP list_automation_runs waits up to 24 seconds for a running test run, then returns it as queued or running.
ChangedNew
Automation delete, test and run refusals get codes that name the state

Clearer Automation Refusals

Three automation endpoints now say why they refused (GetBrew/brew-v2#2839). The same codes reach MCP delete_automation, test_automation and run_automation.
  • New 409 AUTOMATION_IN_PROGRESS while the agent is still generating the automation. Wait for it to finish, then retry. It replaces 500 INTERNAL_ERROR on DELETE /v1/automations/{automationId}, 400 INVALID_PAYLOAD on POST /v1/automations/{automationId}/test and 422 INVALID_REQUEST on POST /v1/automations/{automationId}/run.
  • New 422 AUTOMATION_NOT_READY when the saved flow cannot run: a step is incomplete or invalid, or generation failed. On run it also covers a send step whose sender domain is not verified and an audience the run cannot resolve. The message names the problem. On test this used to be 400 INVALID_PAYLOAD, and on run it was 422 INVALID_REQUEST. 400 INVALID_PAYLOAD now means only that payload does not match the trigger’s schema.
  • New 422 AUTOMATION_NOT_RUNNABLE when run is called on an event automation, which runs when its trigger fires. It was 422 INVALID_REQUEST.
  • DELETE /v1/automations/{automationId} no longer lists 404 AUTOMATION_NOT_FOUND. An unknown id has always returned 200 { "deleted": false }. A brand removed during the call returns 404 BRAND_NOT_FOUND.
  • Resuming a failed run whose remaining send step can no longer send (POST /v1/automations/audience-runs/{audienceRunId}/resume, MCP resume_audience_run) returns 422 AUTOMATION_NOT_READY instead of 422 INVALID_REQUEST (GetBrew/brew-v2#2841). The message names the step, for example a sending domain that is no longer verified.
  • If your client matches on the old codes for these cases, match on the new ones.
ChangedBreakingNew
GIFs from a prompt or image are one GPT Image 2.6 generation; frameCount added; videoUrl and generatedImageUrl removed

Faster GIF Generation

  • POST /v1/content/gif with from: "prompt" or "image" is one GPT Image 2.6 generation (GetBrew/brew-v2#2668), usually 7–20 seconds instead of a video render. Prices are unchanged: 20 credits from a prompt, 10 from an image or a video.
  • New frameCount (2–16, default 9) for a prompt or image GIF. fps (1–24, default 5) sets playback speed, so the defaults loop in 1.8 seconds. The response adds frameCount.
  • fps changes meaning for prompt and image: it used to sample a fixed 5-second clip and now plays the frames, so a loop lasts frameCount / fps seconds. A request that sent fps: 15 alone now loops in 0.6 seconds; for smoother motion raise frameCount (12–16) with fps 8–10.
  • Frame sizes: 16:9 is 768×432, 9:16 432×768, 1:1 640×640.
  • Breaking: the response no longer has videoUrl or generatedImageUrl; no source video or intermediate still is made.
  • An imageUrl the model cannot read, or a request it refuses, returns 422 CONTENT_OPERATION_FAILED. from: "video" is unchanged.
  • SDK and CLI: content.gif types follow, and brew-cli content gif takes --frame-count.
Changed
A repeat audience-run pause is documented as idempotent

Repeat Audience-Run Pause Returns 200

  • Pausing a manual-audience run that is already paused returns 200 and changes nothing, like a gradual send. This covers POST /v1/automations/audience-runs/{audienceRunId}/pause and MCP pause_audience_run. The API has always behaved this way; the docs said 409 RUN_NOT_PAUSABLE. A run held at the plan limit stays held. 409 RUN_NOT_PAUSABLE is returned only for a run that is scheduled, completed, failed or canceled.
ChangedBreakingNew
Three MCP tools fold into their siblings; analytics eventType is a fixed list; automation PATCH keeps stored edges; test emails reach only allowed recipients

Folded MCP Tools, Event Types and Test Recipients

  • Three MCP tools are removed (GetBrew/brew-v2#2592). Each job moved to a sibling tool, and the REST routes are unchanged:
    • get_brand_status: call get_brand with the brandId as brand_id until ready is true. Over HTTP, GET /v1/brands/{brandId} still polls.
    • get_insight: call list_insights with the finding’s insightId. It can’t be combined with state, severity, include, limit or cursor.
    • import_domain_unsubscribes: call add_domain_unsubscribes with csv (and column) in place of emails.
    The MCP tool catalog now has 89 tools on an organization connection and 88 on a brand connection.
  • Email import warns text_dropped (GetBrew/brew-v2#2604). When the editable design cannot carry some source words, assetReport.warnings names them once as { code: "text_dropped", location: "markup", host: "<words>" }; version 1 keeps the exact source.
  • MCP list_brands lines name a brand that isn’t ready, with its status and, for a failed extraction, the reason. An organization’s own failed brand passed as brand_id answers BRAND_NOT_FOUND saying the brand failed extraction.
  • POST /v1/emails takes an optional title, the canvas name (1 to 200 characters), and returns it. Without one, Brew names the canvas from subjectLine, or else from the prompt’s first sentence, cut to 60 characters. Before, the name was the first 120 characters of the prompt.
  • GET /v1/analytics/events takes one of 26 eventType values, spelled exactly (opened, not open; clicked, not click). Any other value is now refused with 400 INVALID_REQUEST. The endpoint’s page in the Public API v1 reference lists all 26.
  • A sendId read on GET /v1/analytics/events spans the whole send unless from/to are given, for the feed and for groupBy/bucket counts. Before, it read the last 7 days like other filters.
  • Breakdown groups carry recipients (GetBrew/brew-v2#2582). On a group of opened, clicked or delivered events (not grouped by link), it counts each recipient once per message within range; count still counts events. See Per-Contact Engagement.
  • Test emails reach only allowed recipients (GetBrew/brew-v2#2578). A test: true send (POST /v1/sends, MCP send_email) and a testRecipient on POST /v1/automations/{automationId}/test or MCP test_automation may go only to a teammate with access to the brand, an address on a verified sending domain of the brand, or, for a signed-in person (not an API key), their own address or one on their company domain. Anyone else is a 422 TEST_RECIPIENT_NOT_ALLOWED, and details.recipients lists the refused addresses.
  • PATCH /v1/automations/{automationId} keeps the stored edges when connections is omitted, also when nodes are sent. Before, nodes without connections cleared every edge; send connections: [] to clear them now. An edge whose end no longer exists is refused with 400 AUTOMATION_GRAPH_INVALID.
  • expectedBaseVersionId works alone. Send the automationVersionId you read; the save answers 409 AUTOMATION_VERSION_CONFLICT if the automation changed since. expectedBaseDefinitionSha256 is an optional stricter guard and requires expectedBaseVersionId. Before, the two had to be sent together.
  • AUTOMATION_GRAPH_INVALID issues name the topology fault. A structure issue now carries code (such as cycle or unreachable_node). API Errors lists every kind and code.
  • A 400 INVALID_REQUEST with more than one problem lists them all in details.issues[] ({ param?, message }, at most 20). param and message still name the first. On a union field such as mode, the error names the field the matching shape missed, not “Invalid input”. API Errors shows the shape.
ChangedBreaking
Audience list operators take arrays; compact MCP contact rows; MCP limit errors name the reset; verify_domain confirms before releasing held campaigns

List Filters Take Arrays, and MCP Review Fixes

  • Audience list operators refuse a comma-separated string. On POST /v1/audiences, PATCH /v1/audiences/{audienceId} and MCP create_audience / update_audience, an in, not_in, contains_any or not_contains_any clause whose value is a string containing a comma now returns 400 INVALID_REQUEST. Send ["pro", "enterprise"], not "pro,enterprise"; a saved filter read the string as one value and matched nobody. An email in list still accepts a comma-separated string, and audiences already saved this way keep working with addEmails / removeEmails.
  • MCP search_contacts returns compact rows: address, name, subscription and suppression state, validation status and custom fields. response_format: "detailed" returns the full row. HTTP, the SDK and the CLI are unchanged.
  • response_format is accepted only by search_contacts and get_brew_capabilities. Other MCP tools refuse it as an invalid argument.
  • MCP limit errors (INSUFFICIENT_CREDITS, SEND_QUOTA_EXCEEDED, BRAND_LIMIT_REACHED, and an audience run held at the send allowance) state the limit and when it resets, without upgrade advice. HTTP copy is unchanged. See Limit Errors.
  • MCP verify_domain asks first only when it would release held campaigns. On OAuth and organization connections, a domain with held campaigns returns confirmation_required; repeat with confirmed: true and the confirmation_id.
  • MCP template results carry one id, emailId. Pass it to create_email as referenceEmailId. search_templates and get_template no longer repeat it as referenceEmailId or templateId.
  • MCP report_tool_issue inputs are camelCase: statusCode, errorCode and requestId replace status_code, error_code and request_id.
  • MCP get_brand_status: a brand connection may now omit brandId and reads its own brand. Organization connections still pass it.
  • MCP get_email_analytics filters take arrays instead of comma-separated strings: source and recipient (one rule per item), and automationIds, audienceIds and triggerEventIds in place of the singular automationId, audienceId and triggerEventId lists on the overview report (audienceIds and triggerEventIds on the events report). On the events report, groupBy takes an array of one or two fields (["eventType", "link"], not "eventType,link"), and includeMachineClicks / includeMachineOpens take booleans, not "true" / "false".
  • MCP run_automation no longer returns workflowRunId, and MCP automation run reads no longer return definitionHash. HTTP responses keep both.
ChangedBreaking
Semantic brand-image search is free; report_tool_issue covers one failed call; a repeat pause is idempotent

Free Brand-Image Search and Narrower Tool Reports

  • GET /v1/brand/images?q= is free. A semantic search no longer costs 1 credit on its first page, so it never returns 402 INSUFFICIENT_CREDITS or X-Credit-Cost. The same goes for MCP search_brand_images and the SDK’s brew.brand.getImages({ q }).
  • Search cursors page by position, like the other catalogs. Cursors stay opaque; send each one back with the q and kind it came from. Cursors from earlier searches keep working.
  • MCP report_tool_issue reports one failed call: tool and a summary, plus optional status_code, error_code and request_id. It no longer takes tool_calls, related_ids, severity, category, client or local_environment.
  • report_tool_issue no longer returns requestId; look a report up by its flareId.
  • Pausing an already-paused gradual send is idempotent: POST /v1/sends/{sendId}/pause and MCP pause_email_send return the same 200 and change nothing, instead of 409 SEND_NOT_PAUSABLE.
  • MCP list_email_comments names participants, authors and mentions by name only; GET /v1/emails/{emailId}/comments is unchanged.
  • The MCP tool catalog now shows each tool’s four annotation hints as columns.
ChangedNew
Contact updates return warnings and only changed fields; NODE_ID_REPLACED, stopInFlight on drafts, and import element_dropped warnings

Contact Update Warnings, Node Ids and Import Warnings

  • PATCH /v1/contacts/{email} returns a required warnings array (also SDK brew.contacts.update and MCP update_contact). It carries the same DATE_ORDER_ASSUMED and FIELD_TYPE_COERCED caveats a single upsert reports; see the warning codes. updated now lists only the fields whose stored value changed, and is empty, with nothing written, when every value sent matched what was stored. Code that expected at least one entry must handle an empty list.
  • JSON numbers above 9007199254740991 (2^53 - 1) are refused. Sent to a number or string custom field, such a number arrives already rounded, so the write is a 409 FIELD_TYPE_MISMATCH. Send 64-bit ids and counters as JSON strings to a string field.
  • New NODE_ID_REPLACED warning on POST /v1/automations and PATCH /v1/automations/{automationId}. The trigger node is always stored as trigger, and an id shaped like wait-3-days (a node type, a hyphen and a slug) gets an opaque one; field names the node, the message gives the stored id, and connections point at it. Every other id is stored as sent.
  • stopInFlight works on a draft. With published: false on an automation that is already a draft, it stops the contacts still in flight; when none are, the update is a 422 AUTOMATION_NOT_PUBLISHED.
  • POST /v1/emails/import lists dropped elements. Each source element with content a design could not keep appears once in assetReport.warnings as { code: "element_dropped", location: "markup", host: "<tag>" }.
Fixed
Two writes creating one new field no longer store a value of the wrong type; FIELD_TYPE_COERCED documented

New Fields Created by Two Writes at Once

  • When two contact writes (POST /v1/contacts, POST /v1/contacts/import, POST /v1/contacts/import-csv, or MCP import_contacts and import_contacts_csv) create the same new custom field at the same moment, the first definition wins. The other write’s values are now converted to that type or refused with FIELD_TYPE_MISMATCH, exactly as if it had been sent second. Before, it could store a value of the wrong type, such as the number 5 in a string field, which filters then missed.
  • fieldsCreated now lists only the fields this request created. Before, both writes listed the field.
  • The FIELD_TYPE_COERCED warning is now documented in the warning codes: a value converted to its field’s type, with field, from (the type sent) and to (the type stored).
  • No request or response shape changed. To pin a field’s type up front, create it first with POST /v1/fields.
Fixed
CLI 0.18.1: two flags the API always refused are gone, counts point to event-counts, and failed image uploads can be recovered

CLI 0.18.1

A bug-fix release. No command that worked before stops working.
  • Two flags removed. content gif --duration and content generate-image --model now fail before the request, with a usage error (exit 2). The API refused both on every call: a GIF is a fixed 5-second clip, and Brew uses one image model.
  • Counts go to analytics event-counts. analytics events refuses groupBy and bucket in --input with a usage error that points there. It used to drop both keys and return event rows.
  • Failed image uploads can be recovered. When finishing an upload fails, the error keeps the uploadId and idempotency key. Recovery runs content add-image with that upload instead of opening a new one. See Upload a Local Image.
  • emails list shows folders. In a terminal, the GROUP column shows the folder name, or “Ungrouped”. --json output is unchanged.
New
Preview a contact import, or add only new contacts

Contact Import Previews and Add-New-Only Imports

  • dryRun: true on POST /v1/contacts/import and POST /v1/contacts/import-csv returns the response the import would return and writes nothing: no contacts, no Import History entry, no importId and no credits, even with validate: true.
  • onConflict: "skip" creates missing contacts and leaves existing ones unchanged, counting each as skipped with a CONTACT_EXISTS_SKIPPED warning (it also says when a row’s opt-out was not applied). The default, "upsert", creates and updates.
  • Both work over MCP (import_contacts, import_contacts_csv). In Brew chat they apply to CSV text; an attached file always creates and updates.
New
Email designs carry a lang field: read on GET /v1/emails/{emailId}, settable on create and edit, and in MCP

Email Language

  • New lang on email designs. The language of a design’s copy, as an ISO 639-1 code or zh-Hans / zh-Hant. Brew reads it after each content change unless a caller set it, and renders it as the HTML document’s lang (and dir for right-to-left languages) on every send and export, and in the HTML that include=html returns.
  • Read it. GET /v1/emails/{emailId} returns lang on the EmailDetail row once it has been read. It is detail-only and optional: list rows do not carry it.
  • Set it. POST /v1/emails accepts lang; omit it and Brew detects the language from the finished body. PATCH /v1/emails/{emailId} accepts lang as part of the free envelope patch, with no AI run and no new version. A value you set is kept and never re-detected; send lang: null to clear it, and Brew reads the language again.
  • MCP. get_email returns lang, and create_email and update_email_metadata accept it (null clears it on update_email_metadata). See MCP Tools.
  • SDK and CLI. The TypeScript SDK types carry lang on emails.get, emails.generate and emails.edit. The CLI adds --lang <code> to emails generate and emails edit, and --clear-lang to emails edit.
NewChanged
JSON contact import, Import History for every import, and MCP imports that create contacts

Contact Imports from Any Surface

  • New POST /v1/contacts/import. Import up to 1,000 contacts as JSON rows (the batch-create shape) in one call. It is the JSON twin of POST /v1/contacts/import-csv: SDK brew.contacts.import(), CLI brew-cli contacts import, MCP import_contacts.
  • Every import is in Import History. Batches from the API, SDK, CLI, MCP and Brew chat are listed beside app uploads. Both imports take an optional fileName to name the batch and return its importId, which each contact they write carries until a later import touches it, so you can filter to them or delete the import in the app (which removes only the contacts it created). POST /v1/contacts stays the sync path with no history entry.
  • MCP imports create contacts. MCP contract 4.0.0 replaces the update-only update_contacts_csv with import_contacts_csv, which creates missing contacts (subscribed unless a row opts out) and takes consent and validate, like the API. Refresh the connector’s tool list after upgrading.
  • Import totals and row details. summary.total equals the added, updated, failed and skipped counts combined. Each failed row has an error naming its 1-based row. CSV skip warnings name the first 100 skipped rows and summarize the rest. JSON batches fail each row of a repeated address. Inspect the errors before retrying failed rows.
New
Six more email categories, and a group filter with counts on the template gallery

More Email Categories, and Template Browse Groups

  • Six new category values on POST /v1/emails and on the category filter of GET /v1/templates: onboarding, content, event-recap, product-pitch, company-news and fundraising. The set is now 30 values, and every earlier value still works (GetBrew/brew-v2 9bf2e01f).
  • New group filter on GET /v1/templates. A browse group is every category in it: welcome-onboarding, newsletter, content, events (invitations, reminders and recaps), product-news, sales, retention, company, transactional, internal and other.
  • Counts by group. count=true counts the templates matching brand, category and group, and groupBy takes group beside brand and category. Each bucket’s key passes back as the filter of the same name.
New
A saved email whose result can't be read back answers 409 EMAIL_RESULT_UNAVAILABLE; recover it by version id

Recover a Saved Email When Its Result Can’t Be Read

POST /v1/emails and PATCH /v1/emails/{emailId} can now answer 409 EMAIL_RESULT_UNAVAILABLE. The generation or edit committed, but its completed result could not be read for the response. error.details carries committed: true, the emailId, the saved emailVersionId and the runId.Read GET /v1/emails/{emailId}?include=html with that emailVersionId to get the saved design. Don’t repeat the call: a repeat generates or edits again, and costs credits again. The code is never retried for you.
ChangedNew
Payload contract reads split by format, a secret field attribute, six fail-closed writes, test-run usage, and Loops as an export provider

Payload Contracts, Fail-Closed Writes, and Loops Export

  • Payload contract reads are split by format. GET …/contract answers one of two shapes: format: json returns fields and no content; ts, zod, jsonschema and skill return content and no fields. POST /v1/payload-contracts/infer now returns format: json with fields only. Clients that read fields off a text-format response, or content off an infer response, need to branch on format. See Typed Payload Contracts.
  • New secret attribute on contract fields. Set secret: true on a one-time code or sign-in link. The value is used only to render the email, is never stored on contacts, in logs or analytics, and cannot be used in filters, splits or recipient fields. Scalars only, never email. pii still controls log masking.
  • Two more writes fail closed. POST /v1/emails/{emailId}/inbox-placement-tests and POST /v1/automations/{automationId}/test now refuse with 503 SERVICE_UNAVAILABLE and a Retry-After header when the idempotency store or billing is unavailable, instead of running unmetered. The fail-closed set is now email audit, inbox placement tests, /v1/sends, automation test, automation run and trigger fire. See Idempotency.
  • Test runs and usage. A test run with testRecipient delivers real mail from your verified sender domain, or from the Brew test domain when none is configured, and those deliveries count toward send usage. Dry runs do not. Test runs stay out of live analytics and never update contact records.
  • Analytics windows. The spec no longer states a default from and to for event reads filtered by sendId. Pass both explicitly.
  • cursor on GET /v1/automations/audience-runs accepts up to 8192 characters (was 512).
  • Loops is an export provider. POST /v1/emails/{emailId}/export with provider: "loops" converts supported content to LMX and creates an editable campaign draft in Loops. See Loops.
New
Start automations when a contact unsubscribes (Brew-event triggers); SDK 12.4.0 and CLI 0.16.0

Unsubscribe Triggers

An automation can now start when a contact unsubscribes (GetBrew/brew-v2#2071). These are Brew events: triggers Brew starts itself. The first is contact.unsubscribed, a contact unsubscribing with an email’s link or their mail app’s one-click button.
  • POST /v1/automations/triggers/brew-events (ensureBrewEventTrigger) returns the brand’s trigger for one scope and creates it the first time. Send { "event": "contact.unsubscribed", "scope": "domain", "domainId": "…" } for one marketing domain’s list, or "scope": "all" with no domainId for every email. It answers 201 when it creates the trigger and 200 with created: false afterwards. Refusals: 400 INVALID_REQUEST, 404 DOMAIN_NOT_FOUND, 422 DOMAIN_PURPOSE_NOT_ALLOWED (a transactional domain keeps no list), and 409 TRIGGER_LIMIT_REACHED.
  • Trigger rows can carry provider: "brew_event" and a brewEvent config, and trigger instances source: "brew_event".
  • New error code TRIGGER_NOT_FIREABLE (409). Fire and readiness refuse a Brew-event trigger, and PATCH and PUT …/contract answer 422 TRIGGER_IMMUTABLE. Try its automation with POST /v1/automations/{automationId}/test. The test runs on the trigger’s sample, with any payload fields you pass laid over it, and writes no contact.
  • Payload: { email, unsubscribe: { scope, domain?, method, reasons, reasonText?, emailId?, emailTitle?, sendId?, at } }.
  • Delivery: the run emails only the contact who just opted out. Send what they need, such as a confirmation of the unsubscribe, from a transactional domain. Mail from another marketing domain reaches them only while they are still on that list, never after an unsubscribe from all. Publish refuses a flow none of whose emails could reach them.
  • MCP ensure_brew_event_trigger, SDK 12.4.0 brew.automations.triggers.ensureBrewEvent(), and CLI 0.16.0 brew-cli automations triggers ensure-brew-event.
New
Canvas embed sessions: create, refresh, and revoke a short-lived grant for one group or email

Canvas Embed Sessions

Three routes back the embedded email canvas. Call them from your backend, after you have authenticated your user and authorized the target. API keys stay server-side.
  • POST /v1/canvas/sessions creates a short-lived grant for exactly one target: { "type": "group", "groupId" } or { "type": "email", "emailId" }. Credentials are returned once, and response replay is disabled.
  • POST /v1/canvas/sessions/{sessionId}/refresh issues a new bootstrap credential for the same target and external user. It needs the original issuing authority.
  • DELETE /v1/canvas/sessions/{sessionId} revokes the session, which stops its reads, writes, and active subscriptions.
ChangedBreaking
MCP: more calls ask for approval, no contacts created from tool arguments, no AI media tools, technical-only flares

MCP Changes for the Claude Directory

The MCP connector changed for the Claude directory review (GetBrew/brew-v2#1854). The HTTP API and the SDK are unchanged except where noted.
  • Confirmation on more calls. On OAuth and organization connections, fire_trigger_event, delete_contacts, delete_contact_field, a save_automation that publishes, unpauses or stops contacts mid-flow, a resume_email_send or resume_audience_run, and a test to anyone but the connected person now return confirmation_required first, like campaigns. The same call with confirmed: true and the request’s confirmation_id runs it; the id holds for those exact arguments for 15 minutes and runs one call. See Confirmation.
  • No contacts from tool arguments. send_email no longer takes consent: inline to recipients must already be subscribed contacts. update_contact updates existing contacts only (createIfMissing and consent are gone). update_contacts_csv updates existing contacts and refuses unknown rows one by one; it no longer takes consent or validate (use validate_contacts). test_automation no longer creates the test payload’s contact. A fire_trigger_event for an address that unsubscribed is refused with RECIPIENT_UNSUBSCRIBED. Over the API, POST /v1/contacts and POST /v1/sends keep consent.
  • Removed from MCP: generate_image, create_gif and transform_image (the API keeps POST /v1/content/generate-image, POST /v1/content/gif and POST /v1/content/transform), and remove_domain_unsubscribe (the API keeps DELETE /v1/domains/{domainId}/unsubscribes/{email}).
  • Imagery made with Brew stays in the design. Over MCP, create_email and edit_email no longer save the scenes they generate to the brand library, and search_brand_images lists logos and brand images only (kind is logo or brand). GET /v1/brand/images and the app still list every kind.
  • sendingPurpose. create_domain and update_domain no longer take it. Set it in the app or with PATCH /v1/domains/{domainId}.
  • report_tool_issue takes technical diagnostics only: tool names, request ids, status and error codes, Brew ids, the client, and a summary of up to 500 characters. The narrative fields are gone.
  • create_audience with sourceAudienceId takes an optional name for the copy.
  • DELETE /v1/emails/{emailId} on an already-deleted design now returns the documented deletedAt.
Breaking
The data command is removed from the API, MCP, SDK, and CLI; typed reads answer the same questions

The Data Command Is Removed

Breaking. POST /v1/data is gone (GetBrew/brew-v2#1825). It ran a command line such as db find contacts --fields email | jq … over the brand’s tables and answered { exitCode, output, truncated }. Everyday reads now go through typed endpoints, each with its own request and response shape, scope, and rate limit.Removed:
  • POST /v1/data (runDataCommand) and the DataCommandResponse schema
  • The MCP tool query_brew_data (first shipped as run_data_command)
  • brew.data.run() in the TypeScript SDK, from SDK 12.0.0
  • brew-cli data run, from the next CLI release
  • The data topic of the MCP tool get_brew_capabilities

What to Use Instead

No equivalent: table discovery (db ls, db schema) and jq pipelines. Read the typed endpoint and filter its result; writes go through each resource’s own endpoints. The reads that only the data command used to serve (insights, comment threads, the chat list, notifications, score history, and open-time profiles) shipped first, in the entry below.A question that joined tables becomes two typed reads. For example, read an audience with GET /v1/audiences/{audienceId}, then its members with POST /v1/contacts/search and that audienceId.
  • SDK: brew.emails.list, brew.emailGroups.list, brew.contacts.search, brew.contacts.count, brew.contacts.countBy, brew.audiences.list, brew.audiences.get, brew.automations.list, brew.automations.runs.list, brew.domains.list, brew.sends.list, brew.analytics.overview, brew.analytics.events and brew.analytics.eventCounts. Since SDK 11.6.0: brew.insights.list (include adds pulse, report, suggestions, and memo) and brew.insights.get, brew.emails.comments.list, brew.chats.list, brew.notifications.list, brew.domains.health({ domainId, include: ['scoreHistory', 'scoreRuns'] }), and brew.contacts.get(email, { include: ['openProfile'] }) or brew.contacts.search({ include: ['openProfile'] }).
  • CLI: emails list, emails groups list, contacts search, contacts count, contacts count-by, audiences list, audiences get, automations list, automations runs list, domains list, sends list, analytics overview, analytics events and analytics event-counts. Since CLI 0.13.0: insights list, insights get, emails comments list, chats list, notifications list, and --include on domains health, contacts get, and contacts search. brew-cli api still sends any raw request.
New
Read insights, comment threads, chats, and notifications; domain score history and contact open-time profiles; SDK 11.6.0 and CLI 0.13.0

Read Insights, Comments, Chats, and Notifications

New typed reads, all free, cover what the app shows on the Insights page, in comment threads, in the chat list, and in the notifications bell. Two existing reads gain a domain’s score history and a contact’s open-time profile.New: GET /v1/insights lists the brand’s Brew Insights findings as the Insights page ranks them, most severe first. state=open (the default) lists active findings, and state=all adds resolved, cleared, dismissed, and stale ones. severity keeps one severity. Every page carries freshness: dataAsOf says how current the data behind the findings is, and latestAttempt.status: "failed" means they may be stale. include adds what the page shows beside the findings: pulse (the last 7 days against the 7 before), report (the latest intelligence report), suggestions (its open suggestions, up to 25), and memo (the analysis agent’s memory across runs). pulse, report, and memo are null until they exist, and suggestions is an empty array when there are none. The engine keeps at most 200 findings in view. The list is ranked again on every request, so its cursor remembers which findings it has returned: if findings are added, removed, or re-ranked above it, the next page is 400 INVALID_REQUEST with param: "cursor" instead of a page that skips or repeats findings, and you read again from the first page with the same state and severity. A change below the cursor is served when its page comes, so a finished walk returns every finding exactly once. A cursor sent with a different state or severity is refused the same way.New: GET /v1/insights/{insightId} reads one finding in full. Its frozen metrics are the only numbers to quote about it. It also carries evidence links, rationale, the detector’s method (what it measures and what resolves it), and generatedBy (the run that produced it and what that run could not see). An unknown id and another brand’s id both answer 404 INSIGHT_NOT_FOUND. Both insight reads need the emails scope and count against analytics.read. See Read Brew Insights.New: GET /v1/emails/{emailId}/comments lists a design’s open comment threads, newest activity first: commentId, target (the whole email or one element), the 12 most recent participants with participantCount, messageCount, lastMessagePreview, and a link. include=messages adds each thread’s newest messages and caps the page at 3 threads, which share a 12,000-character message budget. A thread with older messages returns messagesCursor: send it back with that thread’s commentId for the next older slice, until it comes back null. Resolving a thread deletes it, so only open threads are listed, and a commentId that isn’t an open thread answers 404 COMMENT_NOT_FOUND. An email with no threads is an empty page; an unknown email, or another brand’s, is 404 EMAIL_NOT_FOUND. In body and lastMessagePreview, each mention reads @ plus the name mentions gives with its userId. See Comments.New: GET /v1/chats lists the brand’s Brew chats, most recently active first: chatId, title, the opening prompt, Brew’s latest reply, status, origin, and a link. No transcript; GET /v1/chats/{chatId} still resumes one chat with its artifacts and recent messages.New: GET /v1/notifications lists what the app’s bell shows, newest first: generations, sends, imports, domain checks, and score runs finishing or failing. Filter with type. Any key can call it, and each row is shown only when the credential may read what it describes: contacts for imports and validations, sends or domains for sends and domain checks, and so on. api_key_created needs the all scope, and send_limit_reached reaches organization admins only, never a brand key. Comment mentions and replies reach only the person they’re addressed to, so an API key never sees one. An empty page can therefore mean nothing happened or that the credential can’t see that kind of row; a type it can’t see is an empty page, not an error. Reading marks nothing read. A page can hold fewer rows than limit while hasMore is true, so follow the cursor until hasMore is false. The full per-type table is in Authentication.Changed: GET /v1/domains/{domainId}/health takes include. include=scoreHistory adds scoreHistory, up to 50 saved score snapshots, newest first, each with its grade, confidence, the event that saved it, and every pillar’s score and weight. include=scoreRuns adds scoreRuns, the last 5 automated domain score runs, each with its status, the score it ended on, the credits it cost, and every variant’s placement test.Changed: contact reads take openProfile. GET /v1/contacts/{email}?include=openProfile and POST /v1/contacts/search with include: ["openProfile"] attach the open-time profile that Intelligent send’s per-recipient timing reads. It holds open counts per UTC half hour and, once there is enough history, the best send time. It is null before the first open. It needs the emails scope as well as contacts (403 INSUFFICIENT_PERMISSIONS without it). A search with it returns at most 10 contacts per page, and it can’t be combined with count: true. Machine opens can’t be told apart in the profile, so it is not bot detection. See Explore Per-Contact Engagement.MCP: list_insights, get_insight, list_email_comments, list_chats, and list_notifications are new, get_domain_health takes include: ["scoreHistory", "scoreRuns"], and search_contacts takes include: ["openProfile"]. list_insights reads 10 findings per page and cuts long text and expansions to fit one tool result; truncated names what it cut, and the HTTP read always answers whole.
  • SDK 11.6.0: brew.insights.list() and brew.insights.get(insightId), brew.emails.comments.list({ emailId }), brew.chats.list(), and brew.notifications.list(). brew.chats.listAll() and brew.notifications.listAll() page through everything (the notifications pager keeps going through short pages), and brew.emails.comments.listAllMessages({ emailId, commentId }) walks one thread back to its first message. include on brew.domains.health(), brew.contacts.get(), and brew.contacts.search().
  • CLI 0.13.0: brew-cli insights list and insights get, brew-cli emails comments list, brew-cli chats list, and brew-cli notifications list. --include on domains health, contacts get, and contacts search.
New
Delete a brand image, and upload a local image file to the brand library; add-image returns assetId; SDK 11.5.0 and CLI 0.12.0

Delete a Brand Image, and Upload a Local File

New: DELETE /v1/brand/images/{assetId} removes one image from the brand library, as Delete image on the Assets page does. Pass the assetId that GET /v1/brand/images returns. It answers { assetId, deleted }, and an assetId that isn’t in the library answers deleted: false and changes nothing, so a repeat is safe. The image leaves the library and image search, but its file stays hosted at its URL, so emails already using it keep rendering. Logos are refused with 400 INVALID_REQUEST; manage them on the Assets page. Free, and on the brand.write rate limit. MCP: delete_brand_image.New: upload an image file from your machine. A JSON body can’t carry a file that size, so it takes three calls, all free:
  1. POST /v1/content/image-uploads with { fileName, contentType, size } answers 201 with { uploadId, uploadUrl, expiresAt, maxBytes }. PNG, JPEG, GIF, WebP, AVIF, TIFF, or SVG, up to 20 MB (SVG 2 MB). A brand can hold 20 uploads open at once, and the next one is 429 RATE_LIMITED.
  2. POST the raw bytes to uploadUrl within 15 minutes, with no Authorization header: curl -X POST --data-binary @logo.png "<uploadUrl>". The URL carries its own credential, so keep it private. Sending again never replaces the first file.
  3. POST /v1/content/add-image with { uploadId } within 15 minutes of the bytes landing. The bytes decide the format, and repeating the call returns the same answer for 24 hours.
New error codes: UPLOAD_NOT_FOUND (404, unknown or expired), UPLOAD_NOT_RECEIVED (409, the bytes were never sent), and UPLOAD_IN_PROGRESS (409, another call is converting it; retry). See Upload a Local Image.Changed: POST /v1/content/add-image returns assetId for imageUrl and uploadId, so you can delete what you just added. It still takes imageUrl or imageUrls, and it stays free.MCP: create_image_upload opens the upload, and add_image takes uploadId. Only a client with a shell or an HTTP tool on the machine holding the file (Claude Code, Cursor) can send the bytes; a chat-only client asks for a public link and uses add_image with imageUrl.
  • SDK 11.5.0: brew.brand.deleteImage(assetId), brew.content.createImageUpload({ fileName, contentType, size }), and brew.content.uploadImage({ file, fileName, contentType? }), which runs all three steps (it checks the size before sending and doesn’t retry opening the upload). brew.content.addImage() takes { uploadId }, and its answer carries assetId.
  • CLI 0.12.0: brew-cli content upload-image <file>, brew-cli content create-image-upload, brew-cli content add-image --upload-id, and brew-cli brand delete-image <assetId>. Also fixed: templates list with count or groupBy no longer crashes.
See Assets for the app and agent paths.
New
Flows count themselves and one flow has its own MCP tool; SDK 11.4.0 and CLI 0.11.0

Flows Count Themselves, and One Flow Has Its Own Tool

GET /v1/flows returns total and isTotalExact. total counts every flow the query matches across all pages: the filters narrow it, semantic only orders it. One limit=1 call answers how many flows there are. isTotalExact is false when the read was cut at 500 flows (the newest, or the 500 nearest a semantic query), and total is then a floor.A semantic search that cannot run is now 503 SERVICE_UNAVAILABLE with Retry-After: 300, instead of an empty page that read as “no flows match”. Retry without semantic: brand, category, type and sort still narrow and order the list.MCP: get_flow reads one flow. list_flows is text only and takes no slug or include: it names every flow on the page and leads with the total. get_flow takes slug and include: ["html"] and shows the sequence’s emails. A list_flows call that passes slug is refused; call get_flow instead.
  • SDK 11.4.0: FlowsListResponse carries total and isTotalExact. brew.emailGroups.create and .update take emailIds (move up to 50 designs into a folder in one call) and return moved and notMoved; update needs name, emailIds, or both. The creator fields (createdBy, createdByUserId, publishedBy, publishedByUserId) are typed on emails, email groups and automations.
  • CLI 0.11.0: flows list leads with how many flows match (167 flows in total; 25 on this page), and --json passes total and isTotalExact through. emails groups create and update take --email-ids, and update no longer requires --name.
Fixed
SDK timeouts and cancellation cover the response body; typed transport errors carry the idempotency key

Timeouts and Cancellation Cover the Response Body

Fixed in SDK 11.3.0. timeoutMs and a caller’s AbortSignal stopped at the response headers: the SDK cleared its timer and detached the signal as soon as the headers arrived, so a body that stalled afterwards had no deadline and could not be cancelled, and a connection that dropped mid-body skipped every retry. Both now cover the whole attempt, body included. Reproduced in SDK 10.0.0, 11.0.0 and 11.2.0; the API is unchanged. A response that takes longer than timeoutMs to stream now fails where it used to succeed: raise timeoutMs if you relied on that.
  • SDK 11.3.0: a request with no usable answer throws BrewTransportError, either BrewTimeoutError (name: 'TimeoutError') or BrewConnectionError, instead of a bare AbortError or TypeError, and a 2xx that is not JSON throws BrewParseError. Every error, BrewApiError included, carries the idempotencyKey its request used, so a write whose outcome is unknown can be replayed instead of repeated. retryOnTimeout: false makes a timeout final, and createBrewClient({ signal }) cancels every request on the client. A cancel is never retried and also stops a retry backoff. content.gif, content.generateImage and emails.import get their own per-call timeouts (300, 180 and 300 s). See Timeouts and cancellation.
  • CLI 0.10.0: Ctrl-C and SIGTERM stop the request in flight (exit 130 / 143), --timeout <duration> bounds a whole command, body included, and --max-retries sets the retry count. A write whose outcome is unknown prints its idempotencyKey and a retryCommand that replays it. See Replaying an unknown outcome.
New
Grouped email-event counts on GET /v1/analytics/events; per-domain unsubscribe lists

Event Counts and Domain Unsubscribe Lists

New: count events instead of listing them. GET /v1/analytics/events takes groupBy (one or two comma-separated fields: eventType, emailId, automationId, sendId, source, link, recipientDomain, unsubscribeReason) and bucket (day, week or month, UTC, weeks start Monday), alone or together. With either one it counts the email events the same filters list and answers { count, groups: [{ key, bucket?, count }], otherCount, range, truncated, coveredFrom? }, largest 200 groups first. Clicks per link is groupBy=link&eventType=clicked, and an unsubscribe counts once per reason it gave. It counts events, not unique recipients; GET /v1/analytics/overview opened and clicked count unique human recipients. One count reads the newest 20,000 events in the window, and a busier window answers truncated: true with coveredFrom. cursor and automationRunId are refused with 400, and limit is ignored. MCP get_email_analytics takes the same groupBy and bucket on report.kind: "events". See Explore per-contact engagement.New: every marketing domain has its own unsubscribe list. With the domains scope, the list lives under /v1/domains/{domainId}/unsubscribes: GET pages it (?scope=any|domain|all, ?q= to search), POST adds up to 1,000 addresses, DELETE …/{email} takes one off, POST …/import reads another ESP’s CSV (10,000 rows per call), and GET …/export returns it as CSV. An address on a domain’s list stops only that domain’s mail. subscribed: false on the contact stays the brand-wide opt-out, and removing an address from a domain’s list never clears it. An added address with no contact is created already unsubscribed brand-wide. A transactional domain has no list (422 DOMAIN_PURPOSE_NOT_ALLOWED). MCP: add_domain_unsubscribes, import_domain_unsubscribes, remove_domain_unsubscribe.
  • SDK 11.2.0: brew.analytics.eventCounts({ groupBy, bucket, ... }) and brew.domains.unsubscribes.list|add|remove|import|export, plus dateOrder and consent on brew.contacts.importCsv, consent on upsert, upsertMany and patch, and dryRun on brew.automations.create (typed as the dry-run report).
  • CLI 0.9.0: brew-cli analytics event-counts --group-by --bucket, brew-cli domains unsubscribes list|add|remove|import|export, and contacts import-csv --date-order --validate --consent-source.
Breaking
Brand images list the whole asset library by kind and sort; type and aspectRatio are retired; generated images are saved to it

Brand Images Cover the Whole Asset Library

Changed: everything the Assets page shows. GET /v1/brand/images and MCP search_brand_images now list the brand’s whole asset library: logos, brand images (from the site or uploaded, including the social preview and the site screenshot), and images made with Brew.
  • kind narrows to logo, brand, or generated. Omit it for every kind.
  • sort orders a browse: newest (the default) or oldest.
  • q searches brand and generated images by what they show, in relevance order, and ignores sort. It costs 1 credit for the first page, and cursor pages after it are free. Logos are not searchable, so q with kind=logo is a 400 INVALID_REQUEST, refused before any charge.
Breaking: type and aspectRatio are retired. Sending either is a 400 INVALID_REQUEST. The message for type points you to kind, and the one for aspectRatio says it is no longer a filter. Every row still carries width and height, so filter by shape on your side.Breaking: a new row shape. Each row carries assetId, kind, and url, plus what is known: description, width, height, category, pageUrl, addedAt (ISO 8601), and on a logo, logo ({ type, theme, background, format }). assetId is 8 hex characters, the id the app opens at /assets?image=<assetId>. description is the one the app shows; a search result falls back to the machine-written caption only when an image has none. Rows no longer carry aspectRatio or prompt.Changed: browsing pages by key. A browse cursor names the last rows it returned, so uploads and deletes during a walk don’t shift its pages (see Pagination). It only continues the same sort and kind. A search pages with a signed cursor that only continues the same q and kind.Changed: generated images are saved. POST /v1/content/generate-image and MCP generate_image now save each image to the brand’s generated images, as images made in the app’s chat already were. List them with GET /v1/brand/images?kind=generated.
  • SDK 11.2.0: brew.brand.getImages() takes { q, kind, sort, limit, cursor }. type and aspectRatio are gone.
  • CLI 0.9.0: brew-cli brand get-images takes --kind and --sort in place of --type and --aspect-ratio.
The app’s Assets page shows the same list. It filters by All, Brand images, Generated, and Logos, sorts newest or oldest first, and no longer has a Shape filter. See Assets.
Breaking
Publish refuses a merge tag the trigger doesn't declare; a fire names every automation it could not start

Undeclared Merge Tags and Fires That Start Nothing

Breaking: publish refuses every unresolvable reference. An automation whose email body, subject, preview text, fromName or replyTo uses a trigger field the trigger doesn’t declare, such as {{ trigger.code }} on a trigger that declares only email, now fails PATCH /v1/automations/{automationId} with published: true (and MCP save_automation) as 422 PUBLISH_VALIDATION_FAILED, with or without a | fallback. It used to publish, and then every live fire was refused without saying so. The same applies to a path under a key the trigger doesn’t declare ({{ trigger.order.total }} with no order), a contact property in fromName or replyTo (they resolve once per fire, from trigger fields only), and a dotted triple-brace token such as {{{ trigger.code }}}, which never renders. Every blockingIssues[] entry of a dry run now blocks publish; fatal only says what the reference would do at send time. Fix it by declaring the field on the trigger or changing the tag.New: notStarted[] on a fire. POST /v1/automations/triggers/{triggerEventId}/fire and MCP fire_trigger_event add notStarted: [{ automationId, reason }] for each matched automation whose run failed to start. A fire used to answer 202 triggered with empty automationRunIds and no explanation. A refusal in reason, such as a merge tag the trigger does not declare, repeats on every fire until fixed, and a receipt whose every failed start was a refusal moves to dead_letter at once instead of being retried. An unexpected error is retried automatically.Trigger edits that would break a published automation are refused. Removing or retyping a field a published automation uses was already refused; declaring the shape of an open object or list so one of its tags no longer resolves now is too. PATCH /v1/automations/triggers/{triggerEventId} answers these with 409 CONTRACT_LOCKED_BY_PUBLISHED_AUTOMATIONS, like the contract endpoint, instead of 500.
Fixed
Day-first dates import in the right month; new dateOrder on CSV import and a DATE_ORDER_ASSUMED warning

Day-First Dates

Fixed: a day-first date column imports in the right month. Brew now reads every date in a CSV column, or in one field across a batch (POST /v1/contacts, POST /v1/contacts/import-csv, MCP update_contacts_csv), in one day/month order. A day over 12 anywhere in the column settles it, so a UK file’s 03/04/2026 is 3 April, like its 13/04/2026. Each date used to be read on its own, and 03/04/2026 was stored as 4 March.New: dateOrder on CSV import. day_first or month_first decides a column whose dates all read either way. Without it, such a column reads month first and the response carries a DATE_ORDER_ASSUMED warning that names the field.Changed: more formats, and nothing guessed. Dotted dates (03.04.2026) read day first, and year-first (2026/04/03) and compact (20260403) dates are accepted. A value in none of the listed formats, such as a bare 2026, is refused with FIELD_TYPE_MISMATCH instead of being guessed. A single PATCH /v1/contacts/{email} value still reads an ambiguous date month first. See date formats.
Changed
A contact search for one whole email address returns only that contact; other text matches words on every brand

Contact Search by Address

Changed: a whole address is an exact lookup. A contact search that is one whole email address (POST /v1/contacts/search, GET /v1/contacts?search=, MCP search_contacts) now returns only the contact with that address, or nothing when there is none. It matches like filters: [{ field: "email", operator: "equals", value }], so letter case and surrounding spaces don’t matter. It used to match any word of the address (alice@gmail.com matched every contact with gmail or com), newest first, so the contact searched for was often not the first row and an address with no contact still returned other people.Changed: other text matches words on every brand. Any other search text matches the contacts whose email, first or last name contains any of its words, in sort order. A brand whose contacts all came through the API used to match it as one exact substring instead; the first search on such a brand may still answer that way while its index builds. It can return other contacts, so update or delete a contact you found by its address.In GET /v1/contacts?search=, encode an address’s + as %2B: an unencoded + reads as a space, which makes the address a word search.
Breaking
Re-subscribing an opt-out and immediate sends that reach nobody are refused; verificationStatus removed; valid means a deliverability check ran

Subscriptions, Verdicts, and Who a Send Reaches

Breaking: re-subscribing is refused. subscribed: true only applies to a new contact. A single write that asks to re-subscribe a contact who opted out (PATCH /v1/contacts/{email}, a single POST /v1/contacts, MCP update_contact) answers 422 RESUBSCRIBE_NOT_ALLOWED and writes nothing. A batch or CSV row keeps its other fields and adds a RESUBSCRIBE_SKIPPED warning naming the contact. A contact who asks to receive marketing email again is re-subscribed by a team member from their contact page in the app.Changed: subscribed: false reaches existing contacts. An upsert, batch or CSV import that sets subscribed: false (or an email platform’s status word such as unsubscribed or cleaned) now unsubscribes a contact that already exists. It used to apply to new contacts only.Breaking: an immediate send that would reach nobody is refused. POST /v1/sends and MCP send_email answer 422 NO_ELIGIBLE_RECIPIENTS (details.eligibility carries the counts) when every contact the send targets is unsubscribed, suppressed or undeliverable, and no send is created. Such a send used to be created and then fail. A scheduled send is still accepted, since its audience can change before it goes out. A 202 whose send will skip contacts carries a RECIPIENTS_EXCLUDED warning with the counts by reason.Changed: valid means a deliverability check ran. validationStatus: "valid" now only comes from a deliverability check (validate: true on ingest, or POST /v1/contacts/validate), which also sets lastValidatedAt. Without one, the free format check stores risky or invalid and otherwise leaves the field unset. A valid with no lastValidatedAt came from the format check. Filters that negate the verdict, such as “is not invalid”, include contacts that carry none.Breaking: verificationStatus removed. Contact rows no longer carry the deprecated verificationStatus mirror; read validationStatus. Filters that name verificationStatus still resolve.Changed: one email rule. Every address a write or send accepts follows the rule imports use (dot-atom, up to 254 characters), published in the spec as a pattern instead of format: email, so an address that could be imported can also be looked up, deleted and sent to. Lookups by email accept any address and report an unknown one as not found.
New
Pause, resume, and cancel a manual-audience run

Manual-Audience Run Controls

A manual-audience launch (POST /v1/automations/{automationId}/run) has three controls, each taking the audienceRunId in the path and no body. They return 200 with the run’s new status, and 404 AUDIENCE_RUN_NOT_FOUND for an unknown or cross-brand id.
  • POST /v1/automations/audience-runs/{audienceRunId}/pause holds the run at its next step boundary. Delivery in flight for the current step completes. 409 RUN_NOT_PAUSABLE unless the run is running.
  • POST /v1/automations/audience-runs/{audienceRunId}/resume continues a paused run, or restarts a failed one from the first send step that never delivered, skipping every step the failed run finished. resumedFrom says which case ran. A run held at the plan limit resumes on its own once the monthly send allowance has room. Refusals: 409 RUN_NOT_PAUSED, 409 RUN_NOT_RESUMABLE, 409 RUN_IN_PROGRESS, 402 SEND_QUOTA_EXCEEDED.
  • POST /v1/automations/audience-runs/{audienceRunId}/cancel stops the run for good. Sent emails are not recalled, and a canceled run cannot be resumed. 409 RUN_NOT_CANCELLABLE when it already finished.
The SDK exposes them as brew.automations.audienceRuns.control().
Fixed
The credit balance fell twice as fast past the plan cap; GET /v1/usage now readable by every key

Credit Balance Past the Plan Cap, and Usage for Every Key

Fixed. Once an organization had used its plan credits and was spending bonus credits, every balance readout subtracted the overflow twice: X-Credits-Remaining on a 1-credit call moved by 2, the Billing & Usage page understated the balance by the overflow, and organizations still holding bonus credits could be refused with 402 INSUFFICIENT_CREDITS. Charges themselves were always correct: one ledger entry per call at the published cost, and bonus credits debited exactly once. Nothing is owed and no balance changed; the readouts and the gate now report the real balance, which is the plan credits left this period plus the bonus balance.Changed. GET /v1/usage and the MCP get_usage tool are readable by every API key and MCP connection in the organization, brand-scoped keys and brand members included. Previously they answered 403 INSUFFICIENT_ROLE for anything but an organization-scoped key, which left a brand key no way to measure a usage-metered call. Read the balance before and after the call as the credits page describes.
Fixed
Automation runs filter by recipientEmail; trigger-fire refusals keep their field errors in the SDK

Automation Runs Filter By Recipient

GET /v1/automations/runs?recipientEmail= (and the MCP list_automation_runs tool) now applies the filter. It was accepted and documented but ignored: the unfiltered page came back with no warning. The match is case-insensitive and combines with automationId, status, mode, and the from/to window.

Trigger-Fire Refusals Keep Their Details

POST /v1/automations/triggers/{triggerEventId}/fire answers a payload mismatch with 400 INVALID_PAYLOAD (status: "payload_mismatch") and details.errors[] naming every offending field, plus details.payloadSchema to repair against. The reference now documents that shape; its example previously showed a PAYLOAD_MISMATCH code the API never sent. The same body fails the same way on retry, so read details instead of retrying.
  • SDK 9.3.0: BrewApiError maps the legacy fire envelope (the real code, a type derived from the HTTP status, fix-the-request advice for a 4xx) and gains details and body. Before 9.3.0 a fire refusal surfaced as unknown_error / internal_error with retry advice.
  • CLI, from the next release: automations triggers fire and api POST …/fire print the field errors, and --json carries details inside the error envelope.
Deprecated
API key management is dashboard only on every programmatic surface

API Key Management Is Dashboard Only

The three /v1/api-keys operations now require a signed-in Clerk session whose active organization role is exactly org:admin. API key and OAuth actors receive 403, so a compromised key can never mint or revoke another. The spec marks all three sessionAuth:
  • GET /v1/api-keys
  • POST /v1/api-keys
  • DELETE /v1/api-keys/{keyId}
Nothing changes in the dashboard. Create, rotate, and revoke keys at Settings, then API, the way the key lifecycle has always described.What this means on each surface:
  • MCP never exposed key management and still does not. An MCP credential cannot prove that the human behind it holds the organization’s org:admin role.
  • SDK: brew.apiKeys.list(), create(), and revoke() are marked @deprecated. They compile and call, and the platform answers 403. They are removed in the next major.
  • CLI: brew-cli api-keys list|create|delete are deprecated. Rather than spend a round trip on a guaranteed rejection, they now fail immediately with exit code 2 and a message pointing at the dashboard. The command names, flags, and routes stay documented until the next major removes them.
No migration is needed for code that reads or sends email. If you provision keys from a script, move that step to the dashboard, or tell us about your SOC2 or SAST pipeline and we will scope a real answer.
New
Public email flows on the API, MCP, and CLI

Email Flows

GET /v1/flows exposes the public flows gallery: one brand’s real onboarding or newsletter sequence, with the day each email landed. It is organization-wide, like GET /v1/templates, shares the templates.read budget, and returns the { data, pagination } envelope.
  • List cards with ?brand=, ?category=, ?type=signup|newsletter, ?semantic= (relevance-ranked search), and ?sort=newest|emails|span|remixes. Each card carries brand, title, type, category, emailCount, spanDays, remixCount, and previewImages.
  • Fetch one with GET /v1/flows/{slug} (the brand domain) → the bare flow with anchor (what day 0 means) and steps[]: order, dayOffset, delayDays (the wait since the previous email), subject, previewText, category, previewImage, and emailId. Add ?include=html for each step’s rendered HTML. An unknown slug is a 404 FLOW_NOT_FOUND.
  • A step’s emailId is a template reference: pass it as referenceEmailId on POST /v1/emails to rebuild that email for your brand, or look it up on GET /v1/templates.
Over MCP these are the list_flows and get_flow tools and the brew://flows resource; in the CLI, brew-cli flows list (--all) and brew-cli flows get <slug> (--include html). In the TypeScript SDK, brew.flows.list() and brew.flows.get(slug, { include }) (SDK 10; the 9.2 list({ slug }) mode is gone with the v1 cleanup).
Breaking
The transactional email object and its routes are removed

Transactional Email Is an Automation

Breaking. The standalone transactional email object is gone, along with every /v1/transactional* route. A transactional email is now an automation whose Send Email step uses a domain with sendingPurpose: 'transactional'. The domain purpose is what removes the unsubscribe requirement and delivers to unsubscribed contacts. The delivery class now comes from the domain, not from a dedicated object.Removed:
  • GET /v1/transactional/{transactionId}, including ?include=skill
  • The transactionId field on POST /v1/sends
  • The TRANSACTIONAL_EMAIL_NOT_FOUND error code
  • brew.transactional.get() in the TypeScript SDK, the get_transactional_email MCP tool, and brew-cli types --transaction

Migrate a fire

Replace the send call with a trigger fire. The recipient moves into the payload as email, and the design reads the rest as {{ trigger.* }}.
In the SDK, brew.emails.send({ transactionId, to, payload }) becomes brew.automations.triggers.fire({ triggerEventId, payload }).Read the contract with GET /v1/automations/triggers?triggerEventId= (MCP list_triggers). Pre-flight a fire with GET on the fire URL itself (MCP check_trigger_ready). That returns the payload schema and the published automations a fire would match, without sending anything.

What else changed

An unknown id now returns 404 TRIGGER_EVENT_NOT_FOUND. A payload that fails its schema returns 400 INVALID_PAYLOAD (status: "payload_mismatch") in the fire envelope, with details.errors[] naming the offending fields. A trigger with nothing published returns 422 NO_PUBLISHED_AUTOMATION.Payload contracts are declared on the trigger as payloadSchema, not derived from a pinned design. A field is optional when required: false. brew-cli types now emits a type per trigger and needs only the automations scope.Set a domain’s purpose with POST /v1/domains { sendingPurpose }, and change it later with PATCH /v1/domains/{domainId}. Filter with GET /v1/domains?sendingPurpose=.See Transactional Email for the model and Build an Automation for the walkthrough.
NewBreaking
A raw-content email audit with a versioned complete or partial response

Unified Email Audit

POST /v1/emails/audit replaces the saved-design accessibility endpoint. It accepts { emailHtml, subject?, previewText?, sendingPurpose? } and checks unsubscribe content, links, images, loaded size, accessibility, compatibility, markup, subject copy, and preview copy in parallel.The response has a versioned schema and a completion discriminator:
  • complete returns readiness, a 0 to 100 score, and X-Credit-Cost: 5;
  • partial preserves finished checks, returns completion.score: null and X-Credit-Cost: 0, and never establishes readiness.
The old email-id route is removed. Use brew.emails.auditEmail(...) in the TypeScript SDK.See Audit an Email for the product workflow and examples for every interface.
New
POST /v1/audiences/{audienceId}/duplicate returns

Duplicate an Audience

POST /v1/audiences/{audienceId}/duplicate is back after its removal on Jun 24. It creates a deterministic copy of the saved audience’s live filters under a server-generated “(copy)” name. Contacts are not copied: both audiences resolve against the same contact records.
New
Set an email's subject line from the API, MCP, and CLI

Subject Lines on Every Email Write

Every design carries a default inbox subject (subjectLine), and until now only the app could set it, so designs created through the API, MCP, or CLI landed without one. All four write surfaces now accept an optional subjectLine of 1 to 250 characters:
  • POST /v1/emails (MCP create_email_design). The email agent also sees the subject, so the preview text and opening copy complement it instead of repeating it.
  • POST /v1/emails/import (MCP import_email_design)
  • POST /v1/emails/figma (MCP import_figma_design)
  • PATCH /v1/emails/{emailId} (MCP edit_email_with_ai)
Each response echoes the persisted subjectLine, and GET /v1/emails?emailId= already returns it on the detail row.prompt is now optional on PATCH /v1/emails/{emailId}. Send subjectLine on its own and Brew sets the subject in place: no AI run, no new version, no credits. Send both and the subject lands on the new version the edit produces. At least one of the two is required, and emailVersionId still requires prompt, because pinning a source version means nothing for a subject change.A subject line is the design’s default, not the send. POST /v1/sends still takes its own subject per delivery.In the CLI this is --subject-line on emails generate, emails import, emails import-figma, and emails edit.
New
Run and copy any API capability from the dashboard

The API Catalog

The dashboard now has an API tab at brew.new/api that runs eleven v1 capabilities against your own brand and hands you the exact call afterwards. No endpoints changed, and nothing here is new API surface.
  • Covers Generate Email, Edit Email, Figma to Email, HTML to PNG, Image to GIF, Optimize Image, Resize Image, Validate Contacts, Email Audit, Email Inbox Preview, and Inbox Placement, with each one’s credit cost on the row.
  • Every parameter you set rewrites a live request snippet, switchable between cURL, TypeScript (SDK), TypeScript, and Python. Copied snippets always carry the brew_your_api_key placeholder rather than the key the in-app run used.
  • Each capability also carries a copyable implementation prompt for a coding agent: endpoint, docs link, cost, the BREW_API_KEY auth pattern, the SDK method, the equivalent MCP tool, every request field, and an example body.
Runs are real API calls, so they charge credits and write to your brand exactly as a call from your backend would. Full walkthrough in API Catalog.
New
Figma imports on the API, and full SDK parity

Figma to Email on the API, MCP, and SDK

Converting a Figma frame into an editable email was previously only possible in chat. It is now a first-class operation on every surface:
  • POST /v1/emails/figma takes { figmaUrl, title?, format?: 'jsx' | 'html' } and returns 201 { emailId, emailVersionId, title, format, content, warningCount, exportedNodeCount, previewImage? }. The figmaUrl must include a node-id, which is the link to one specific frame rather than the whole file.
  • The conversion is deterministic, with no model in the loop, so the same frame always converts the same way and the call is free.
  • Every surface uses the API-key brand’s connected Figma integration. Credentials are never accepted in the request or retained in API/MCP history. Without a usable connection you get 422 FIGMA_NOT_CONNECTED.
Also available as the import_figma_design MCP tool and as brew.emails.importFigma(...) in the SDK.

Every v1 operation now has an SDK method

The TypeScript SDK had drifted behind the API. These methods are new:
  • brew.emails.importFigma(), brew.emails.clone(), brew.emails.export()
  • brew.emails.createInboxPlacementTest() and brew.emails.getInboxPlacementResults(), the seed-list test of whether a design lands in the inbox or in spam
  • brew.sends.pause() and brew.sends.resume(), the reversible pair for an in-flight gradual send
  • brew.analytics.overview() for the exact totals, rates, and timeseries shown in Brew
  • brew.automations.run() plus brew.automations.audienceRuns.list() and .control() for manual-audience launch, scheduling, pause, resume, and cancel
  • brew.domains.health() for the aggregate deliverability score and signals
New
Clone a design and export it to a connected ESP as routes of their own

Clone and Export Routes

The SDK methods announced above have their routes:
  • POST /v1/emails/{emailId}/clone creates a new design by copying the stored snapshot exactly, with no model in the loop and no re-hosting. Omit emailVersionId to clone the latest row, or pass a version id from GET /v1/emails/{emailId}?include=versions. Optional title (else Copy of …) and groupId or groupName, not both; omit to inherit the source group.
  • POST /v1/emails/{emailId}/export sends a finished design to a connected ESP as a reusable template. It is not a Brew send: nothing is delivered, and the provider must already be connected for the brand in the app. Pass dryRun: true to validate the design, brand ownership and connection without creating a template. Free, no credits.
NewBreaking
Validate contacts on ingestion & write-back; validationStatus rename

Public API v1: Validate Contacts as You Add Them

Contact deliverability validation now persists and reaches the ingestion endpoints:
  • POST /v1/contacts/validate now writes the verdict back onto matching contacts (it was read-only before), and each result adds risk, isDisposable, and isRole signals alongside the existing reason and didYouMean.
  • POST /v1/contacts and POST /v1/contacts/import-csv accept an optional validate: true, each address is deliverability-checked as it’s ingested and the verdict is saved. Metered 2 credits per address, charged only on success. Up to 100 addresses validate inline (the response carries a validation count summary); larger submissions upsert first and validate as a background job, returning a validationJobId.
  • The contact’s verdict field is renamed verificationStatus → validationStatus. verificationStatus is dual-emitted with the same value for back-compat, so existing integrations keep working.
  • Also available via the create_contact, update_contacts_csv, and validate_contacts MCP tools.
New
Email checks and contact deliverability validation

Public API v1: Check an Email and Your List Before You Send

Two pre-send quality checks shipped on the Public API, the MCP tools, and the in-app agent:
  • The first email audit checked WCAG 2.1 accessibility for a saved design. The August unified audit replaced it with production-readiness checks and a versioned complete or partial response. See the August entry above.
  • POST /v1/contacts/validate now runs a real deliverability check on up to 100 addresses at once, each comes back valid, risky (role account, disposable, catch-all), or invalid, with a machine-readable reason and a didYouMean typo correction. Metered 2 credits per address, charged only on success.
  • Contact validation remains available as the validate_contacts MCP tool.
New
Preview a design across real inboxes & devices

Public API v1: See How an Email Renders in Real Inboxes

New POST /v1/emails/{emailId}/client-previews renders a design’s latest version across real email clients & devices: Gmail, Outlook, Apple Mail, iOS (with dark-mode variants), plus Yahoo, and returns a screenshot per client, rehosted on the Brew CDN.
  • Pass clients (ids from the supported catalogue) to target specific inboxes/devices, e.g. outlook2021_win11_dm_dt for Outlook 2021 on Windows in dark mode, or send {} for a popular default spread.
  • Fixed cost of 10 credits, charged only when at least one client renders (X-Credit-Cost: 10). A batch where zero clients finish in time returns a retryable 503 and is not billed; unknown client ids are rejected with a 422 before any paid work.
  • Slow clients that outlive the bounded render window come back in pending. Call again to retry just those.
  • Also available as the preview_email_across_clients MCP tool and as brew.emails.previewClients(...) in the SDK.
New
POST /v1/sends/{sendId}/cancel cancels a scheduled or queued send

Public API v1: Cancel a Send

New endpoint to pull back a send before it goes out.
  • POST /v1/sends/{sendId}/cancel (“Cancel a send”). Cancels a scheduled or queued send → 200 { sendId, status: 'canceled' }. Idempotent, an already-canceled send returns 200. Once the send is sending, sent, or failed it is 409 SEND_NOT_CANCELLABLE; an unknown / cross-brand id is 404 SEND_NOT_FOUND. sends scope. The SDK method is brew.sends.cancel(sendId).
Breaking
Renames, /v1/account → /v1/usage, host-image → add-image

Public API v1: Two Operation Renames

Two endpoints (and their SDK methods) were renamed for clarity. The request and response shapes are unchanged.
  • GET /v1/account → GET /v1/usage (“Get usage”). The billing/quota surface, { plan, credits, emailSends, period }: keeps the same shape and the emails scope. The SDK method moves from brew.account.get() to brew.usage.get().
  • POST /v1/content/host-image → POST /v1/content/add-image (“Add image”). Still optimizes the source image and saves it to the brand image library (fixed credit cost). The SDK method moves from brew.content.hostImage() to brew.content.addImage().
Breaking
Read-collapse, flat reads, polymorphic send, email import

Public API v1: Flat Reads + Unified Send

The v1 surface collapsed from 71 to 55 endpoints around one rule: one flat read per resource, identity in the query, ?include= opt-ins for the heavy detail. Plus a new way to bring existing designs into Brew.
  • Reads are flat. The per-resource get-one paths are gone. Pass the id key to the list endpoint instead: emails GET /v1/emails?emailId= (?include=html,versions), domains ?domainId=, audiences ?audienceId= (?include=count), automations ?automationId= (?include=graph,versions), automation runs GET /v1/automations/runs?automationRunId= (?include=logs), triggers ?triggerEventId=, trigger instances ?triggerInstanceId=, and sends GET /v1/analytics/sends?sendId= (?include=events, also ?emailId=). The single-send detail row carries previewImage, so POST /v1/emails/{emailId}/preview, GET /v1/emails/{emailId}/versions, and GET /v1/emails/{emailId}/sends were removed (on-demand rendering is POST /v1/content/html-to-png).
  • One polymorphic send. POST /v1/sends/test folded into POST /v1/sends. Pass { test: true } for the synchronous one-off QA send (200 { recipient }); omit it for the campaign send (202 { sendId }).
  • One contact read. GET /v1/contacts and GET /v1/contacts/{email} were replaced by POST /v1/contacts/search ({ filters, audienceId?, search?, sort, count?, cursor }); a by-email lookup is a { field: 'email', operator: 'equals' } filter.
  • New, POST /v1/emails/import. Bring existing html, mjml, or jsx into an editable Brew design (external images are re-hosted on the CDN). Usage-metered.
  • Semantic brand-image search. GET /v1/brand/images?q= runs a credit-metered vector search (plus ?type / ?aspectRatio); the no-q browse stays free.
  • Also removed: POST /v1/audiences/{audienceId}/duplicate.
The TypeScript SDK keeps its factory names: every read is one list() (id/include/filters in the args), send/sendTest merged into send(input) with test?, the contact read is search(), and emails.import() is new. See the updated API Introduction, SDK Overview, and the @brew.new/sdk changelog.
Breaking
Restructure, decoupled sends, 3-domain surface, /v1/help

Public API v1: Decoupled-Send Restructure

A breaking restructure of the v1 surface around a single insight: emails are pure designs, and a send is the unit of delivery and analytics. A design now carries no type and no send state. It can be sent any number of times.
  • Sends, unified. Campaign sends and automation sends are one entity. A campaign records one send; an automation records one send per recipient. Every delivery event attaches to its sendId.
  • Three clear domains. automations owns /v1/automations/* plus /v1/automations/triggers(/{id}/fire) (renamed from /v1/triggers) and /v1/automations/runs(/{runId}) (moved from /v1/analytics/automations/runs). analytics owns all reporting, including /v1/analytics/sends(/{sendId}/events) (send reads, moved off GET /v1/sends) and /v1/analytics/trigger-instances (the fired-trigger log, moved off /v1/events). sends is the action only: POST /v1/sends and POST /v1/sends/test.
  • POST /v1/sends now takes either a saved audienceId or an inline to list (≤ 50) and returns a sendId you poll under /v1/analytics/sends.
  • GET /v1/help: a no-auth, structured-JSON catalog of the whole API (scopes, credits, rate limits, every endpoint) for MCP / agent discovery, alongside GET /v1/llms.txt.
  • No more dry_run. Credit-metered operations just charge on success (402 INSUFFICIENT_CREDITS when short); check your balance with GET /v1/account.
  • POST /v1/content/host-image is now credit-metered and saves the image into the brand image library.
  • Removed: /v1/me, /v1/usage (use GET /v1/account), /v1/integrations, the single-template GET /v1/templates/{emailId} (the list GET /v1/templates stays and now returns html + previewImage per row), and automation-run replay.
See the updated API Introduction and the @brew.new/sdk changelog. The entries below describe earlier iterations of the v1 surface, paths noted there have since moved as summarized above.
New
Version restore moves to POST /v1/emails/{emailId}/restore

Restore Is Its Own Route

POST /v1/emails/{emailId}/restore replaces the restoreVersion field on the edit body. The restore is non-destructive. It clones the numbered version into a new latest row and demotes the current head. The response is the same generated-email shape as an edit, with a fresh emailVersionId.
New
Hardening, 7 new endpoints, pagination, scopes

Public API v1: Hardening Pass

Seven new endpoints plus cross-cutting normalization across the whole API.
  • New observability + discovery endpoints: GET /v1/sends (campaign send list + stats), GET /v1/brand (the key’s brand + readiness), GET /v1/usage (API request volume + trend), GET /v1/analytics/events (unified event explorer, filter by recipientEmail for a contact’s full timeline), and GET /v1/integrations (triggerable integration-event catalog).
  • Test/preview sends: POST /v1/sends { mode: 'test' } sends a one-off preview to a single inbox, no verified domain or audience required, and it doesn’t consume the email’s live-send slot.
  • Automation run replay: POST /v1/automations/runs { automationRunId, mode: 'replay' } re-runs a prior run against the current saved draft.
  • Uniform cursor pagination: every list endpoint now accepts limit/cursor and returns a pagination envelope.
  • Lean lists + include=: GET /v1/templates and GET /v1/automations are lean by default. Pass ?include=html / ?include=graph to opt into the heavy fields.
  • Granular scopes: new least-privilege domains, sends, and audiences scopes; the coarse scopes still satisfy them, so existing keys are unaffected.
New TypeScript SDK methods: brew.brand.get(), brew.usage.get(), brew.integrations.list(), brew.analytics.sends.{list,listAll,get}() + brew.emails.sendTest(), and brew.analytics.{events,eventsAll}(). See the updated API reference, the new API Guides, and the @brew.new/sdk changelog.
NewBreaking
Lifecycle expansion

Public API v1: Full Lifecycle

The v1 API now covers the whole loop end-to-end for an org + brand API key.
  • Audiences are now full CRUD (POST/PATCH/DELETE + single fetch), and rows carry their filters, member count, and ISO timestamps.
  • Domains gained a full lifecycle: add → verify → set sender defaults → delete. GET /v1/domains now lists every domain (incl. pending rows + the DNS records to publish); ?sendableOnly=true returns just the send-ready set.
  • Analytics is now queryable: GET /v1/analytics/campaigns (lifetime per-campaign KPIs) and GET /v1/analytics/automations (windowed per-automation performance + totals).
  • Emails gained delete, version history (?include=versions), and non-destructive version restore.
Breaking: POST/PATCH /v1/triggers (since renamed to /v1/automations/triggers) now return the uniform { triggers: [row] } envelope (was { trigger }); contact timestamps are ISO-8601 strings. See the updated API reference + the @brew.new/sdk changelog.
New
OpenAPI 3.1 spec + TypeScript SDK

API Specification

Published OpenAPI 3.1 specification covering contacts, automations, triggers, automation runs, emails, sends, audiences, domains, fields, and templates. Official TypeScript SDK (@brew.new/sdk) is available; generate clients for other languages from the OpenAPI spec at https://brew.new/openapi/public-api-v1.yaml (see Generate Your Own SDK).