EmailBuilder.js Editor Sample

A customizable React email template editor component built on top of the powerful EmailBuilder.js framework by Waypoint. This is a sample application demonstrating the editor's capabilities.

Features

• 🎨 Drag & Drop Interface - Intuitive visual editor for creating email templates
• 📱 Responsive Preview - Desktop and mobile preview modes
• 🔧 Customizable - Theme, styling, and configuration options
• ☁️ Cloud Storage - S3-compatible storage for saving/loading templates
• 📧 Email Testing - Send test emails directly from the editor
• 🧪 Test Data - Variable templating with preview mode
• 🎯 Block System - Rich set of pre-built email components
• 📦 Export Options - JSON and HTML export capabilities

Installation

npm install

Basic Usage

The editor works with a Node.js backend for S3 storage and email functionality:

import React from "react";
import EmailEditor from "./src/EmailEditor";

function App() {
  return (
    <EmailEditor
      cloudServiceConfiguration={{
        accessKeyId: "your-access-key",
        secretAccessKey: "your-secret-key",
        endpoint: "https://s3.amazonaws.com",
        bucket: "your-bucket-name",
        region: "us-east-1",
      }}
      emailConfiguration={{
        smtpHost: "smtp.gmail.com",
        smtpPort: 587,
        secure: false,
        username: "[email protected]",
        password: "your-app-password",
        fromEmail: "[email protected]",
        fromName: "Your Company",
      }}
      onSave={(templateName, document) => {
        console.log("Template saved:", templateName);
      }}
    />
  );
}

Configuration Options

EmailEditorProps

| Prop | Type | Required | Description | | --------------------------- | ----------------------------------- | -------- | ----------------------------------------------- | | apiBaseUrl | string | No | Backend API URL (e.g., 'http://localhost:5000') | | cloudServiceConfiguration | S3Configuration | No | ⚠️ Deprecated: Use backend API instead | | emailConfiguration | EmailConfiguration | No | ⚠️ Deprecated: Use backend API instead | | theme | Theme | No | Custom Material-UI theme | | styleConfiguration | StyleConfiguration | No | Simple style customization | | initialDocument | any | No | Initial template/document to load | | onSave | (name: string, doc: any) => void | No | Callback when template is saved | | onLoad | (name: string) => void | No | Callback when template is loaded | | onSendTest | (email: string, doc: any) => void | No | Callback when test email is sent | | showSamplesDrawer | boolean | No | Show samples drawer (default: true) | | showInspectorDrawer | boolean | No | Show inspector drawer (default: true) | | enableCloudStorage | boolean | No | Enable S3 features (default: true) | | enableEmailSending | boolean | No | Enable email features (default: true) |

S3Configuration

interface S3Configuration {
  accessKeyId: string;
  secretAccessKey: string;
  endpoint: string; // e.g., 'https://s3.amazonaws.com'
  bucket: string;
  region?: string; // default: 'us-east-1'
}

EmailConfiguration

interface EmailConfiguration {
  smtpHost: string; // e.g., 'smtp.gmail.com'
  smtpPort: number; // e.g., 587
  secure: boolean; // Use TLS
  username: string;
  password: string; // For Gmail, use App Password
  fromEmail: string;
  fromName?: string;
}

Advanced Usage

Backend API Configuration

The apiBaseUrl prop allows you to point the editor to any backend API endpoint:

Development:

<EmailEditor apiBaseUrl="http://localhost:5000" />

Production:

<EmailEditor apiBaseUrl="https://api.yourcompany.com" />

Environment-based:

const API_URL = process.env.REACT_APP_API_URL || "http://localhost:5000";

<EmailEditor apiBaseUrl={API_URL} />;

Multiple environments:

const getApiUrl = () => {
  switch (process.env.NODE_ENV) {
    case "production":
      return "https://api.production.com";
    case "staging":
      return "https://api.staging.com";
    default:
      return "http://localhost:5000";
  }
};

<EmailEditor apiBaseUrl={getApiUrl()} />;

Setting Up the .NET Backend

1. Install the NuGet package (see sf9-email-editor folder):

   dotnet add package SF9.EmailEditor

2. Configure in Program.cs:

   builder.Services.AddEmailEditor(builder.Configuration);

3. Configure appsettings.json:

   {
     "EmailEditor": {
       "S3": {
         "AccessKey": "your-key",
         "SecretKey": "your-secret",
         "BucketName": "templates",
         "Region": "us-east-1"
       },
       "Email": {
         "Provider": "SendGrid",
         "SendGrid": {
           "ApiKey": "your-sendgrid-api-key",
           "FromEmail": "[email protected]"
         }
       }
     }
   }
   `nst handleLoad = (templateName: string) => {
    console.log(`Template "${templateName}" loaded`);

};

const handleSendTest = (recipientEmail: string, document: any) => { // Track test email sends console.log(Test email sent to ${recipientEmail}); };

return ( ); }

### Initial Template

```tsx
import EmailEditor from "sf9-email-editor";
import welcomeTemplate from "./templates/welcome";

function App() {
  return (
    <EmailEditor
      apiBaseUrl="http://localhost:5000"
      initialDocument={welcomeTemplate}
    />
  );
}

Standalone Editor (No Backend)

If you want to use the editor without backend features:

<EmailEditor enableCloudStorage={false} enableEmailSending={false} />

Development

Running with .NET Backend (Recommended)

1. Start the .NET API:

   cd sf9-email-editor/Example
   dotnet run

./src/EmailEditor";

const customTheme = createTheme({ palette: { primary: { main: "#1976d2", }, secondary: { main: "#dc004e", }, }, });

function App() { return ; }

### With Callbacks

```tsx
import EmailEditor from "./src/EmailE
npm install
npm run dev:full  # Runs backend (port 3001) and frontend (port 5173)

Or run separately:

npm run server    # Backend API on http://localhost:3001
npm run dev       # Frontend on http://localhost:5173

Building

Build the library for npm publishing:

npm run build:lib

This gonSave={handleSave} onLoad={handleLoad} onSendTest={handleSendTest} /> ); }

### Initial Template

```tsx
import EmailEditor from "./src/EmailE
- ✅ Better performance
- ✅ Type-safe configuration
- ✅ Production-ready with comprehensive error handling
- ✅ Supports SendGrid and Resend for email delivery
- ✅ Native dependency injection
- ✅ Full documentation in `sf9-email-editor` folder
initialDocument={welcomeTemplate}
    />
  );
}

Development

To run the editor with smtpHost: 'smtp.mail.yahoo.com', smtpPort: 465, secure: true, username: '[email protected]', password: 'your-app-password', fromEmail: '[email protected]', }}

## S3-Compatible Storage

This package supports AWS S3 and any S3-compatible storage service (DigitalOcean Spaces, MinIO, Wasabi, etc.).

**Note:** When using the .NET backend, S3 configuration is done server-side in `appsettings.json`. The frontend only needs the `apiBaseUrl`.

**Legacy Node.js approach:**

```tsx
// DigitalOcean Spaces example
cloudServiceConfiguration={{
  accessKeyId: 'your-key',
  secretAccessKey: 'your-secret',
  endpoint: 'https://nyc3.digitaloceanspaces.com',
  bucket: 'your-space-name',
  region: 'us-east-1',
}}

Migration Guide

Migrating from Node.js to .NET Backend

Before:

<EmailEditor
  cloudServiceConfiguration={{
    accessKeyId: "key",
    secretAccessKey: "secret",
    endpoint: "https://s3.amazonaws.com",
    bucket: "templates",
  }}
  emailConfiguration={{
    smtpHost: "smtp.gmail.com",
    smtpPort: 587,
    secure: false,
    username: "[email protected]",
    password: "password",
    fromEmail: "[email protected]",
  }}
/>

After:

// Frontend - much simpler!
<EmailEditor apiBaseUrl="http://localhost:5000" />

// Backend - appsettings.json
{
- `GET /api/email-template/{name}` - Get template by name
- `POST /api/email-template/{name}` - Save/update template
- `DELETE /api/email-template/{name}` - Delete template

### Email Operations (.NET only)

- `POST /api/email-template/send` - Send test email with template

### Email Operations (Node.js)

- `POST /api/email/verify` - Verify SMTP connection
- `POST /api/email/send` - Send test email

## Troubleshooting

### Cannot connect to API server

**Error:** `Cannot connect to API server. Please ensure the .NET API is running on http://localhost:5000`

**Solution:**

1. Check if the backend is running: `dotnet run` (in Example folder)
2. Verify the port matches your `apiBaseUrl` prop
3. Check CORS is configured correctly in the backend

### Templates not loading

**Solution:**

1. Verify S3 credentials in `appsettings.json`
2. Check S3 bucket exists and is accessible
3. Ensure bucket permissions allow read/write operations

### Email sending fails

**Solution:**

1. For SendGrid: Verify API key is valid
2. For Resend: Verify API key is valid
3. Check the "From" email is verified with your provider
4. Review backend logs for specific error messages

## License

MIT

## Credits

Built on top of [EmailBuilder.js](https://usewaypoint.com) by Waypoint.

## Related Documentation

- [SF9.EmailEditor NuGet Package Documentation](sf9-email-editor/README.md) - Complete .NET backend documentation
- [API Reference](sf9-email-editor/API-REFERENCE.md) - Detailed API documentation
- [Migration Guide](sf9-email-editor/MIGRATION-GUIDE.md) - Detailed migration from Node.js to .NET
Templates not loading

**Solution:**

1. Verify S3 credentials are configured correctly
2. Check S3 bucket exists and is accessible
3. Ensure bucket permissions allow read/write operations

### Email sending fails

**Solution:**

1. Verify SMTP credentials are correct
2. Check the "From" email is valid
3. For Gmail, use App Passwords instead of account password
4. Review server