EEmail Editor

Getting Started with @returnhypnosis/email-editor

Installation

npm install @returnhypnosis/email-editor

Quick Start

React Integration

import { EmailEditorReact } from '@returnhypnosis/email-editor/react';
import '@returnhypnosis/email-editor/styles.css';
import { useState } from 'react';

function App() {
  const [template, setTemplate] = useState({
    version: '1.0',
    metadata: { subject: 'My Email' },
    sections: [],
  });

  return (
    <EmailEditorReact
      value={template}
      onChange={setTemplate}
      onSave={() => console.log('Saved!', template)}
    />
  );
}

Vanilla JavaScript

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

const editor = createEditor({
  container: document.getElementById('editor'),
  initialValue: {
    version: '1.0',
    metadata: { subject: 'My Email' },
    sections: [],
  },
  onChange: (template) => {
    console.log('Template changed:', template);
  },
});

// Get compiled HTML
const html = editor.getHTML();

// Clean up
editor.destroy();

Core Concepts

EmailTemplate Structure

interface EmailTemplate {
  version: '1.0';
  metadata: {
    subject?: string;
    previewText?: string;
  };
  sections: Section[];
}

Adding Blocks

Drag blocks from the left toolbar onto the canvas. Available blocks:

  • Text - Rich text with formatting
  • Image - Images with optional links
  • Button - Call-to-action buttons
  • Divider - Horizontal lines
  • Spacer - Vertical spacing
  • ReTurn Header - Branded header (locked)
  • ReTurn Footer - Branded footer (locked)

Editing Properties

Click any block to select it. The right panel shows editable properties like colors, alignment, and text.

Undo/Redo

  • Cmd+Z (Mac) or Ctrl+Z (Windows) - Undo
  • Cmd+Shift+Z or Ctrl+Shift+Z - Redo

Device Preview

Toggle between desktop and mobile views using the icons in the canvas toolbar.

Theming

Customize the editor's appearance:

const theme = {
  colors: {
    primary: '#944923',
    surface: '#ffffff',
    text: '#1a1a1a',
    border: '#e5e5e5',
  },
  fonts: {
    heading: 'Georgia, serif',
    body: 'Georgia, serif',
  },
};

<EmailEditorReact theme={theme} ... />

Server-Side Compilation

For production use, compile MJML on the server:

// API route (Next.js example)
import { createMJMLCompiler } from '@returnhypnosis/email-editor-core';

export async function POST(request) {
  const template = await request.json();
  const compiler = createMJMLCompiler();
  const { html, mjml } = compiler.compile(template);

  return Response.json({ html, mjml });
}

Custom Blocks

Register your own custom blocks:

import { createEditor } from '@returnhypnosis/email-editor';

const customBlock = {
  type: 'custom',
  label: 'Custom Block',
  category: 'text',
  defaultProps: { content: 'Hello' },
  propSchema: z.object({ content: z.string() }),
  toMJML: (block) => `<mj-text>${block.content}</mj-text>`,
};

const editor = createEditor({
  container: document.getElementById('editor'),
  blocks: [customBlock],
});

Next Steps