groupId or emailId. Customers can watch emails generate live, review them
together, edit by hand, and use the editor panel. They need no Brew login, and
your browser code needs no API key.
For a private admin app with customer sign-in, start with
Build a White-Label Email Editor.
That guide connects brand extraction, generation, per-user canvas access, and
saved HTML. The client ID flow below grants access to all brands in an
organization, or one specific brand, from an allowed origin.
What You Can Build
- An email builder inside your SaaS product
- A shared workspace that shows generation results as they arrive
- A single-email editor inside an approval flow
- A review portal with editing turned off
Browser Support
The embedded canvas uses the same GPU renderer as the Brew app. Browsers need WebGPU or WebGL2. Selected emails stay editable while other frames can use GPU previews. If neither backend can initialize, the canvas reports the problem throughonError. Your app can offer saved HTML while the customer retries in a
browser with GPU support.
Create a Client App
Open Settings → API → Client apps in Brew. Choose Create client ID, name the app, choose All brands or a specific brand, add its allowed origins, and save. Copy the client ID into your app. Organization admins can choose All brands, including brands created later, and can create a client ID before adding any brands. Brand members can create IDs only for their authorized brands. Allow exact origins, such ashttps://app.example.com or
http://localhost:3500, including the port when there is one. Paths, trailing
slashes, and wildcards aren’t accepted. HTTPS is required, except for loopback
development.
Whether customers can edit is a setting on the client app.
Install the SDK
Use SDK 13.2.0 or newer:Embed a Group or One Email
groupId with emailId. Passing both or neither
is rejected by TypeScript and at runtime.
Pass the selected brandId with an All brands client ID, including for the
reserved ungrouped group. A specific-brand client ID can omit it for backward
compatibility; passing another brand is rejected. The client ID sets editing
permissions. You do not pass user, permission, origin, or session fields.
One organization-wide client ID can serve your brand switcher. Each session
still opens only one brand and one group or email. Changing brandId in React
acquires a new scoped session; create and edit results within the current
board do not require remounting it.
React 18 and 19 are supported. The component defaults to 640px tall.
The SDK handles sign-in and renews the session without reloading the iframe.
The canvas works even when third-party login cookies are blocked.
For each client app, the SDK keeps a public recovery ID in your app’s local
storage. It uses that ID to recover unsaved drafts after a reload. Session ownership
secrets stay in memory.
Without local storage the canvas still works, but drafts don’t survive a
reload.
Use Another Framework
fitView(), focusEmail(emailId), and
flush() and clearSelection() return promises.
React exposes the same methods through an EmailCanvasHandle ref. Await
flush() before leaving. If the save fails, keep the canvas mounted so the
customer can retry.
Use onDirtyChange to warn before navigation, onSaved for save feedback,
and onSelectionChange for selection.
What the Embedded Canvas Includes
Multiplayer shows live presence, selections, and saved updates. One person edits an email at a time, so there is no simultaneous character-level editing. The editor panel covers text, color, spacing, layout, image upload, and cropping. Workspace media search, logos, Giphy, and AI image generation need separate capabilities and aren’t in the embedded panel.Use Brew Headlessly
Use the browser canvas as the editing surface, and Brew’s API for generation and management. API keys stay on your backend:brew.emailGroups to manage groups and brew.emails to manage designs.
Return an authorized email ID when opening a single-email editing step. A
client ID can’t authorize API generation, sending, or management.
Select a Template and Create Locale Variants
SDK 13.1.0 addsonEmailSelectionChange. Keep a group canvas mounted and
record its resolved displayed selection:
CanvasSelectedEmail from @brew.new/sdk/embed.
The callback receives
[] on deselection or removal and while a version is
switching or unresolved. The existing onSelectionChange still returns IDs.
After authorizing the selection on your backend, create a new locale email:
referenceEmailId reads the reference’s latest saved version. To remix an
exact historical selection, first call
emails.clone({ emailId, emailVersionId, title }).
Use the clone’s emailId
as the reference. A clone copies content exactly; remixing runs AI.
Keep the Canvas Mounted During Writes
Generate into the mounted group’sgroupId. New emails and edited versions
arrive through its live subscriptions. Avoid a React key based on the current
email or version ID.
Before an API AI edit, await canvas.current.clearSelection(). It saves
pending changes and releases the editing lease without replacing the iframe.
Prevent new manual selection while your backend request runs.
Use the exact selected emailVersionId as the edit baseline, then call
focusEmail(emailId) after the updated email is available. If saving fails,
keep the editor open and do not start the API write.
clearSelection() is also available on createEmailCanvas controllers.
Changing the authorized brand or group still requires a new scoped canvas.
Rename Groups and Emails
Understand the Access Boundary
Client IDs are public app credentials. Brew checks the browser’s Origin against the client’s allowlist before issuing short-lived credentials. The iframe accepts framing only from that origin. Every content, edit, and presence operation rechecks the client configuration and brand access. A client ID authenticates the configured app, not an individual person. Visitors to an allowed origin can request groups and emails within its configured brand scope. All brands grants access to every current and future brand in that organization; a specific-brand client grants only that brand. Opaque target IDs, or hiding a target in your UI, don’t give per-user access control. Non-browser callers can forge Origin headers. For tenant isolation, use a dedicated brand and client app per customer. For private per-user or per-target access, use your own login and the server-authorized flow below.Revoke or Change Access
Revoking a client app in Settings ends its canvas access. Changing its origins, editing permissions, or brand scope ends existing sessions. Customers can reopen the canvas with the new access settings. When the SDK unmounts, it closes the session it owns on a best-effort basis. Sessions from lost connections expire on the server.Copy the Client-ID Integration Prompt
Use this for an app-level canvas integration. For private staff permissions, use the server-authorized flow below.Advanced Per-User Authorization
Use this when individual users need narrower access than the client app’s brand. Any login provider works. ReplaceclientId with a provider that calls
your authenticated endpoint:
{ target, sessionId? }. Authenticate the caller, and
resolve the allowed brand and target from your own data.
Then call
brew.canvas.sessions.create({ target, user: { externalId, name }, parentOrigin, permissions })
with a server-side API key.
Keep session ownership in your backend. Renew only the caller’s own grant with
brew.canvas.sessions.refresh(sessionId), and revoke it when access ends. A
session ID alone doesn’t prove ownership.
Recheck the caller’s target and permissions on every renewal. Return the
session object directly as JSON with Cache-Control: no-store. Set
parentOrigin from trusted server configuration.
The custom provider does not
automatically revoke a session on unmount; your app owns that lifecycle.
Never pass both clientId and getSession. The brandId prop belongs to
client-ID mode. With getSession, authorize and supply the brand in your
backend grant request instead.
Run the Open Source Demo
The MIT-licensed Next.js demo and README show client ID setup, group and single-email views, and autosave. They also cover failed-save recovery and saving before navigation. The demo needs no authentication-provider keys or API key. The README covers installation, tests, deployment, and the headless use cases above. Before release, test your deployed HTTPS app from an allowed origin and a denied one. Confirm your CDN preserves the iframe’s framing policy, then upload, crop, save, and reopen a real image. Local fixture tests don’t verify production CDN or object-storage configuration.Related
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.