Skip to main content
Embed Brew’s email canvas inside your app with a client ID and exactly one 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 through onError. 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 as https://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:
The open source demo installs the released SDK from npm.

Embed a Group or One Email

For a single email, replace 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

Give the container a nonzero height. 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:
Keep the matching group canvas mounted while your backend generates emails. New emails and their content appear live. Use 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 adds onEmailSelectionChange. Keep a group canvas mounted and record its resolved displayed selection:
Import 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:
This creates a separate email. Keep the source and each locale’s returned email/version IDs in your existing records. Review the generated translation and layout before approval. 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’s groupId. 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

These metadata-only updates do not run AI or create versions. Ungrouped is a reserved group and cannot be renamed.

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. Replace clientId with a provider that calls your authenticated endpoint:
Your endpoint receives { 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.

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:

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.