@alihaiderrana/email-builder-sdk

React SDK for embedding the Circles Email Builder in your app.

Install

npm install @alihaiderrana/email-builder-sdk

Quick Start

import { EmailBuilder } from '@alihaiderrana/email-builder-sdk';

export function EmailEditor() {
  return (
    <div style={{ height: '100vh' }}>
      <EmailBuilder
        embedToken={process.env.NEXT_PUBLIC_EMAIL_BUILDER_TOKEN}
        initialHtml="<h1>Welcome</h1><p>Edit this email template</p>"
        showFooter={true}
        includeUnsubscribe={true}
        footerInjectionMode="sdk"
        externalFooterHtml="<div>Custom footer</div>"
        onAuthError={(message) => console.error('auth failed', message)}
        onChange={(html) => console.log('changed', html)}
        onSave={(html) => console.log('saved', html)}
        onUpload={async (file) => {
          const body = new FormData();
          body.append('asset', file);
          const response = await fetch('/api/uploads', { method: 'POST', body });
          const data = await response.json();
          return data.url;
        }}
        onListAssets={async () => {
          const response = await fetch('/api/assets');
          const data = await response.json();
          return data.assets;
        }}
        onDeleteAsset={async ({ id }) => {
          if (!id) return false;
          const response = await fetch(`/api/assets/${id}`, { method: 'DELETE' });
          return response.ok;
        }}
      />
    </div>
  );
}

If initialHtml is not provided, the editor starts with a default Hello World template. If src is not provided, the SDK uses the managed Circles builder endpoint.

Props

| Prop | Type | Required | Description | | --- | --- | --- | --- | | embedToken | string | Yes | Token passed to iframe for backend verification. | | src | string | No | Optional custom builder URL override. | | initialHtml | string | No | Initial HTML content to load in the editor. | | templateId | string | No | Optional template id; builder fetches HTML from backend when provided. | | showFooter | boolean | No | Show "Powered by Public Circles" branding in footer. Defaults to true. | | includeUnsubscribe | boolean | No | Include unsubscribe link in footer. Defaults to true. | | externalFooterHtml | string | No | Optional host-provided footer HTML snippet. | | footerInjectionMode | 'default' \| 'sdk' | No | Footer source mode. Use 'sdk' to apply externalFooterHtml. | | config | Record<string, unknown> | No | Optional builder configuration object. | | className | string | No | Class for the wrapper container. | | style | React.CSSProperties | No | Inline styles for the wrapper container. | | iframeTitle | string | No | Accessible title for the iframe. | | sandbox | string | No | Custom iframe sandbox value. | | allowedOrigin | string | No | Override allowed origin for message validation. | | onReady | () => void | No | Called when editor is ready. | | onStatusChange | (status) => void | No | Called on status changes (loading, ready, error). | | onChange | (html: string) => void | No | Called when editor content changes. | | onSave | (html: string) => void | No | Called when user saves content. | | onUpload | (file: File) => Promise<string> | No | Upload handler that returns a public URL for inserted assets. | | onListAssets | (payload?: { limit?: number }) => Promise<AssetItem[]> | No | Returns previously uploaded images for the picker modal. | | onDeleteAsset | (payload: { id?: string; url?: string }) => Promise<boolean> | No | Deletes an uploaded asset and returns whether it succeeded. | | onAuthError | (message: string) => void | No | Called when token is missing/invalid/rejected. |

AssetItem shape:

type AssetItem = {
  url: string;
  id?: string;
  name?: string;
  thumbnailUrl?: string;
};

Image Management Contract

To support reusable image uploads for any client app:

• implement onUpload to upload a file and return a public URL
• implement onListAssets to return uploaded images
• implement onDeleteAsset to delete uploaded images from your backend/storage

The SDK stays storage-agnostic (S3, GCS, Cloudflare R2, etc.).

Ref API

EmailBuilder supports a ref with:

• reload(): void - Reloads the embedded editor iframe.

Requirements

• React >=18.2.0
• ReactDOM >=18.2.0

License

MIT