API Reference

interface EditorOptions {
  container: HTMLElement;          // DOM element to mount editor
  initialValue?: EmailTemplate;    // Starting template
  theme?: EditorTheme;             // Custom theme
  blocks?: BlockDefinition[];      // Redefine standard block types; new types are refused
  onChange?: (template: EmailTemplate) => void;
  onSave?: (template: EmailTemplate) => void;    // Receives the current template
  onRequestImage?: OnRequestImage;               // Your image picker, see below
}

interface EditorInstance {
  getValue(): EmailTemplate;              // The latest document
  setValue(template: EmailTemplate): void;
  getHTML(): string;                      // Placeholder: returns '' (compile on the server)
  getMJML(): string;                      // Placeholder: returns '' (compile on the server)
  undo(): void;                           // Not implemented yet: use the toolbar or Cmd/Ctrl+Z
  redo(): void;                           // Not implemented yet: use the toolbar or Cmd/Ctrl+Shift+Z
  destroy(): void;                        // Unmounts the editor
}

import { createEditor } from '@marlinjai/email-editor';
import '@marlinjai/email-editor/styles.css';

const editor = createEditor({
  container: document.getElementById('editor'),
  initialValue: myTemplate,
  onChange: (template) => {
    console.log('Changed:', template);
  },
  theme: { colors: { primary: '#0f766e' } },
});

// Latest document, to send to your server for compilation
const doc = editor.getValue();

// Clean up
editor.destroy();

interface EmailEditorReactProps {
  initialTemplate?: TemplateSnapshotIn;                 // Document to open; omit for an empty email
  onChange?: (template: TemplateSnapshotOut) => void;   // Whole document after edits, debounced by 300 ms
  onSave?: () => void;                                  // Shows a Save button in the toolbar
  onExport?: (template: TemplateSnapshotOut) => void;   // Shows an Export button; compile on your server
  onNavigateBack?: () => void;                          // Shows a back arrow in the toolbar
  onRequestImage?: OnRequestImage;                      // Your image picker, see below
  blocks?: BlockDefinition[];                           // Extra block types next to the standard ones
  theme?: EditorTheme;                                  // Brand colors and font of the editor chrome
}

'use client';

import { useState } from 'react';
import { EmailEditorReact, type TemplateSnapshotOut } from '@marlinjai/email-editor/react';
import '@marlinjai/email-editor/styles.css';

function Composer({ initial }: { initial?: TemplateSnapshotOut }) {
  const [doc, setDoc] = useState(initial);

  // The editor fills its container, so the container needs a height.
  return (
    <div style={{ height: '80vh' }}>
      <EmailEditorReact
        initialTemplate={initial}
        onChange={setDoc}
        theme={customTheme}
        onSave={() => handleSave(doc)}
      />
    </div>
  );
}

type OnRequestImage = (request: ImageRequest) => Promise<RequestedImage | null>;

interface ImageRequest {
  blockId: string;       // The block the image is for
  blockType: string;     // The block type asking (today always 'image')
  currentUrl?: string;
  currentAlt?: string;
}

interface RequestedImage {
  url: string;           // Must be publicly reachable by recipients' mail clients
  alt?: string;
}

interface EmailTemplate {
  version: '1.0' | '1.1'; // migrateTemplate returns '1.1'
  metadata: TemplateMetadata;
  sections: Array<Section | Wrapper>; // the top level, in order
}

interface TemplateMetadata {
  subject?: string;
  previewText?: string;
  title?: string;
  createdAt?: string;
  updatedAt?: string;
  fonts?: FontDefinition[];
  themeColors?: ThemeColor[];
  breakpoint?: string;
  customCSS?: string;
  inlineCSS?: string;
}

interface Section {
  id: string;
  type: 'section';
  backgroundColor?: string;
  backgroundImage?: string;
  backgroundPosition?: string;
  backgroundRepeat?: 'repeat' | 'no-repeat';
  backgroundSize?: string;
  fullWidth?: boolean;
  noStack?: boolean;
  hidden?: boolean;
  padding?: Spacing;
  columns: Column[];
}

interface Wrapper {
  id: string;
  type: 'wrapper';
  hidden?: boolean;
  backgroundColor?: string;
  backgroundImage?: string; // background-url
  backgroundGradient?: BackgroundGradient;
  backgroundPosition?: string;
  backgroundRepeat?: 'repeat' | 'no-repeat';
  backgroundSize?: string;
  border?: string; // all four sides
  borderTop?: string;
  borderRight?: string;
  borderBottom?: string;
  borderLeft?: string;
  borderRadius?: string;
  padding?: Spacing; // MJML's default when unset: 20px 0
  fullWidth?: boolean;
  cssClass?: string;
  gap?: string; // px, between the sections inside
  textAlign?: 'left' | 'center' | 'right';
  extraAttributes?: Record<string, string>;
  sections: Section[];
}

interface Column {
  id: string;
  width?: number; // Percentage
  blocks: Block[];
  hidden?: boolean;
  backgroundColor?: string;
  verticalAlign?: 'top' | 'middle' | 'bottom';
  padding?: Spacing;
}

type Block =
  | TextBlock
  | ImageBlock
  | ButtonBlock
  | DividerBlock
  | SpacerBlock
  | HeaderBlock
  | FooterBlock
  | SocialBlock
  | HeroBlock
  | AccordionBlock
  | RawBlock
  | NavbarBlock
  | CarouselBlock
  | TableBlock;

interface TextBlock extends BaseBlock {
  type: 'text';
  content: string;       // HTML string from TipTap
  align?: 'left' | 'center' | 'right' | 'justify';
  color?: string;
  fontSize?: string;
  fontFamily?: string;
  padding?: Spacing;
  lineHeight?: string;
}

interface ImageBlock extends BaseBlock {
  type: 'image';
  src: string;
  alt?: string;
  width?: string;
  height?: string;
  align?: 'left' | 'center' | 'right';
  href?: string;
  padding?: Spacing;
  borderRadius?: string;
}

interface ButtonBlock extends BaseBlock {
  type: 'button';
  label: string;
  href: string;
  align?: 'left' | 'center' | 'right';
  backgroundColor?: string;
  color?: string;
  borderRadius?: string;
  border?: string;
  padding?: Spacing;
  innerPadding?: string;
}

interface SocialBlock extends BaseBlock {
  type: 'social';
  links: SocialLink[];
  iconSize?: string;
  iconPadding?: string;
  borderRadius?: string;
  align?: 'left' | 'center' | 'right';
  mode?: 'horizontal' | 'vertical';
}

interface HeroBlock extends BaseBlock {
  type: 'hero';
  backgroundImage: string;
  backgroundHeight?: string;
  backgroundWidth?: string;
  backgroundColor?: string;
  verticalAlign?: 'top' | 'middle' | 'bottom';
  mode?: 'fixed-height' | 'fluid-height';
}

interface AccordionBlock extends BaseBlock {
  type: 'accordion';
  items: AccordionItem[];
  iconPosition?: 'left' | 'right';
  borderColor?: string;
  fontFamily?: string;
}

interface NavbarBlock extends BaseBlock {
  type: 'navbar';
  links: NavbarLink[];
  hamburger?: boolean;
  baseUrl?: string;
  align?: 'left' | 'center' | 'right';
  icoColor?: string;
  padding?: Spacing;
}

interface CarouselBlock extends BaseBlock {
  type: 'carousel';
  images: CarouselImage[];
  thumbnails?: 'visible' | 'hidden';
  borderRadius?: string;
  iconWidth?: string;
  tbBorderRadius?: string;
  padding?: Spacing;
}

interface TableBlock extends BaseBlock {
  type: 'table';
  headers: string[];
  rows: string[][];
  align?: 'left' | 'center' | 'right';
  color?: string;
  fontFamily?: string;
  fontSize?: string;
  cellpadding?: string;
  cellspacing?: string;
  border?: string;
  padding?: Spacing;
}

interface DividerBlock extends BaseBlock {
  type: 'divider';
  borderColor?: string;
  borderWidth?: string;
  borderStyle?: 'solid' | 'dashed' | 'dotted';
  width?: string;
  padding?: Spacing;
}

interface SpacerBlock extends BaseBlock {
  type: 'spacer';
  height: string;
}

interface RawBlock extends BaseBlock {
  type: 'raw';
  html: string;
}

interface HeaderBlock extends BaseBlock {
  type: 'header';
  locked: true;
}

interface FooterBlock extends BaseBlock {
  type: 'footer';
  locked: true;
}

import { createStandardBlockRegistry } from '@marlinjai/email-editor-blocks';

const registry = createStandardBlockRegistry();

interface BlockDefinition<T extends Block = Block> {
  type: string;
  label: string;
  category: 'text' | 'media' | 'layout' | 'brand';
  icon?: string;
  description?: string;
  locked?: boolean;
  defaultProps: Omit<T, 'id' | 'type'>;
  propSchema: ZodType<Omit<T, 'id' | 'type'>>;
  toMJML: (block: T) => string;
}

import { createStandardPrebuiltRegistry } from '@marlinjai/email-editor-blocks';

const prebuiltRegistry = createStandardPrebuiltRegistry();

import { migrateTemplate, isTemplateMigrationError } from '@marlinjai/email-editor-core';

try {
  const doc = migrateTemplate(input);
} catch (error) {
  if (isTemplateMigrationError(error)) {
    console.error(error.code, error.message, error.issues);
  }
}

import { migrateTemplate } from '@marlinjai/email-editor-core';
import { createMJMLCompiler } from '@marlinjai/email-editor-core/server';

const compiler = createMJMLCompiler();
const result = await compiler.compile(migrateTemplate(template));

console.log(result.html);   // Compiled HTML
console.log(result.mjml);   // MJML source
console.log(result.errors); // Validation errors (if any)

import { MJMLExporter, createMJMLExporter } from '@marlinjai/email-editor-core/server';

const exporter = createMJMLExporter();
const { html, mjml, errors } = exporter.export(template);

import { createRootStore } from '@marlinjai/email-editor-core';

const store = createRootStore({
  template: myTemplate,
  onChange: (snapshot) => saveToDatabase(snapshot),
});

// Direct MST operations
store.template.addSection(sectionData);
store.template.findBlockById('block-1')?.updateStyle('color', 'red');

interface EditorTheme {
  colors?: {
    primary?: string;       // --ee-accent: primary buttons, selection, focus rings
    primaryHover?: string;  // --ee-accent-hover
    surface?: string;       // --ee-canvas-2: light panel surfaces
    text?: string;          // --ee-text-dark: text on light surfaces
    border?: string;        // --ee-border-light: borders on light surfaces
  };
  fonts?: {
    body?: string;          // --ee-font-sans: font stack of the editor chrome
  };
}