HiveWrite Email Editor SDK

A powerful, flexible, and easy-to-integrate drag-and-drop email builder for React or JavaScript applications. Create beautiful, responsive emails with a modern WYSIWYG editor.

✨ Features

• 📧 Drag & Drop Editor - Intuitive block-based email building
• 🎨 Rich Block Types - Text, images, buttons, videos, countdown timers, social icons, and more
• 📱 Mobile Preview - Real-time mobile (350px) and desktop preview modes
• 🌙 Dark/Light Theme - Built-in theme support
• 📤 HTML/MJML Export - Export responsive HTML emails compatible with all email clients
• 🎯 Merge Tags - Dynamic content placeholders for personalization
• 🖼️ Stock Images - Built-in Unsplash integration for stock photos
• 🏗️ Pre-built Templates - E-commerce, marketing, and transactional email templates
• � Saved Sections - Save and reuse custom block groups across templates
• �🔧 Fully Customizable - White-labeling, permissions, and branding options

📦 Installation

Via NPM

npm install hivewrite-sdk

Via CDN (Plain HTML/JS)

<script src="https://cdn.jsdelivr.net/npm/hivewrite-sdk@latest/bundle.min.js"></script>

🚀 Quick Start

React Integration

import React, { useEffect, useRef } from "react";
import { hivewrite } from "hivewrite-sdk";

const MyEditor = () => {
  const containerRef = useRef(null);

  useEffect(() => {
    if (containerRef.current) {
      hivewrite.init({
        apiKey: "your-api-key",
        container: containerRef.current,
        mode: "FULL_EDITOR",
        theme: "dark",
        locale: "en",
        callbacks: {
          onLoad: () => console.log("Editor ready"),
          onExport: (html) => console.log("HTML:", html),
        },
      });
    }
  }, []);

  return <div ref={containerRef} style={{ height: "100vh", width: "100%" }} />;
};

Plain JavaScript Integration

<div id="editor-container" style="height: 100vh;"></div>

<script src="https://cdn.jsdelivr.net/npm/hivewrite-sdk@latest/bundle.min.js"></script>
<script>
  hivewrite.init({
    apiKey: "your-api-key",
    container: "#editor-container",
    mode: "FULL_EDITOR",
    theme: "dark",
    locale: "en",
    callbacks: {
      onLoad: () => console.log("Editor ready"),
      onExport: (html) => console.log("HTML:", html),
    },
  });
</script>

📖 API Reference

hivewrite.init(config: SDKConfig)

Initializes and mounts the editor.

SDKConfig Parameters

| Parameter | Type | Required | Description | | :------------- | :---------------------- | :------- | :------------------------------------------------------------------------------------------------------ | | apiKey | string | Yes | Your HiveWrite API Key | | container | string \| HTMLElement | Yes | CSS selector or DOM element to mount the editor | | userId | string | No | Unique identifier for the current user | | mode | string | Yes | 'FULL_EDITOR', 'DESIGN_ONLY', 'READ_ONLY', 'HTML_IMPORT' | | theme | string | No | 'light' (default) or 'dark' | | locale | string | No | 'en' (default), 'es', or 'fr' | | branding | object | No | Custom white-labeling options (primaryColor, secondaryColor, accentColor, logoUrl, customCSS) | | permissions | object | No | Toggle features: export, aiMagic, uploadImages, hideSaveButton | | mergeTags | array | No | Array of { label, value } for dynamic content | | portalTarget | string | No | 'window' (default) or 'container'. Controls where dialogs render. | | callbacks | object | No | Event hooks for SDK actions |

🧱 Available Block Types

| Block | Description | | :--------------------------------- | :----------------------------------------------------------- | | text | Rich text paragraph | | heading1, heading2, heading3 | Heading elements | | image | Image with alt text, link, and styling | | button | CTA button with customizable colors and links | | divider | Horizontal line separator | | video | Video embed with poster image and play button | | timer | Countdown timer (static snapshot in email export) | | icon | Social/brand icons with shape options (circle, square, none) | | tiktok | TikTok video embed card | | twitter | X/Twitter post embed card | | bulletList, numberedList | List elements | | blockquote | Quote block | | columns2, columns3 | Multi-column layouts | | section | Single column container | | html | Custom HTML code block |

📤 Export Options

Export to HTML

const result = await hivewrite.export({
  format: "html",
  minify: true,
});
// Or use the shorthand
hivewrite.exportHtml((html) => console.log(html));

Export to JSON (Design)

const result = await hivewrite.export({ format: "json" });
console.log(result.design);

Export Features

• Responsive HTML - MJML-based output compatible with all email clients
• Inline CSS - Optional CSS inlining for maximum compatibility
• Minification - Reduce file size for production
• Static Snapshots - Countdown timers, videos, and embeds render as email-safe static content

🎨 Theming & Branding

Theme Modes

hivewrite.init({
  theme: "dark", // or 'light'
  // ...
});

// Switch theme at runtime
hivewrite.setTheme("light");

White Labeling

branding: {
  primaryColor: '#6366f1',      // Main accent color
  secondaryColor: '#8b5cf6',    // Secondary elements
  accentColor: '#ec4899',       // Highlights and focus
  logoUrl: 'https://yoursite.com/logo.png',
  customCSS: '.my-class { color: red; }'
}

🔐 Permissions

Control what features are available:

permissions: {
  export: true,           // Allow HTML export
  aiMagic: true,          // Enable AI features
  uploadImages: false,    // Disable uploads (stock images only)
  hideSaveButton: true    // Hide the built-in save button
}

🏷️ Merge Tags

Add dynamic content placeholders:

mergeTags: [
  { label: "First Name", value: "{{first_name}}" },
  { label: "Company", value: "{{company}}" },
  { label: "Unsubscribe Link", value: "{{unsubscribe_url}}" },
];

📞 Callbacks

| Callback | Arguments | Description | | :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------ | | onLoad | () | Editor fully initialized | | onExport | (html: string, userId?: string) | Triggered on HTML export | | onSave | (json: {blocks: any[], canvasSettings: CanvasSettings, name: string, description: string, category: string}, userId?: string) | Triggered on design save | | onError | (err: any, userId?: string) | Initialization or processing error | | onTemplateChange | (templateId: string, userId?: string) | Template selection changed | | onImageUpload | (file: File, userId?: string) | Async. Handle image uploads, return URL |

Image Upload Example

callbacks: {
  onImageUpload: async (file, userId) => {
    const formData = new FormData();
    formData.append("image", file);
    if (userId) formData.append("userId", userId);
    const res = await fetch("/api/upload", { method: "POST", body: formData });
    const data = await res.json();
    return data.url; // Return the uploaded image URL
  };
}

Response Examples

hivewrite.save()

Triggers the onSave callback with the current design state.

hivewrite.save();

// Result sent to onSave(json, userId):
{
  "body": {
    "blocks": [ ... ]       // Array of block objects
  },
  "canvasSettings": { ... }, // Canvas styles (width, background, etc)
  "name": "My Email Template",
  "description": "Here will be the description",
  "category": "marketing"
}

onExport(html, userId)

The html argument is a string containing the final generated HTML.

// Example usage
onExport: (html, userId) => {
  console.log(`Exported for user ${userId}`);
  saveToDatabase(html);
};

🏗️ Design JSON Format

The loadDesign(data) method and onSave callback use a specific JSON structure.

data Object

| Property | Type | Description | | :--------------- | :--------------- | :-------------------------------- | | blocks | EditorBlock[] | Array of content blocks | | canvasSettings | CanvasSettings | Global editor styles and branding |

JSON Example

{
  "blocks": [
    {
      "id": "os-UuWl9Cx32T7OYMdmRO",
      "type": "text",
      "content": {
        "text": "<a href=\"#\" style=\"color:#666;text-decoration:none;\">View in browser</a>"
      },
      "styles": {
        "textAlign": "center",
        "fontSize": "12px",
        "color": "#666",
        "padding": "10px",
        "backgroundColor": "#FFFFFF"
      }
    },
    {
      "id": "II1rUSyoqXnn9qTqQp54h",
      "type": "image",
      "content": {
        "src": "https://images.unsplash.com/photo-1504674900247-0877df9cc836?q=80&w=800&auto=format&fit=crop"
      },
      "styles": {
        "width": "100%",
        "height": "300px",
        "objectFit": "cover"
      }
    }
  ],
  "canvasSettings": {
    "backgroundColor": "#ffffff",
    "outerBackgroundColor": "#ffffff",
    "width": "100%",
    "maxWidth": "600px",
    "fontFamily": "Inter, sans-serif",
    "padding": "32px",
    "spacing": 16,
    "branding": {
      "primary": "#000000",
      "secondary": "#4b5563",
      "accent": "#2563eb"
    }
  },
  "templateSettings": {
    "name": "My Template",
    "category": "Marketing",
    "thumbnail": "https://example.com/template-thumbnail.jpg",
    "description": "A marketing email template"
  }
}

📱 Mobile Preview

The editor includes a mobile preview mode (350px width) with automatic scaling:

• Font sizes scale proportionally
• Images adapt to container width
• Spacing adjusts for mobile screens

Toggle between desktop and mobile using the view mode controls in the toolbar.

📧 Email Client Compatibility

Exported HTML is fully compatible with:

• Gmail (Web, iOS, Android)
• Apple Mail
• Outlook (Desktop, Web, Mobile)
• Yahoo Mail
• Samsung Mail
• And many more...

Note: Some features like videos and iframes are rendered as static fallbacks since email clients don't support embedded media.

🛠️ Methods

| Method | Description | | :---------------------------- | :------------------------------------------- | | init(config) | Initialize the editor | | loadDesign(data) | Load a previously saved JSON design | | export({ format, minify? }) | Export design to HTML, JSON, or MJML | | exportHtml(callback) | Shorthand for HTML export | | exportJson(callback) | Shorthand for JSON export | | exportMjml(callback) | Shorthand for MJML export | | save() | Triggers onSave callback with current JSON | | setTheme(theme) | Switch theme at runtime | | setLocale(locale) | Switch locale at runtime | | destroy() | Unmount and cleanup |

📄 License

MIT © Babber Maven

Created & Maintained by Shahzad Siddique