React integration

Embed the hosted MailLayers editor in React

Use the lightweight React SDK to mount the hosted MailLayers editor in an iframe with typed events, exact-origin checks, server-issued tokens, and host-controlled assets.

Published on npm

Version 0.2.2 · Install from npm or review the source on GitHub.

npm install @maillayers/react-email-editor
React client component
import { useRef } from "react";
import {
  MailLayersEmailEditor,
  type EmailBuilderHandle,
} from "@maillayers/react-email-editor";

export function EmailEditor({ apiKey, embedToken }) {
  const editor = useRef<EmailBuilderHandle>(null);

  return (
    <MailLayersEmailEditor
      ref={editor}
      apiKey={apiKey}
      embedToken={embedToken}
      initialHtml="<h1>Welcome</h1>"
      onSave={(html) => saveHtml(html)}
      onAuthError={(message) => report(message)}
    />
  );
}

Production integration

Content, assets, security, and lifecycle

A useful embedded email editor is more than a mounted component. Plan the persistence and trust boundaries before connecting it to customer data.

Editor data methods

Use getHtml() for a sendable snapshot and getJson() for structured editor state. Call reload() only when staged content or configuration should start a new iframe handshake; use ready, load, change, save, and status callbacks for normal updates.

Assets

Implement upload, list, and delete handlers against storage owned by your application. Validate file type and size on the server, authorize each tenant-scoped object, return HTTPS URLs, and treat delete as an authenticated operation.

API keys and allowed domains

Use a browser SDK key only from an exact configured origin. Keep privileged secrets on your server, issue scoped embed tokens after authenticating the user, and do not treat iframe messages as trusted until origin and payload validation pass.

Multiple instances

Give each mounted editor stable state and separate callbacks. Avoid reusing one imperative ref across instances, and unmount inactive editors when tabs or routes no longer need them so listeners and iframe resources are released.

Performance

Reserve editor height to prevent layout shift, defer mounting until the authoring UI is needed, and show a stable loading fallback. Avoid remounting the iframe for ordinary form-state changes; prefer events and staged reloads.

Troubleshooting

If the editor does not become ready, verify the allowed origin, browser key, embed-token lifetime, editor URL, and Content Security Policy. For missing saves, inspect callback errors and confirm the host persistence request succeeds independently of the iframe.

Integration

React owns the host lifecycle; the iframe owns editor isolation

  1. 01

    Render the component only in the browser. Next.js applications place it in a client component; the module itself is safe to import during SSR.

  2. 02

    Issue the embed token from an authenticated server flow and pass it to the client. Do not expose privileged server credentials through public environment variables.

  3. 03

    Persist HTML from onChange or onSave, and use the ref reload method when staged initial content or configuration should begin a new handshake.

Relevant capabilities

What this integration actually supports

Strict message boundary
Protocol payloads and the configured iframe origin are validated before messages are accepted.
Full asset callbacks
Upload, list, and delete remain host-controlled operations with cancellation support.
Typed lifecycle
Ready, status, load, change, save, and sanitized authentication-error callbacks integrate with React state.

Product boundary: MailLayers is the hosted editing surface, not an authentication provider, asset store, approval engine, ESP, or email delivery service. Your application owns users, persistence, and sending.

Related integration guides

Engineering articles

Read implementation notes about editor security, persistence, asset workflows, and framework-specific patterns.

Browse the MailLayers blog

FAQ

Questions specific to this integration

Does the React package work with React 19?

Yes. The package supports React 18.2+ and React 19 peer ranges.

How should Next.js load the editor?

Use a client component with the same React SDK. Generate scoped embed tokens on the server and pass them into that client boundary. See the Next.js guide for App Router patterns.

Who stores images and exported HTML?

Your application does. The SDK calls your asset handlers and returns editor content for your persistence workflow.

Continue with the verified integration guide

Review licensing, allowed domains, events, assets, SSR boundaries, and troubleshooting before production use.