API Changelog

​

Subject Lines on Every Email Write

• 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)

​

The API Catalog

• Covers Generate Email, Edit Email, Figma to Email, HTML to PNG, Image to GIF, Optimize Image, Resize Image, Validate Contacts, Accessibility 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.

​

Public API v1: Validate Contacts as You Add Them

• 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, import_contacts_csv, and validate_contacts MCP tools.

​

Figma to Email on the API, MCP, and SDK

• 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.

​

Every v1 operation now has an SDK method

• 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

​

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

• POST /v1/emails/{emailId}/accessibility-audit runs a WCAG 2.1 audit of a design’s rendered HTML, colour contrast, image alt text, link text, heading structure, font size, language, and returns a score (0-100), a summary, and the specific issues with their WCAG criterion. Fixed 5 credits, charged only on success. (This endpoint is now a POST and credit-metered; it previously returned a lightweight local result.)
• 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.
• Both are value-aligned: if the check can’t complete, you get a retryable 503 and are not billed. Also available as the audit_email_accessibility and validate_contacts MCP tools.

​

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

• 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.

​

Public API v1: Cancel a Send

• 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).

​

Public API v1: Two Operation Renames

• 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().

​

Public API v1: Flat Reads + Unified Send

• 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.

​

Public API v1: Decoupled-Send Restructure

• 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.

​

Public API v1: Hardening Pass

• 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.

​

Public API v1: Full Lifecycle

• 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.

​

API Specification