# strapi-plugin-easyemail

Drag-and-drop MJML email designer for **Strapi v5**, powered by [EasyEmail Pro](https://www.easyemail.pro/).

Design responsive emails inside the Strapi admin panel. The plugin stores the editor state (`designJson`) and compiled HTML (`htmlBody`), and provides a server-side API that renders templates with [LiquidJS](https://liquidjs.com/) variables.

## Features

- Visual drag-and-drop editor (MJML-based, mobile-responsive)
- Template CRUD with design JSON + compiled HTML storage
- Liquid template variables (`{{ user.name }}`, `{% for %}`, `{% if %}`, etc.)
- Send test emails directly from the editor (no save required)
- Starter template library with bundled examples
- CSS-isolated editor (iframe) — no style conflicts with Strapi admin
- Optional send APIs can use the email provider already configured in your Strapi app

## Install

```bash
# npm
npm install strapi-plugin-easyemail

# yarn
yarn add strapi-plugin-easyemail

# pnpm
pnpm add strapi-plugin-easyemail
```

Enable the plugin in your Strapi project:

```ts
// config/plugins.ts
export default ({ env }) => ({
  easyemail: {
    enabled: true,
    config: {
      editor: {
        showSourceCode: true,
        showPreview: true,
        showSidebar: true,
        showLayer: true,
        showDragMoveIcon: true,
        showInsertTips: true,
        compact: false,
        enabledAutoComplete: true,
      },
    },
  },
});
```

### EasyEmail Pro Client ID (optional)

The plugin uses `STRAPI_FREE` by default. If you have an EasyEmail Pro paid plan, override it with your client ID:

```bash
STRAPI_ADMIN_EASYEMAIL_PRO_CLIENT_ID=<your-client-id>
```

## Usage

### Admin Panel

After installation, a new **EasyEmail** menu item appears in the Strapi sidebar. From there you can:

1. **Create** a new email template (blank or from a starter)
2. **Edit** with the visual drag-and-drop editor
3. **Send Test** to preview the email in a real inbox
4. **Save** to persist design JSON and compiled HTML

Image uploads inside the editor use Strapi's built-in Upload plugin. Uploaded images are stored in the Media Library, and the editor inserts the returned asset URL into the email design.

### Editor Configuration

You can pass serializable EasyEmail editor options through the plugin config:

```ts
// config/plugins.ts
export default () => ({
  easyemail: {
    enabled: true,
    config: {
      editor: {
        showSourceCode: false,
        showPreview: true,
        compact: false,
        enabledAutoComplete: true,
        unsplash: {
          clientId: 'your-unsplash-client-id',
        },
      },
    },
  },
});
```

These options are merged into `Retro.useCreateConfig`. Runtime values such as `clientId`, `height`, `initialValues`, `onUpload`, `onSubmit`, and the default block categories are managed by the plugin.

### Sending Emails Programmatically

```ts
// Send an email using a saved template
await strapi
  .plugin('easyemail')
  .service('emailSender')
  .sendEmail(
    'template-document-id',   // Strapi documentId
    'user@example.com',        // recipient (string or string[])
    {                          // Liquid template variables
      user: { name: 'Ryan' },
      company: 'Acme',
      resetLink: 'https://...',
    }
  );
```

### Render Without Sending (preview)

```ts
const { subject, html, text } = await strapi
  .plugin('easyemail')
  .service('emailSender')
  .renderTemplate('template-document-id', {
    user: { name: 'Ryan' },
  });
```

### Liquid Template Syntax

The `subject` and `htmlBody` fields support full [LiquidJS](https://liquidjs.com/) syntax:

```
Hello {{ user.name }},
```

### Replacing Strapi Built-in Emails

You can use this plugin to replace Strapi's built-in emails (password reset, email confirmation, etc.) by overriding the Users & Permissions plugin in your project:

```ts
// src/extensions/users-permissions/strapi-server.ts
export default (plugin) => {
  const originalForgotPassword = plugin.controllers.auth.forgotPassword;

  plugin.controllers.auth.forgotPassword = async (ctx) => {
    // your logic to get user and generate reset URL...

    await strapi
      .plugin('easyemail')
      .service('emailSender')
      .sendEmail('your-reset-template-id', user.email, {
        user: { name: user.username },
        resetLink: resetUrl,
      });

    ctx.send({ ok: true });
  };

  return plugin;
};
```

## Admin REST API

All routes require admin authentication and are prefixed with `/easyemail/`.

### Templates

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/templates` | List all templates |
| `GET` | `/templates/:id` | Get a single template |
| `POST` | `/templates` | Create a template |
| `PUT` | `/templates/:id` | Update a template |
| `DELETE` | `/templates/:id` | Delete a template |
| `POST` | `/templates/:id/send` | Render with Liquid variables and send |

#### Send a template

```bash
POST /easyemail/templates/:id/send
Content-Type: application/json

{
  "data": {
    "to": "user@example.com",
    "data": { "user": { "name": "Ryan" } },
    "from": "noreply@example.com",
    "cc": "manager@example.com",
    "bcc": "log@example.com",
    "replyTo": "support@example.com"
  }
}
```

### Send Test (raw HTML)

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/send-test` | Send raw HTML email without saving a template |

```bash
POST /easyemail/send-test
Content-Type: application/json

{
  "data": {
    "to": "test@example.com",
    "subject": "Test email",
    "html": "<html>...</html>"
  }
}
```

### Starter Templates

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/starters` | List bundled starter templates |
| `GET` | `/starters/:id` | Get a bundled starter template |

## Sending Emails

Designing and saving templates does not require any external email platform.

The optional **Send Test** button and send APIs use Strapi's email plugin. If your Strapi app already has an email provider configured, EasyEmail will use that existing configuration. If no email provider is configured, you can still create, edit, save, and render templates, but sending emails will fail until Strapi email is configured.

See Strapi's email plugin documentation for provider setup.

## Package Verification

```bash
pnpm run build
pnpm run verify   # validates package for Strapi Marketplace
```

## License

MIT