MCP Tools

The Brew MCP server exposes customer tasks, not one tool per HTTP route. Some tools compose several Public API v1 operations (get_email_analytics answers the overview, send, and event reads), and a few have no HTTP route at all. The catalog below is generated from what an organization connection’s tools/list returns, grouped under the topics get_brew_capabilities uses. A brand connection sees the same tools except create_brand. Every tool is strictly typed and carries all four MCP annotations as booleans: readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, shown as the catalog’s Read-only, Destructive, Idempotent and Open world columns. A write that overwrites, unsubscribes, or sends is marked destructive. Call get_brew_capabilities with a tool for one tool’s full input schema, or with a topic for focused help. Each description is exactly what your agent reads, and it states the tool’s cost: every credit-metered tool names its price there, and running out returns INSUFFICIENT_CREDITS.

Tool Catalog

Email

Tool	What it does	Read-only	Destructive	Idempotent	Open world	HTTP equivalent
`audit_email`	Use this when checking an email before a production send. A complete audit costs 5 credits; a partial result is free and does not establish readiness. Pass exactly one of `emailId` (a saved design; pin `emailVersionId`), `emailJsx` or `emailHtml`; `sendingPurpose` is inferred when omitted.	no	no	no	yes	`POST /v1/emails/audit`
`cancel_email_send`	Cancel an existing scheduled, queued, or in-flight email send by sendId from get_email_analytics. Permanently stops remaining deliveries; delivered emails cannot be recalled. Repeating a cancellation is idempotent.	no	yes	yes	no	`POST /v1/sends/{sendId}/cancel`
`clone_email`	Copy a Brew design exactly without AI; it shows no preview, since the copy looks like its source. Omit groupId/groupName to inherit its folder. Use edit_email to change content or import_email for external source.	no	no	no	no	`POST /v1/emails/{emailId}/clone`
`create_email`	Create an on-brand email from the requested content and design brief, metered in credits; use clone_email for an exact copy or import_email for source content. The brand must be ready. Set groupId or groupName to choose its folder. A ready result already shows the design; only if generating, poll get_email. Repeating creation starts another billed design.	no	no	no	yes	`POST /v1/emails`
`create_inbox_placement_test`	Start a 10-credit seed test for inbox/spam placement; it sends a real email from the domain to the Brew seed inboxes. Requires a verified domain. Check get_domain_health first; poll get_inbox_placement_results. Visual client screenshots use test_email_rendering.	no	yes	no	yes	`POST /v1/emails/{emailId}/inbox-placement-tests`
`delete_email`	Permanently delete a design and all its versions. Delivered campaigns remain delivered. deleted:false explains already_deleted (with its deletedAt) or not_found; a retry changes nothing.	no	yes	yes	no	`DELETE /v1/emails/{emailId}`
`delete_email_group`	Delete a named email folder; its designs move to Ungrouped. Cannot delete Ungrouped. Use delete_email to delete a design itself.	no	yes	yes	no	`DELETE /v1/email-groups/{groupId}`
`edit_email`	Change an existing design with a natural-language prompt (required). Each edit creates a version, moves automation steps pinned to the previous latest onto it (as a draft), and is usage-metered in credits. A ready result already shows the edited design; only if generating, poll get_email with the returned emailId and runId. To rename a design, set its subject or language, or move it to a group, use update_email_metadata: free, with no new version.	no	yes	no	yes	`PATCH /v1/emails/{emailId}`
`export_email`	Export a design as a template to an ESP already connected in Brew. Use list_integrations to check the provider, or send_email to deliver through Brew.	no	yes	yes	yes	`POST /v1/emails/{emailId}/export`
`get_email`	Show an existing email design with its preview, creator and Open-in-Brew link, read a saved version with emailVersionId, or poll a generation with the runId it returned. Free. Request include html, versions or links only when needed; those reads show no preview. preview:false reads a design without showing it again. Use test_email_rendering only for paid inbox-client screenshots.	yes	no	yes	no	`GET /v1/emails/{emailId}`
`get_email_analytics`	Read report.kind overview for totals over time, sends for campaign sends and their lifetime stats (pass sendId for one send; include events for its recipients), or events for recipient engagement (groupBy/bucket count them per link, day, email or unsubscribe reason). Use list_automations or get_automation with analytics:{} for flow performance.	yes	no	yes	no	`GET /v1/analytics/overview`, `GET /v1/sends`, `GET /v1/sends/{sendId}`, `GET /v1/analytics/events`
`get_email_audit`	Read a saved email audit and its precise findings without running or charging for a new audit. Use audit_email to create a fresh audit.	yes	no	yes	no	`GET /v1/emails/audits/{auditId}`
`get_email_rendering`	Read a saved inbox-rendering job with previewId; waits up to 30 s while it runs. Returns per-client status and screenshot links without starting another paid render. Use test_email_rendering to start a new job.	yes	no	yes	no	`GET /v1/emails/client-previews/{previewId}`
`get_inbox_placement_results`	Read saved placement results with emailId and testId; background collection refreshes them independently. Re-read about every 30 seconds while queued or running. Omit testId to compare a design’s previous tests. This read does not poll the provider or modify results.	yes	no	yes	no	`GET /v1/emails/{emailId}/inbox-placement-tests`, `GET /v1/emails/{emailId}/inbox-placement-tests/{testId}`
`get_template`	Use this when viewing one public template selected with search_templates. Returns its preview and emailId, which create_email takes as referenceEmailId. Include html only to inspect its content; large HTML is a downloadable file. Use get_email for a design in your brand.	yes	no	yes	no	`GET /v1/templates/{templateId}`
`import_email`	Import existing HTML, MJML, React Email JSX, or a connected Figma frame as an editable email. Choose source.kind content or figma. For a new design from a prompt use create_email.	no	no	no	yes	`POST /v1/emails/import`, `POST /v1/emails/figma`
`list_email_comments`	List the open comment threads teammates left on one email design, newest activity first: commentId, whether it is on the whole email or one element, the 12 most recent participants and their count, message count and the latest preview. include [“messages”] adds each thread’s newest messages (author, body, mentions) and caps the page at 3 threads; a thread with older ones returns messagesCursor: pass it with that commentId for the next older messages, until null. An unknown emailId is EMAIL_NOT_FOUND; a commentId that is not an open thread on it (resolving deletes one) is COMMENT_NOT_FOUND. Read-only and free. Use get_email for the design itself.	yes	no	yes	no	`GET /v1/emails/{emailId}/comments`
`list_email_groups`	List email folders with their groupId values and creators, including Ungrouped. Use list_emails with groupId to read a folder’s designs. save_email_group creates or renames folders.	yes	no	yes	no	`GET /v1/email-groups`
`list_emails`	List this brand’s saved email designs by group or status. Returns public emailId, title, group, creator, and links; a page of up to 8 shows as a gallery (to show designs, pass limit 8 or preview:true). Pass preview:false to look up ids or act on many designs. Use get_email to view one design or retrieve its content. search_templates browses the public gallery.	yes	no	yes	no	`GET /v1/emails`
`list_insights`	List the brand’s Brew Insights as the Insights page ranks them, most severe first: each finding’s insightId, title, description, severity, confidence, category, state and first and last seen times, plus when the engine last ran. Open findings by default; state “all” adds closed ones. include adds the weekly pulse, latest intelligence report, its open suggestions and the agent memo; anything cut to fit is named in truncated. A cursor is refused once the findings change; list again without it. With an insightId from a row (not a report insight key), returns that finding with its frozen metrics, evidence and detector method. Read-only and free. get_email_analytics reports raw performance.	yes	no	yes	no	`GET /v1/insights`, `GET /v1/insights/{insightId}`
`pause_email_send`	Pause an existing gradual email send by sendId from get_email_analytics. Holds remaining deliveries; emails already delivered remain sent. Applies to gradual sends only. Use resume_email_send to continue or cancel_email_send to stop remaining deliveries permanently.	no	yes	yes	no	`POST /v1/sends/{sendId}/pause`
`restore_email_version`	Restore a saved email version as a new latest version. Read available versions with get_email first. Existing history is preserved. Automation steps pinned to the previous latest move to it as a draft.	no	yes	no	no	`POST /v1/emails/{emailId}/restore`
`resume_email_send`	Resume a paused gradual email send by sendId from get_email_analytics. Continues delivering real email to remaining recipients; applies to gradual sends only. On OAuth and organization connections, first obtain a confirmation request, then repeat with confirmed:true and its confirmation_id. Reuse the same idempotency_key when retrying.	no	yes	yes	yes	`POST /v1/sends/{sendId}/resume`
`save_email_group`	Create a named email folder, or rename an existing group by groupId. Pass emailIds (up to 50) to move designs into it in the same call, one request against the rate limit; resend any notMoved with reason retry. Omit groupId only when creating. update_email_metadata moves one design.	no	yes	yes	no	`POST /v1/email-groups`, `PATCH /v1/email-groups/{groupId}`
`search_templates`	Browse public templates by category or brand. Use semantic for relevance ranking (top 200), or query for a case-insensitive title substring or exact public ID. Pages contain metadata, preview links, and each template’s emailId (create_email takes it as referenceEmailId); a page of up to 8 shows as a gallery (the default page). Pass preview:false to list them as text. count:true returns the total for brand/category instead of rows, refreshed every 15 minutes; add groupBy brand or category for per-value counts, largest first, such as which categories a brand has. Use get_template for one template’s content.	yes	no	yes	no	`GET /v1/templates`
`send_email`	Send one campaign or a test:true QA email. A campaign goes from a verified marketing domain to a saved audience (audienceId) or to up to 50 existing subscribed contacts (to); it never creates contacts. With an idempotency_key a retry replays instead of sending twice. On OAuth and organization connections a campaign, or a test (except, on OAuth, one to the signed-in person), returns a confirmation request first; the same call with confirmed:true and its confirmation_id sends. Recurring/event mail uses fire_trigger_event or run_automation.	no	yes	no	yes	`POST /v1/sends`
`test_email_rendering`	Test a design’s appearance in specific inbox clients and devices. Reserves 10 credits; charges once when a screenshot is ready. Waits up to 30 s; read clients still rendering with get_email_rendering and the returned previewId. For a free general design preview use get_email.	no	no	no	yes	`POST /v1/emails/{emailId}/client-previews`
`update_email_metadata`	Rename a design, set its inbox subject or language, or move it to an existing group atomically; groupId:null ungroups. Free: it never generates content, charges credits, creates a version or shows a preview. Shares the 20/min email-edit limit: to move several designs, use save_email_group with emailIds. edit_email changes the design itself.	no	yes	yes	no	`PATCH /v1/emails/{emailId}`

Automations

Tool	What it does	Read-only	Destructive	Idempotent	Open world	HTTP equivalent
`cancel_audience_run`	Permanently cancel a manual-audience run by audienceRunId from list_automation_runs. Stops remaining steps; delivered emails remain sent. Repeating a cancellation is idempotent. Event and test runs use cancel_automation_run.	no	yes	yes	no	`POST /v1/automations/audience-runs/{audienceRunId}/cancel`
`cancel_automation_run`	Cancel one running event or test run by automationRunId from list_automation_runs or test_automation. Returns canceled with the status it was in; delivered emails remain sent. Use cancel_audience_run for manual-audience runs, or save_automation to change a flow.	no	yes	yes	no	`POST /v1/automations/runs/{automationRunId}/cancel`
`check_trigger`	Check whether a trigger can fire now and which published automations consume it. A trigger no published automation listens for is ready: false with a NO_PUBLISHED_AUTOMATION entry in blockers, not an error; publish one before firing. An integration trigger also returns delivery: whether Brew has received its event yet (Shopify sends a topic only to a webhook made for it); it never changes ready. Include payload to validate that example against its contract. A Brew-event (unsubscribe) trigger answers TRIGGER_NOT_FIREABLE: Brew starts it itself. Nothing fires or changes.	yes	no	yes	no	`GET /v1/automations/triggers/{triggerEventId}/readiness`, `POST /v1/automations/triggers/{triggerEventId}/contract/validate`
`delete_automation`	Use this when permanently removing an automation: its versions, run history and layout go, contacts mid-flow stop and scheduled launches are cancelled. The designs it references stay, and already-delivered emails are not unsent. Idempotent.	no	yes	yes	no	`DELETE /v1/automations/{automationId}`
`delete_trigger`	Use this when removing an unused trigger. Fails while any automation, published or draft, is wired to it; unpublishing is not enough. Delete those with delete_automation, or re-point each to another trigger with save_automation and republish a published one, then retry. Idempotent.	no	yes	yes	no	`DELETE /v1/automations/triggers/{triggerEventId}`
`ensure_brew_event_trigger`	Get or create the brand’s unsubscribe trigger: scope domain with a domainId from list_domains (unsubscribes from that domain’s emails) or scope all (from every email). Brew starts it itself on every unsubscribe from an email link or the mail app’s button, so fire_trigger_event refuses it. Wire it with save_automation; the contact just opted out of marketing, so send only what they need, such as confirming the unsubscribe, from a transactional domain.	no	no	yes	no	`POST /v1/automations/triggers/brew-events`
`fire_trigger_event`	Use this when starting published event automations from an app/event payload. Do not use `send_email` (one-off campaign) or `run_automation` (manual-audience launch). Requires a published automation listening for the trigger. With an `idempotency_key`, a retry replays the original runs instead of firing twice. On OAuth and organization connections it returns a confirmation request first; the same call with confirmed:true and its confirmation_id fires. A new payload email becomes a contact; a contact who unsubscribed is refused (RECIPIENT_UNSUBSCRIBED) and nothing is sent. A Brew-event (unsubscribe) trigger is refused (TRIGGER_NOT_FIREABLE): try its automation with test_automation.	no	yes	no	yes	`POST /v1/automations/triggers/{triggerEventId}/fire`
`get_automation`	Get an automation by automationId, including its creator, live publisher, canonical link and optional graph or versions. Include analytics:{from?,to?} for performance. Use list_automation_runs for execution logs.	yes	no	yes	no	`GET /v1/automations/{automationId}`, `GET /v1/analytics/automations`
`get_flow`	Show one public email sequence by its slug from list_flows: up to 12 steps with subjects, day offsets, previews and emailId references for create_email. `include: ["html"]` adds step content. An unknown slug returns FLOW_NOT_FOUND.	yes	no	yes	no	`GET /v1/flows/{slug}`
`get_trigger_contract`	Read a trigger’s payload contract before integration. Request format ts, zod, jsonschema or skill for generated code/docs. Use set_trigger_contract to change it.	yes	no	yes	no	`GET /v1/automations/triggers/{triggerEventId}/contract`
`infer_payload_contract`	Infer typed fields and uncertainty notes from the required example event payload. Nothing is saved. Review the draft, then persist it with set_trigger_contract before integrating the trigger.	yes	no	yes	no	`POST /v1/payload-contracts/infer`
`list_automation_runs`	Inspect run.kind execution for automation executions or audience for manual-audience launches. Pass automationRunId or audienceRunId to read one run; include logs on an execution for its node logs. Each kind has its own IDs and pagination cursor.	yes	no	yes	no	`GET /v1/automations/runs`, `GET /v1/automations/runs/{automationRunId}`, `GET /v1/automations/audience-runs`, `GET /v1/automations/audience-runs/{audienceRunId}`
`list_automations`	List saved automations with their IDs, creator, publication state, and Open-in-Brew links; search finds them by name. Use get_automation for graph or version details. Include analytics:{from?,to?} for performance. list_automation_runs retrieves logs.	yes	no	yes	no	`GET /v1/automations`, `GET /v1/analytics/automations`
`list_flows`	Browse public brand email sequences by brand, category, type or semantic relevance. Text only: each page lists its flows with their slug, email count and span, and total counts every flow the query matches, so limit 1 answers how many there are. Use get_flow with a slug to see one sequence’s emails. Use search_templates for single public designs or list_automations for your saved automations.	yes	no	yes	no	`GET /v1/flows`
`list_trigger_events`	Read past trigger fires, their match state and the runs they started; pass triggerInstanceId for one fire. Brew records one for each unsubscribe that starts an unsubscribe trigger. Fire payloads are not stored. list_automation_runs reads execution logs; get_email_analytics reads email engagement.	yes	no	yes	no	`GET /v1/automations/trigger-instances`, `GET /v1/automations/trigger-instances/{triggerInstanceId}`
`list_triggers`	List automation trigger definitions or read one triggerEventId. include:[“skill”] returns its integration brief. Use list_trigger_events for past fires. get_trigger_contract retrieves its payload schema.	yes	no	yes	no	`GET /v1/automations/triggers`, `GET /v1/automations/triggers/{triggerEventId}`
`pause_audience_run`	Pause a running manual-audience run by audienceRunId from list_automation_runs. Stops progress at the next step boundary; deliveries already in progress may finish. Pausing a run that is already paused returns paused and changes nothing. Use resume_audience_run to continue or cancel_audience_run to stop it permanently. Event and test runs use cancel_automation_run.	no	yes	yes	no	`POST /v1/automations/audience-runs/{audienceRunId}/pause`
`resume_audience_run`	Resume an operator-paused manual-audience run, or retry a failed run from its first undelivered step, by audienceRunId. Continues real email delivery; completed steps are skipped and partially delivered steps are refused to avoid duplicates. A plan-limit hold resumes automatically and cannot be resumed here. On OAuth and organization connections, first obtain a confirmation request, then repeat with confirmed:true and its confirmation_id. Reuse the same idempotency_key when retrying.	no	yes	yes	yes	`POST /v1/automations/audience-runs/{audienceRunId}/resume`
`run_automation`	Launch a manual-audience automation. dryRun previews without sending; scheduledAt/gradualSend control timing; with an idempotency_key a retry replays instead of launching twice. On OAuth and organization connections a real launch returns a confirmation request first; the same call with confirmed:true and its confirmation_id launches. Event-triggered flows use fire_trigger_event. send_email delivers a one-off campaign.	no	yes	no	yes	`POST /v1/automations/{automationId}/run`
`save_automation`	Create an automation graph, or edit an existing automationId. Setting paused:false resumes pending workflows and can continue real email delivery. State changes are explicit: published, paused, or stopInFlight (with published:false; permanently stops contacts mid-flow). On OAuth and organization connections publishing, resuming (paused:false) or stopInFlight returns a confirmation request first; the same call with confirmed:true and its confirmation_id applies it. dryRun validates without saving; test_automation exercises the flow.	no	yes	no	yes	`POST /v1/automations`, `PATCH /v1/automations/{automationId}`
`save_trigger`	Define an event for automations, or update its existing triggerEventId. Keep the required recipient email field in the payload schema. Fire a real event with fire_trigger_event.	no	yes	no	no	`POST /v1/automations/triggers`, `PATCH /v1/automations/triggers/{triggerEventId}`
`set_trigger_contract`	Set a trigger payload contract. Keep a required top-level email string. Version changes only when behavior changes; enable enforcement explicitly after testing.	no	yes	yes	no	`PUT /v1/automations/triggers/{triggerEventId}/contract`
`test_automation`	Test a draft or published automation. Omit testRecipient to send nothing. On OAuth and organization connections a test to a testRecipient (except, on OAuth, the signed-in person) returns a confirmation request first; the same call with confirmed:true and its confirmation_id runs it. scenario simulates timed engagement and forces percentage branches; payload drives field conditions, and contact.<name> ones read the stored contact unless payload sets that key; a test never creates or edits a contact. On a Brew-event (unsubscribe) trigger, omit payload to use Brew’s sample event; a payload overrides its fields. Omit scenario for a smoke test. Inspect coverage; one run cannot prove every path.	no	yes	no	yes	`POST /v1/automations/{automationId}/test`

Contacts and audiences

Tool	What it does	Read-only	Destructive	Idempotent	Open world	HTTP equivalent
`create_audience`	Create a saved contact segment from filters, or copy one with sourceAudienceId (and an optional name for the copy). Contacts are not duplicated. Use create_audience_from_events for a frozen engagement-event cohort.	no	no	no	no	`POST /v1/audiences`
`create_audience_from_events`	Save a frozen contact cohort from engagement events. Poll list_audiences with the returned audienceId and include:[“build”] until ready before sending. create_audience creates a live filter instead.	no	no	no	no	`POST /v1/audiences/from-events`
`create_contact_field`	Define a contact field and its type before writing values through update_contact, import_contacts or import_contacts_csv.	no	no	yes	no	`POST /v1/fields`
`delete_audience`	Use this when removing a saved audience. Does not delete the contacts in it. Idempotent.	no	yes	yes	no	`DELETE /v1/audiences/{audienceId}`
`delete_contact_field`	Use this when removing a custom field and its value from every contact. The values cannot be recovered, and audience filters on the field then see no value. On OAuth and organization connections it returns a confirmation request first; the same call with confirmed:true and its confirmation_id deletes. Cannot delete core system fields. Idempotent.	no	yes	yes	no	`DELETE /v1/fields/{fieldName}`
`delete_contacts`	Permanently delete one or more contacts by email. Pass a nonempty emails array; already missing contacts are safe to retry. On OAuth and organization connections it returns a confirmation request first; the same call with confirmed:true and its confirmation_id deletes.	no	yes	yes	no	`DELETE /v1/contacts/{email}`, `POST /v1/contacts/batch-delete`
`import_contacts`	Add or update up to 1000 contacts from JSON rows (email, firstName, lastName, subscribed, customFields, consent). Missing contacts are created subscribed unless a row says subscribed:false; existing ones are updated (onConflict:“skip” leaves them unchanged), and re-subscribing an opt-out is skipped with a RESUBSCRIBE_SKIPPED warning. A missing, invalid or repeated address fails its row. Listed in Import History under fileName; returns importId. dryRun:true returns the same counts and writes nothing. Free unless validate:true (2 credits per address). Use import_contacts_csv for CSV text and update_contact for one contact.	no	yes	no	yes	`POST /v1/contacts/import`
`import_contacts_csv`	Import up to 1000 CSV rows. Headers map by name; mapping overrides columns. Creates missing contacts subscribed unless the row opts out; updates existing ones (onConflict:“skip” leaves them unchanged), never re-subscribing an opt-out (RESUBSCRIBE_SKIPPED). Invalid subscription values fail their row. Missing/invalid emails and earlier duplicates are skipped. Brew-managed columns warn CSV_COLUMN_IGNORED. Listed in Import History under fileName; returns importId. dryRun:true previews and writes nothing. Free unless validate:true: inline <=100 submitted rows cost 2 credits per submitted row; larger background validation costs 2 credits per checked address. Use import_contacts for JSON.	no	yes	no	yes	`POST /v1/contacts/import-csv`
`list_audiences`	List saved contact segments with their current member counts (search narrows them by name), or fetch one audienceId. Only that one-audience read takes include: count recomputes its size, build adds an event snapshot’s build status. search_contacts retrieves the members.	yes	no	yes	no	`GET /v1/audiences`, `GET /v1/audiences/{audienceId}`
`list_contact_fields`	List the brand’s contact field definitions and types before filtering or updating custom contact data. create_contact_field adds a definition.	yes	no	yes	no	`GET /v1/fields`
`search_contacts`	Read-only query over the brand’s own contacts. Returns personal data: rows carry email, name, subscription and suppression state, validation status and custom fields; response_format “detailed” returns the full row. Default 10 rows per page, max 25. A search that is one whole email address returns only that contact; other text matches any of its words. With count:true returns the exact total instead; groupBy or bucket adds per-value breakdowns. include [“openProfile”] adds open-time profiles (up to 10 per page). Never creates, modifies or deletes contacts. Use list_contact_fields for field names; create_audience saves a reusable segment.	yes	no	yes	no	`POST /v1/contacts/search`
`update_audience`	Rename a saved audience, replace its filter, or add/remove specific contacts by email (addEmails/removeEmails). For a separate copy, use create_audience with sourceAudienceId.	no	yes	yes	no	`PATCH /v1/audiences/{audienceId}`
`update_contact`	Update an existing contact by email with a partial fields map; a missing contact is refused (CONTACT_NOT_FOUND) and nothing is created. Custom fields must already exist; create_contact_field adds one. Supports null clearing. subscribed:false unsubscribes; true never re-subscribes an opt-out (RESUBSCRIBE_NOT_ALLOWED). updated names only fields whose value changed; warnings flags an ambiguous date read month/day (DATE_ORDER_ASSUMED). validate:true checks deliverability for 2 credits per address.	no	yes	no	yes	MCP only
`validate_contacts`	Check deliverability for up to 100 addresses at 2 credits per address, saving verdicts on matching contacts without creating new ones. update_contact can also validate after saving.	no	yes	no	yes	`POST /v1/contacts/validate`

Domains

Tool	What it does	Read-only	Destructive	Idempotent	Open world	HTTP equivalent
`add_domain_unsubscribes`	Add addresses to one marketing domain’s unsubscribe list so that domain stops sending to them: `emails` (up to 1,000) or `csv` (CSV text, up to 10,000 rows), not both. Known contacts still receive mail from the brand’s other marketing domains; an address with no contact is created already unsubscribed everywhere. Idempotent. Both return the same counts. Taking an address off the list happens in the Brew app, not over MCP.	no	yes	yes	no	`POST /v1/domains/{domainId}/unsubscribes`, `POST /v1/domains/{domainId}/unsubscribes/import`
`create_domain`	Register a sending domain and return DNS records for verify_domain. A new domain is marketing; an authorized reclaim of an unverified domain keeps the purpose it had, can move it from another brand and clears sender defaults. If it becomes sendable during registration, an eligible initial measurement sends real email to fixed Brew seed inboxes. Transactional domains are set up in the Brew app.	no	yes	yes	yes	`POST /v1/domains`
`delete_domain`	Use this when removing a sending domain. Idempotent. Campaigns cannot send from a deleted domain.	no	yes	yes	no	`DELETE /v1/domains/{domainId}`
`get_domain_health`	Diagnose sending-domain DNS, authentication, reputation and deliverability. Start here; create_inbox_placement_test measures where a specific email lands. include [“scoreHistory”] adds up to 50 saved score snapshots, newest first; [“scoreRuns”] adds the last 5 automated score runs.	yes	no	yes	no	`GET /v1/domains/{domainId}/health`
`list_domains`	List sending domains, DNS records, verification, and sending purpose. Choose a verified marketing domain for campaigns. Use verify_domain only while a domain is not sendable. get_domain_health diagnoses DNS and reputation.	yes	no	yes	no	`GET /v1/domains`
`update_domain`	Change a domain’s default sender name, from address or reply-to; this never changes sending purpose, which is set in the Brew app. An eligible verified domain without an initial automatic measurement queues one, sending real email to fixed Brew seed inboxes. verify_domain rechecks DNS.	no	yes	yes	yes	`PATCH /v1/domains/{domainId}`
`verify_domain`	Recheck DNS after adding records from create_domain; a sendable domain is refreshed. Persists verification and tracking state and can disable or restore provider tracking, queue an initial measurement that sends to Brew seed inboxes, and hold or release existing campaigns. Releasing a domain hold resumes delivery to remaining recipients. On OAuth and organization connections, a domain with held campaigns first returns a confirmation request; repeat with confirmed:true and its confirmation_id. get_domain_health diagnoses without these changes.	no	yes	yes	yes	`POST /v1/domains/{domainId}/verify`

Brand

Tool	What it does	Read-only	Destructive	Idempotent	Open world	HTTP equivalent
`create_brand` (organization connections only)	Create a brand by extracting its website. Organization connections only. Poll get_brand with the returned brandId as brand_id until ready is true before designing.	no	no	no	yes	`POST /v1/brands`
`get_brand`	Read a brand: its saved name, tagline and links (always returned), status, ready and extraction progress. While a brand is extracting, call it again until ready is true before designing. include adds the design system, image style and logos. list_brands discovers brands.	yes	no	yes	no	`GET /v1/brand`
`list_brands`	List brands this connection can access. Organization connections choose a returned brandId for brand_id on scoped tools; brand connections see only their bound brand.	yes	no	yes	no	`GET /v1/brands`
`update_brand`	Update identity fields such as brandName, description and contact details by partial merge. emailDesign and imageStyle replace their Markdown artifacts in full. Omitted fields stay unchanged; colors and logos are not writable identity fields.	no	yes	yes	no	`PATCH /v1/brand`

Images and media

Tool	What it does	Read-only	Destructive	Idempotent	Open world	HTTP equivalent
`add_image`	Add an image to the brand library. Free. imageUrl hosts one public URL; imageUrls imports up to 100 in the background; uploadId finishes a local-file upload, and repeating that call returns the same image. search_brand_images finds an image the brand already has; create_email and edit_email make new imagery inside a design.	no	no	no	yes	`POST /v1/content/add-image`
`create_image_upload`	Open a single-use upload for one local image file. Free. Returns uploadId and uploadUrl, which takes the file’s raw bytes as an HTTP POST body for 15 minutes; add_image with that uploadId then puts the image in the brand library. For a client that can send the file itself; a public image URL goes straight to add_image as imageUrl. PNG, JPEG, GIF, WebP, AVIF, TIFF or SVG; 20 MB max, SVG 2 MB.	no	no	no	no	`POST /v1/content/image-uploads`
`delete_brand_image`	Delete one image from the brand library, as Delete image on the Assets page does. Pass the assetId from search_brand_images; one image per call. The image leaves the library and image search, but its file stays hosted, so emails already using its URL keep rendering. Logos are refused; manage them on the Assets page. An assetId not in the library returns deleted: false. Idempotent. Free. Use add_image to add an image.	no	yes	yes	no	`DELETE /v1/brand/images/{assetId}`
`render_html_image`	Render HTML into a hosted PNG for 1 credit. Use get_email for an existing design preview or test_email_rendering for inbox-client screenshots.	no	no	no	yes	`POST /v1/content/html-to-png`
`search_brand_images`	List the brand’s logos and brand images (from the site or uploaded), free; sort newest or oldest. Pass q for semantic search over brand images, also free. For a hero or photo, use kind brand. Imagery made with Brew stays inside the designs that use it; create_email and edit_email make new imagery. add_image adds a URL or an uploaded file; delete_brand_image removes one by assetId.	yes	no	yes	no	`GET /v1/brand/images`

Account and discovery

Tool	What it does	Read-only	Destructive	Idempotent	Open world	HTTP equivalent
`get_brew_capabilities`	Discover this connection’s scope and available tools. Filter by topic or tool for focused help and schemas; detailed adds a paginated HTTP API catalog. The default is a compact overview, so call only when guidance is needed.	yes	no	yes	no	MCP only
`get_chat_artifacts`	Read a selected Brew chat’s title, link and referenced email designs, automations and triggers by chatId. Use after a chat handoff or selecting a chat with list_chats. Organization connections require the owning brand_id. Load a referenced design with get_email before editing it. Returns artifacts only; no conversation messages.	yes	no	yes	no	`GET /v1/chats/{chatId}`
`get_usage`	Use this when checking plan, remaining credits, or send allowance before a metered operation. Organization scope; no `brand_id`.	yes	no	yes	no	`GET /v1/usage`
`list_chats`	Find Brew chats in the connected brand, newest first. Returns chatId, title, updatedAt and a link, with a pagination cursor. Use get_chat_artifacts to read a selected chat’s referenced designs and automations. Conversation messages and snippets are excluded.	yes	no	yes	no	`GET /v1/chats`
`list_integrations`	List connected or available integrations. A human connects providers in Brew Settings; this read does not begin OAuth.	yes	no	yes	no	`GET /v1/integrations`
`list_notifications`	List the brand’s Brew notifications, newest first, as the app’s bell shows them: generations, sends, imports, domain checks and score runs finishing or failing, plus comment mentions addressed to you on a personal connection. Each row has its notificationId, type, status, title, subtitle, a link and the ids it concerns (chatId, emailId, domainId). Rows outside this connection’s access are left out, so a type it cannot see is an empty page; billing alerts reach organization admins only. Read-only and free; nothing is marked read. Follow a chat with get_chat_artifacts.	yes	no	yes	no	`GET /v1/notifications`
`report_tool_issue`	Use this when the user asks to report a problem with a Brew tool. Files a technical diagnostic report about one failed call for Brew support: the tool name, its status and error code, a Brew request ID if the user has one, and a short description of what went wrong (no conversation text). Free. Returns a flareId support can look the report up by. Product feedback goes to submit_feedback.	no	no	no	no	MCP only
`submit_feedback`	Use this when the user asks to send the Brew team a problem, a feature request, a question or praise. Sends their own message to the Brew inbox, with an optional title and issue type. Do not include conversation history or unrelated context. The message carries no secrets, API keys, tokens or recipient addresses. Technical diagnostics for failed tool calls go to report_tool_issue.	no	yes	no	yes	MCP only

Resources

Attach a resource to give your agent context before it calls tools. Each resource uses the connection’s permissions. Brand context resources are available on brand connections; organization connections offer the public gallery resources and can request brand context through tools with brand_id.

Resource	Context	Connection
`brew://templates`	Ten public template summaries with reference IDs and preview links.	Brand or organization
`brew://flows`	The first 100 public email sequences, with slugs, email counts, time spans, and the `total`. Page through the rest with `list_flows`.	Brand or organization
`brew://brand`	Brand identity and voice, email design document, image style, and logos, plus extraction readiness.	Brand
`brew://emails`	The connected brand’s newest email designs with preview links.	Brand
`brew://audiences`	Saved audiences for the connected brand, each with a cached `count` that can lag. For a fresh size, call `list_audiences` with the `audienceId` and `include: ["count"]`.	Brand

brew://brand returns the brand’s saved identity (name, tagline, description, links) with emailDesign, imageStyle, and logos. For the same context through a tool, use get_brand({ include: ["emailDesign", "imageStyle", "logos"] }). A plain get_brand already returns the identity.

Conventions

`response_format`

Only two tools take response_format, because only their results come in two shapes. Every other tool returns one shape and refuses the field as an invalid argument.

Tool	`concise` (default)	`detailed`
`search_contacts`	Each row has the address, name, subscription and suppression state, validation status, and custom fields (plus `openProfile` when you `include` it).	The full contact row, adding import, consent, per-domain opt-out, validation-provider, and timestamp details.
`get_brew_capabilities`	The overview alone.	Also `http_api`, a paginated catalog of HTTP endpoints; continue it with `http_cursor`.

The HTTP API, SDK, and CLI always return the full contact row. Every result carries its record in structuredContent, and every tool publishes that record’s shape as its outputSchema in tools/list, so a client can validate a result and read its fields without guessing.

`idempotency_key`

Write tools that can be retried accept an optional idempotency_key: a repeat call with the same key replays the original result instead of acting twice. Use a fresh UUID per intended action. See Safe Retries.

`include`

Expansions are opt-in. Every tool that takes include takes an array of the expansion names its input schema lists (include: ["html"] on get_email, include: ["emailDesign", "logos"] on get_brand). A string is refused.

Previews

Email and image tools attach Brew’s stored preview where your client can show it in the transcript, plus an Open in Brew link, and the result’s text says which previews the client shows. Markdown images are left out: some clients turn them into a “Show Image” button instead of the design. preview: false returns text only.

Confirmation

On OAuth and organization connections, a call that emails people or removes contact data returns a confirmation request first: campaigns, tests to someone else, automation launches and trigger fires, publishing or resuming an automation, resuming a send, deleting contacts or a contact field, and verifying a domain that has campaigns held on it. After the user approves, the same call with confirmed: true and the request’s confirmation_id runs it. See Confirmation.

Limit Errors

When a call hits a plan limit (INSUFFICIENT_CREDITS, SEND_QUOTA_EXCEEDED, BRAND_LIMIT_REACHED, or an audience run held at the send allowance), the MCP error states the limit and when it resets. It does not suggest upgrading. get_usage shows the limit, the balance, and the reset date (period.end). The brand limit does not reset; deleting an unused brand frees a slot. The HTTP API keeps its own suggestion text.

Result Size

Results are sized to fit a model’s context:

A list page comes back whole or not at all. When a page is too large, the call returns RESPONSE_TOO_LARGE with no rows and names what to lower (the limit, or an include expansion). Rows are never trimmed behind a cursor. list_insights is the one exception: it trims instead of refusing.
List pages are smaller than the HTTP API’s, and each tool’s limit states its bounds. MCP Page Sizes owns the numbers and the list_insights trimming rule.
A single record comes back whole in structuredContent. Its text summary may be shortened, keeping the identifiers and next steps. A record past the hard cap returns RESPONSE_TOO_LARGE too.
A write always returns its outcome. An oversized result is compacted in place (long strings and arrays shortened), keeping every field’s type.

Email Language

Every design carries a lang: the language its copy is written in, 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 get_email returns.

get_email returns lang on the design once Brew has read it.
create_email accepts lang to name the language up front. Omit it and Brew detects it from the finished body.
update_email_metadata accepts lang to set or correct it. Like the other metadata fields it is free and creates no version. A value you set is kept: Brew stops re-detecting it after later edits. Pass lang: null to clear it, and Brew reads the language from the email again.

Chat Artifacts and Feedback

list_chats returns chat titles, links and timestamps. Select a chat and use get_chat_artifacts for its referenced email designs, automations and triggers. These tools do not return previous messages, conversation snippets, channel context or the model used in the chat. import_contacts (JSON rows) and import_contacts_csv (CSV text) create missing contacts, subscribed unless a row opts out, and update existing ones. Both take consent, validate and fileName, record the batch in Import History, and return its importId. onConflict: "skip" leaves existing contacts unchanged, and dryRun: true returns the same counts without writing anything. update_contact updates one existing contact and cannot create one. Contact field values must match the declared field type; use list_contact_fields to read those definitions. When you ask to send feedback, submit_feedback takes your message, an optional title and an issue type. Brew redacts secrets and addresses and sends those fields to Notra’s Brew inbox. report_tool_issue records a requested technical issue for Brew support and returns a support reference. Neither automatically attaches conversation history. Ordinary tool results keep diagnostic identifiers on the server. Read our Privacy Policy for data recipients, retention, public asset handling and deletion controls.

Need Help?

Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you:

Self-Service Tools
Talk to Our Team

Search Documentation

Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.

Ask ChatGPT or Claude

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

Start Here

Public API v1

API Contracts

API Guides

MCP Server

CLI

SDKs

Tool Catalog

Email

Automations

Contacts and audiences

Domains

Brand

Images and media

Account and discovery

Resources

Conventions

`response_format`

`idempotency_key`

`include`

Previews

Confirmation

Limit Errors

Result Size

Email Language

Chat Artifacts and Feedback

Need Help?

Search Documentation

Ask ChatGPT or Claude

Schedule a Call

Call Us Directly

Slack Channel

Email Support

​Tool Catalog

​Email

​Automations

​Contacts and audiences

​Domains

​Brand

​Images and media

​Account and discovery

​Resources

​Conventions

​response_format

​idempotency_key

​include

​Previews

​Confirmation

​Limit Errors

​Result Size

​Email Language

​Chat Artifacts and Feedback

​Need Help?

Search Documentation

Ask ChatGPT or Claude

Schedule a Call

Call Us Directly

Slack Channel

Email Support

Tool Catalog

Email

Automations

Contacts and audiences

Domains

Brand

Images and media

Account and discovery

Resources

Conventions

`response_format`

`idempotency_key`

`include`

Previews

Confirmation

Limit Errors

Result Size

Email Language

Chat Artifacts and Feedback

Need Help?