strapi-plugin-magic-mail 3.1.0 → 4.0.0

package/README.md

@@ -1,1454 +1,930 @@
-# 📧 MagicMail - Email Business Suite for Strapi v5
+# MagicMail: email accounts, routing and templates for Strapi 5
 
 Project site: https://schero94.github.io/Magic-Mail/
 
-> Manage email accounts, routing rules, OAuth setup, and delivery in Strapi. The plugin is MIT-licensed and open source.
-
 [![NPM Version](https://img.shields.io/npm/v/strapi-plugin-magic-mail.svg)](https://www.npmjs.com/package/strapi-plugin-magic-mail)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Strapi Version](https://img.shields.io/badge/Strapi-v5.57.0-blue.svg)](https://strapi.io)
+[![Strapi Version](<https://img.shields.io/badge/Strapi-5.57%2B%20(tested%205.61)-blue.svg>)](https://strapi.io)
 
-> The plugin does not require a license key or paid plan.
+MagicMail adds a mail desk to the Strapi admin. You connect one or more sending accounts (Gmail, Microsoft 365, Yahoo, any SMTP server, SendGrid or Mailgun), decide with routing rules which account sends which email, design templates, and see what was delivered, opened and clicked.
 
----
+It plugs into the Strapi email service you already use. Code that calls `strapi.plugin('email').service('email').send()`, Strapi's own password-reset mail and every Users & Permissions mail go through MagicMail without changes.
+
+MagicMail sends **email only**. It is MIT-licensed, has no license key, tiers or usage limits.
 
-## 🌟 Why MagicMail?
+**At a glance**
 
-**Stop fighting with .env files and email configuration!** MagicMail brings professional email management to Strapi v5 with:
+- 6 providers: Gmail, Microsoft 365 and Yahoo with OAuth 2.0, SMTP (optional DKIM), SendGrid, Mailgun
+- Routing rules by email type, recipient, subject, template or a custom value, with a fallback account
+- Hourly and daily quotas per account, reserved atomically, with safe failover
+- Template designer: visual editor (Unlayer) or plain HTML/text, Mustache variables, versions, import/export
+- Delivery log with privacy-friendly open and click tracking and configurable retention
+- Credentials encrypted with AES-256-GCM; secrets never reach the browser
+- Admin UI in English, German, French, Spanish and Portuguese, light and dark mode
 
-- **100% Free & Open Source** - Every feature included, no license key, tiers, or limits (MIT)
-- **7 Email Providers** - Gmail, Microsoft 365, Yahoo, SMTP, SendGrid, Mailgun, Nodemailer
-- **OAuth 2.0 Authentication** - No passwords needed for Gmail, Microsoft, Yahoo
-- **Smart Routing Rules** - Route emails by type, recipient, subject, or custom conditions
-- **Automatic Failover** - Never lose an email when rate limits hit
-- **Beautiful Admin UI** - Manage everything from Strapi Admin Panel
-- **Zero Configuration** - No .env files, everything in the database
-- **Email Designer Compatible** - Works seamlessly with strapi-plugin-email-designer-5
-- **GDPR/CAN-SPAM Compliant** - Built-in List-Unsubscribe headers
-- **Professional Security** - TLS 1.2+, DKIM, SPF, DMARC validation
+## Contents
+
+- [Screenshots](#screenshots)
+- [Quick start](#quick-start)
+- [Sending email](#sending-email)
+- [Provider setup](#provider-setup)
+- [Routing rules and quotas](#routing-rules-and-quotas)
+- [Templates and the visual editor](#templates-and-the-visual-editor)
+- [Tracking, privacy and retention](#tracking-privacy-and-retention)
+- [Content API](#content-api)
+- [Admin API](#admin-api)
+- [Permissions](#permissions)
+- [Configuration reference](#configuration-reference)
+- [Troubleshooting](#troubleshooting)
+- [Upgrading to 4.0.0](#upgrading-to-400)
+- [Development](#development)
 
 ---
 
-## 📸 Screenshots
+## Screenshots
 
-### Email Accounts Dashboard
-![Email Accounts Dashboard](pics/EmailAccountDashboard.png)
-*Manage unlimited email accounts with live stats and real-time monitoring*
+The screenshots show synthetic demo data (`example.test` addresses) on Strapi 5.61.
 
-### Add Email Account - Step 1
-![Add Account Step 1](pics/Emailaddccount1.png)
-*Choose from 6 different email providers with OAuth 2.0 support*
+### Email accounts
 
-### Add Email Account - Step 2
-![Add Account Step 2](pics/emailaddaccount2.png)
-*Configure SMTP settings or connect with OAuth*
+![Email accounts list with usage, quotas and actions](https://raw.githubusercontent.com/Schero94/Magic-Mail/main/pics/EmailAccountDashboard.png)
+_Accounts with status, provider, priority, today's usage against the daily limit, and test/edit/delete actions._
 
-### Add Email Account - Step 3
-![Add Account Step 3](pics/emailaddaccount3.png)
-*Complete setup with rate limits and test connection*
+### Account wizard
 
-### Email Templates
-![Email Templates](pics/Templates.png)
-*Create and manage email templates with the visual designer*
+![Add email account wizard, provider step](https://raw.githubusercontent.com/Schero94/Magic-Mail/main/pics/Emailaddccount1.png)
+_Four steps: provider, details, credentials, settings. OAuth providers connect in a popup._
 
-### Email Designer
-![Email Designer](pics/emailDesigner.png)
-*Drag-and-drop email editor with real-time preview*
+### Routing rules
 
-### Template Version History
-![Version History](pics/emailVersionHistory.png)
-*Track changes and restore previous template versions*
+![Routing rules list in evaluation order](https://raw.githubusercontent.com/Schero94/Magic-Mail/main/pics/RoutingEmailTemplates.png)
+_Rules in evaluation order. Rules that point to a missing or inactive account are flagged._
 
-### Template Send Test
-![Send Test](pics/emailTemplateSendTest.png)
-*Test your templates before sending to production*
+### Templates
 
-### Routing Rules & Templates
-![Routing Rules](pics/RoutingEmailTemplates.png)
-*Define intelligent routing rules based on email type, recipient, subject*
+![Template list with categories, status and actions](https://raw.githubusercontent.com/Schero94/Magic-Mail/main/pics/Templates.png)
+_Templates with Reference ID, category and status; edit, download as HTML or JSON, duplicate, code snippets, test send and delete._
 
-### Email Analytics
-![Email Analytics](pics/emailAnalytics.png)
-*Track email performance with detailed analytics and statistics*
+### Template editor
 
-### Code Integration
-![Code Snippet](pics/codesnippet.png)
-*Simple API integration with your Strapi application*
+![Template editor with the visual designer](https://raw.githubusercontent.com/Schero94/Magic-Mail/main/pics/emailDesigner.png)
+_Template editor. For this screenshot the Unlayer canvas was replaced by a local stand-in, so no request went to Unlayer; the real editor looks different inside the canvas._
 
----
+### Analytics
 
-## Messaging migration
+![Analytics with totals and the delivery log](https://raw.githubusercontent.com/Schero94/Magic-Mail/main/pics/emailAnalytics.png)
+_Totals, delivery log with server-side search, opens and clicks per email._
 
-Magic-Mail now handles email only. Install and configure the separate Magic-WhatsApp plugin for WhatsApp transport, connection state, templates, and message actions. Magic-Mail does not proxy its old routes to another plugin.
+### Plugin settings
 
-The `/api/magic-mail/send` endpoint is unchanged. `/api/magic-mail/send-message` still sends email and accepts `channel: "email"` or `channel: "auto"` when `to` contains the recipient address. The old `/send-whatsapp` and `/whatsapp/*` routes are removed. The `email-router` service no longer exposes WhatsApp methods, and email routing rules no longer offer WhatsApp fallback.
+![Plugin settings for tracking and unsubscribe headers](https://raw.githubusercontent.com/Schero94/Magic-Mail/main/pics/pluginSettings.png)
+_Settings → MagicMail → Plugin Settings: link and open tracking, tracking base URL, unsubscribe header, default sender name._
 
-Magic-Mail does not delete or import old local session files, stored templates, or settings. The two legacy routing-rule columns remain in Strapi's schema so schema synchronization does not drop their saved values. The plugin no longer reads or updates those fields. Back up existing session data securely and migrate it only by following the separate Magic-WhatsApp plugin's instructions.
+### Dark mode and mobile
+
+![Analytics in dark mode](https://raw.githubusercontent.com/Schero94/Magic-Mail/main/pics/emailAnalyticsDark.png)
+
+| Accounts at 390 px                                                                                         | Routing rules at 390 px                                                                                             |
+| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| ![Accounts on a phone](https://raw.githubusercontent.com/Schero94/Magic-Mail/main/pics/mobileAccounts.png) | ![Routing rules on a phone](https://raw.githubusercontent.com/Schero94/Magic-Mail/main/pics/mobileRoutingRules.png) |
 
 ---
 
-## Quick Start
+## Quick start
+
+### Requirements
 
-### Installation
+- Node.js `>=22.12.0 <=26.x.x`
+- Strapi `^5.57.0` (developed and tested against 5.61)
+- `@strapi/plugin-users-permissions` `^5.57.0` (part of every default Strapi app; the email log links to its users)
+- Outside development and test: the environment variable `MAGIC_MAIL_ENCRYPTION_KEY` (see [Environment variables](#environment-variables))
 
-Requires Node.js `>=20.19.0 <=26.x.x` and Strapi `^5.57.0`.
+### 1. Install
 
 ```bash
 npm install strapi-plugin-magic-mail
-# or
-yarn add strapi-plugin-magic-mail
 ```
 
-### Enable Plugin
+### 2. Enable
 
-Create or update `config/plugins.ts`:
-
-```typescript
-export default () => ({
+```javascript
+// config/plugins.js (or config/plugins.ts with export default)
+module.exports = () => ({
   'magic-mail': {
     enabled: true,
   },
 });
 ```
 
-### Build & Start
+### 3. Set the encryption key
+
+```bash
+# Generate once and keep it with your other secrets
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+```env
+MAGIC_MAIL_ENCRYPTION_KEY=<the generated value>
+```
+
+Keep the key stable. Losing it makes the stored account credentials unreadable.
+
+### 4. Build and start
 
 ```bash
 npm run build
 npm run develop
 ```
 
-### Add Your First Email Account
+### 5. Add an account and send a test
 
-1. Navigate to **Admin Panel → MagicMail → Email Accounts**
-2. Click **"Add Account"**
-3. Choose your provider (Gmail OAuth, SMTP, etc.)
-4. Fill in credentials
-5. Click **"Test"** to verify
-6. Done! 🎉
-
----
+1. Open **MagicMail → Email Accounts** in the admin and click **Add account**.
+2. Pick a provider and enter the details (see [Provider setup](#provider-setup)).
+3. Click the **Test** action on the account, enter your own address and choose **Direct test**.
 
-## 📧 Supported Email Providers
+Every existing `strapi.plugin('email')` call now goes through MagicMail.
 
-| Provider | Type | Authentication | Features |
-|----------|------|----------------|----------|
-| **Gmail** | OAuth 2.0 | Google OAuth | Gmail API, Attachments, Auto DKIM |
-| **Microsoft 365** | OAuth 2.0 | Azure AD | Graph API, Attachments, Tenant Support |
-| **Yahoo Mail** | OAuth 2.0 | Yahoo OAuth | SMTP OAuth2, Attachments |
-| **SMTP** | Credentials | Username/Password | Universal, DKIM Optional, Custom Servers |
-| **SendGrid** | API Key | SendGrid API | Transactional, Marketing, Templates |
-| **Mailgun** | API Key | Mailgun API | Bulk Sending, Analytics |
+Upgrading from 3.x? Read [Upgrading to 4.0.0](#upgrading-to-400) first.
 
 ---
 
-## 💡 How to Send Emails
+## Sending email
 
-### Method 1: Strapi Native Email Service (Recommended!)
+### Option 1: the Strapi email service (recommended)
 
-MagicMail **automatically intercepts** Strapi's email service - no code changes needed!
+MagicMail wraps the provider of `@strapi/email` at startup, so existing code keeps working:
 
 ```javascript
-// This works in ANY Strapi plugin or controller:
 await strapi.plugin('email').service('email').send({
   to: 'user@example.com',
-  subject: 'Welcome to Our Platform!',
-  text: 'Plain text version',
+  subject: 'Welcome to Example Shop',
+  text: 'Thanks for signing up!',
   html: '<h1>Welcome!</h1><p>Thanks for signing up!</p>',
 });
-
-// ✅ MagicMail automatically:
-// - Selects best account (via routing rules or priority)
-// - Checks rate limits
-// - Handles failover if needed
-// - Logs the email
-// - Updates statistics
 ```
 
-**Benefits:**
-- ✅ **Zero code changes** - Existing plugins work automatically
-- ✅ **Email Designer compatible** - Works with strapi-plugin-email-designer-5
-- ✅ **Fallback safe** - Falls back to original email service if MagicMail fails
-- ✅ **Drop-in replacement** - Just enable and go!
+Both `send()` and `sendTemplatedEmail()` are routed, including Strapi's admin password-reset email and the Users & Permissions emails. MagicMail picks the account (routing rules, then priority), reserves quota, fails over when that is safe, logs the email and updates the statistics.
+
+**Fallback to the original provider.** When no MagicMail account is active, or every eligible account is over its quota, the email is sent through the Strapi email provider you configured before (logged with the account name `strapi-email-provider`). Once a MagicMail account has attempted delivery, an error is returned to the caller and the email is **not** sent again through the original provider, so nothing goes out twice.
 
-### Method 2: Direct MagicMail API
+### Option 2: the MagicMail router service
 
-For explicit control over account selection:
+Use the router directly when you need its options, for example to force an account:
 
 ```javascript
-// Force a specific account
 await strapi.plugin('magic-mail').service('email-router').send({
   to: 'customer@example.com',
-  subject: 'Order Confirmation',
-  html: '<h1>Your Order #12345</h1>',
-  accountName: 'SendGrid Marketing', // Force this account
+  subject: 'Order confirmation',
+  html: '<h1>Your order #12345</h1>',
+  accountName: 'Transactional SMTP', // case-insensitive; never replaced by another account
   type: 'transactional',
   priority: 'high',
 });
+// → { success: true, accountUsed: 'Transactional SMTP', messageId: '<…>', emailId: '…' }
 ```
 
-### Sending with Attachments
+An explicit `accountName` is never swapped for another account: if that account is over quota or fails, the send fails. Router calls never use the Strapi-provider fallback; they get the error.
 
-```javascript
-await strapi.plugin('email').service('email').send({
-  to: 'customer@example.com',
-  subject: 'Invoice #12345',
-  html: '<h1>Invoice Attached</h1>',
-  attachments: [
-    {
-      filename: 'invoice.pdf',
-      path: './uploads/invoice-12345.pdf',
-    },
-    {
-      filename: 'receipt.pdf',
-      content: Buffer.from(pdfData),
-      contentType: 'application/pdf',
-    },
-  ],
-});
-```
+### Option 3: HTTP
 
-**Supported attachment formats:**
-- ✅ PDF, Word, Excel, PowerPoint
-- ✅ Images (PNG, JPG, GIF, WebP)
-- ✅ Text files (TXT, CSV, JSON)
-- ✅ Archives (ZIP, RAR)
-- ✅ Any file type!
+See [Content API](#content-api) for `POST /api/magic-mail/send` and `/send-message`.
 
-### Advanced: Priority & Marketing Emails
+### Send options
 
-```javascript
-// High priority email
-await strapi.plugin('magic-mail').service('email-router').send({
-  to: 'vip@example.com',
-  subject: 'Urgent: Action Required',
-  html: '<h1>Important Update</h1>',
-  priority: 'high', // Adds X-Priority and Importance headers
-});
+The same fields work for the router, the Strapi email service and `POST /api/magic-mail/send`.
 
-// Marketing email with unsubscribe (GDPR/CAN-SPAM compliant)
-await strapi.plugin('magic-mail').service('email-router').send({
-  to: 'subscriber@example.com',
-  subject: 'Weekly Newsletter',
-  html: '<h1>This Week's Updates</h1>',
-  type: 'marketing',
-  unsubscribeUrl: 'https://yoursite.com/unsubscribe?id=123',
-  // Automatically adds List-Unsubscribe header!
-});
-```
+| Field                                                | Description                                                                                                                                                                   |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `to`, `cc`, `bcc`                                    | Address, array or comma-separated list (max. 100 `to`, 50 `cc`/`bcc`). Display names allowed                                                                                  |
+| `subject`, `text`, `html`                            | `subject` is required unless a template provides it; `text` or `html` is required. HTML is sanitised (no scripts, event handlers or `javascript:` URLs; email layout is kept) |
+| `from`                                               | Optional. Must be the sending account's address; only its display name is used                                                                                                |
+| `replyTo`                                            | A valid address                                                                                                                                                               |
+| `type`                                               | `transactional` (default), `marketing` or `notification`. Without `type`, a template's category is used                                                                       |
+| `priority`                                           | `normal` (default), `high` or `low`. `high` adds `X-Priority` and `Importance` headers                                                                                        |
+| `accountName`                                        | Force one account                                                                                                                                                             |
+| `templateId` / `templateReferenceId`, `templateData` | Render a MagicMail template by its Reference ID with Mustache data (`data` is accepted as an alias of `templateData`)                                                         |
+| `unsubscribeUrl`                                     | Per-email unsubscribe URL                                                                                                                                                     |
+| `enableTracking: false`, `skipLinkTracking: true`    | Disable open and click tracking, or only click tracking, for this email                                                                                                       |
+| `customField`                                        | Value matched by routing rules of type _Custom_                                                                                                                               |
+| `headers`                                            | Up to 20 custom headers: `X-*` (except MagicMail's own) plus `List-Id`, `Precedence`, `Auto-Submitted`, `In-Reply-To`, `References`. Others are dropped                       |
+| `attachments`                                        | Up to 20, 25 MB each, with `filename`, `content`, `contentType`, `encoding`, `cid`                                                                                            |
+| `userId`, `recipientName`                            | Stored on the email log                                                                                                                                                       |
 
----
+### Attachments
 
-## 🎨 Email Designer Suite (NEW!)
-
-**Design beautiful emails visually with the integrated email designer!**
-
-### ✨ Features
-
-Every Email Designer feature is included for free:
-
-| Feature | Included |
-|---------|----------|
-| **Visual Designer** | ✅ |
-| **Unlimited Templates** | ✅ |
-| **Drag & Drop + Mustache** | ✅ |
-| **Import / Export** | ✅ |
-| **Template Versioning** | ✅ |
-| **Email Analytics** | ✅ |
-
-### 📧 Creating Email Templates
-
-**1. Navigate to Email Templates Tab**
-
-Go to **MagicMail → Email Templates** in the admin panel.
-
-**2. Create New Template**
-
-Click **"Create Template"** and use the visual designer to build your email.
-
-**3. Add Variables with Mustache**
-
-Use Mustache syntax for dynamic content:
-
-```html
-<h1>Welcome {{user.firstName}}!</h1>
-<p>Thanks for joining {{company.name}}</p>
+```javascript
+await strapi
+  .plugin('email')
+  .service('email')
+  .send({
+    to: 'customer@example.com',
+    subject: 'Invoice 12345',
+    html: '<h1>Your invoice is attached</h1>',
+    attachments: [
+      {
+        filename: 'invoice.pdf',
+        content: await fs.promises.readFile(invoicePath), // read the file yourself
+        contentType: 'application/pdf',
+      },
+      { filename: 'receipt.pdf', content: pdfBase64, encoding: 'base64' },
+    ],
+  });
 ```
 
-**4. Save & Use**
+Attachments must carry their `content` (a Buffer, or a string with `encoding`). Attachments with `path` or `href` are rejected for every provider, so MagicMail never reads server files or fetches URLs for a caller. Inline images use `cid`.
 
-Each template gets a unique **Reference ID** (e.g., `100`) that you use when sending.
+### Unsubscribe and bulk headers
 
-### 💌 Sending Templated Emails
+- `List-Unsubscribe` is sent for marketing emails that have an unsubscribe URL, and for every email type while **Settings → Unsubscribe header** is on and a URL is available.
+- A per-email `unsubscribeUrl` wins. The plugin-wide URL from the settings is used only while the toggle is on; `{{email}}` in it is replaced with the URL-encoded recipient (single-recipient emails only).
+- `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058) is only added for `https` URLs.
+- Marketing emails get `Precedence: bulk`; notification emails get `Auto-Submitted: auto-generated`.
 
-**Method 1: Using Template ID**
+---
 
-```javascript
-// Send email using template
-await strapi.plugin('magic-mail').service('email-router').send({
-  to: 'user@example.com',
-  templateId: 100, // Your template reference ID
-  templateData: {
-    user: {
-      firstName: 'John',
-      lastName: 'Doe',
-      email: 'john@example.com',
-    },
-    company: {
-      name: 'ACME Corp',
-      url: 'https://acme.com',
-    },
-    orderNumber: '12345',
-    orderTotal: '$199.99',
-  },
-});
+## Provider setup
 
-// ✅ MagicMail will:
-// - Load template #100
-// - Render it with your data (Mustache)
-// - Route via smart routing
-// - Send via best account
-```
+### OAuth redirect URI
 
-**Method 2: Via Strapi Email Service**
+MagicMail builds the redirect URI from the `URL` environment variable if it is set (legacy override), otherwise from Strapi's `server.url` (or `server.absoluteUrl`):
 
-```javascript
-// Also works with standard Strapi email service!
-await strapi.plugin('email').service('email').send({
-  to: 'user@example.com',
-  templateId: 100,
-  templateData: {
-    user: { firstName: 'Jane' },
-    resetUrl: 'https://yoursite.com/reset?token=xyz',
-  },
-});
 ```
-
-### 🎯 Template Categories
-
-Templates can be categorized for automatic routing:
-
-- **transactional** - Order confirmations, receipts
-- **marketing** - Newsletters, promotions
-- **notification** - System alerts, updates
-- **custom** - Anything else
-
-**Automatic Routing by Category:**
-
-```javascript
-// Create routing rule: All marketing templates → SendGrid
-// Then just send:
-await strapi.plugin('magic-mail').service('email-router').send({
-  to: 'subscriber@example.com',
-  templateId: 200, // Marketing category template
-  templateData: { offer: '50% OFF' },
-});
-// ✅ Automatically routes via SendGrid (based on category)
+<public URL>/magic-mail/oauth/<gmail|microsoft|yahoo>/callback
 ```
 
-### 🔄 Template Versioning
-
-Every time you save a template, a new version is created automatically:
-
-```javascript
-// Get all versions
-const versions = await strapi
-  .plugin('magic-mail')
-  .service('email-designer')
-  .getVersions(templateId);
-
-// Restore old version
-await strapi
-  .plugin('magic-mail')
-  .service('email-designer')
-  .restoreVersion(templateId, versionId);
-```
+The account wizard shows the exact value the server uses; register exactly that value with the provider. In production the URL must be public `https`; there is no `localhost` fallback. The `localhost:1337` URIs below are for local development.
 
-### 📦 Import/Export Templates
+The authorization popup reports back to the admin origin (`admin.url`). If the admin runs on its own host, set `admin.url` to that absolute URL. OAuth flows are bound to the admin who started them and kept in process memory, so several Strapi instances behind a load balancer need sticky admin sessions.
 
-**Export all templates:**
+**Reconnecting an account** (revoked consent, expired refresh token): edit the account and use **Reconnect with &lt;provider&gt;** in the wizard. The provider must return the account's own mailbox. Access tokens are refreshed 60 seconds before they expire and once more if the provider rejects them; rotated refresh tokens are stored.
 
-```javascript
-const templates = await strapi
-  .plugin('magic-mail')
-  .service('email-designer')
-  .exportTemplates();
+### Gmail (OAuth 2.0)
 
-// Save to file
-fs.writeFileSync('templates.json', JSON.stringify(templates, null, 2));
-```
+1. In the [Google Cloud Console](https://console.cloud.google.com) create or select a project and enable the **Gmail API**.
+2. Create an **OAuth client ID** of type _Web application_.
+3. Add the redirect URI, for example `http://localhost:1337/magic-mail/oauth/gmail/callback`.
+4. In MagicMail choose **Gmail**, paste the client ID and secret, click **Connect with Google** and sign in.
 
-**Import templates:**
+Scopes: `https://www.googleapis.com/auth/gmail.send`, `https://www.googleapis.com/auth/userinfo.email`, `openid`. Mail is sent through the Gmail API.
 
-```javascript
-const templates = JSON.parse(fs.readFileSync('templates.json'));
+### Microsoft 365 (OAuth 2.0)
 
-const results = await strapi
-  .plugin('magic-mail')
-  .service('email-designer')
-  .importTemplates(templates);
+1. In the [Azure portal](https://portal.azure.com) open **Microsoft Entra ID → App registrations → New registration**.
+2. Copy the **Application (client) ID** and the **Directory (tenant) ID**.
+3. Add a _Web_ redirect URI, for example `http://localhost:1337/magic-mail/oauth/microsoft/callback`.
+4. API permissions (Microsoft Graph, _Delegated_): `Mail.Send`, `User.Read`, `offline_access`, `openid`, `email`. Grant admin consent.
+5. Under **Certificates & secrets** create a client secret and copy its **Value** (not the secret ID).
+6. In MagicMail choose **Microsoft 365**, enter tenant ID, client ID and secret, click **Connect with Microsoft**.
 
-console.log(`Imported ${results.filter(r => r.success).length} templates`);
-```
+The tenant ID must be a GUID, a domain, `common`, `organizations` or `consumers`. Mail is sent through Microsoft Graph `sendMail`.
 
-### 🎨 Visual Designer Features
+### Yahoo Mail (OAuth 2.0)
 
-**Powered by Unlayer Email Editor:**
+1. Create an app at [developer.yahoo.com/apps](https://developer.yahoo.com/apps).
+2. Redirect URI, for example `http://localhost:1337/magic-mail/oauth/yahoo/callback`.
+3. Permissions: **Mail (read/write)** and **OpenID Connect** (scopes `openid email mail-w`).
+4. In MagicMail choose **Yahoo Mail**, paste client ID and secret and click **Connect with Yahoo**.
 
-- ✅ Drag & Drop Interface
-- ✅ Pre-built Content Blocks
-- ✅ Image Upload & Management
-- ✅ Custom Fonts & Colors
-- ✅ Responsive Design
-- ✅ Mobile Preview
-- ✅ HTML/Text Editor
-- ✅ Merge Tags Support
-- ✅ Save/Load Designs
+Mail is sent over SMTP with XOAUTH2.
 
-### 📊 Template Statistics
+### SMTP
 
-```javascript
-const stats = await strapi
-  .plugin('magic-mail')
-  .service('email-designer')
-  .getStats();
-
-console.log(stats);
-// {
-//   total: 15,
-//   active: 12,
-//   inactive: 3,
-//   byCategory: [
-//     { category: 'transactional', count: 8 },
-//     { category: 'marketing', count: 4 },
-//     { category: 'notification', count: 3 }
-//   ],
-//   maxTemplates: -1, // unlimited (all features are free)
-//   remaining: -1     // unlimited
-// }
-```
+| Field             | Example                                                      |
+| ----------------- | ------------------------------------------------------------ |
+| Host              | `smtp.example.com`                                           |
+| Port              | `587` (STARTTLS) or `465` (turn on _Use SSL/TLS encryption_) |
+| Username/password | Mailbox credentials or an app password                       |
 
-### 🚀 Best Practices
+Common hosts: Gmail `smtp.gmail.com:587` (app password), Outlook.com `smtp-mail.outlook.com:587`, Microsoft 365 `smtp.office365.com:587`.
 
-**1. Use Template Categories**
-```javascript
-// Set category when creating template
-category: 'marketing' // Auto-routes to marketing account
-```
+TLS 1.2 or newer is required and certificates are verified. For a local mail catcher (Mailpit, MailHog) set `"allowInsecure": true` in the account config; it is honoured outside `NODE_ENV=production`, or for loopback hosts.
 
-**2. Test Templates Before Using**
-```javascript
-// Test render before sending
-const rendered = await strapi
-  .plugin('magic-mail')
-  .service('email-designer')
-  .renderTemplate(100, { user: { firstName: 'Test' } });
+Optional DKIM signing (account config):
 
-console.log(rendered.html); // Preview HTML
+```json
+{
+  "dkim": {
+    "domainName": "example.com",
+    "keySelector": "default",
+    "privateKey": "-----BEGIN PRIVATE KEY-----\n..."
+  }
+}
 ```
 
-**3. Version Control**
-```javascript
-// Template version history is always enabled (free for everyone).
-```
+Generate a key with `openssl genrsa -out dkim_private.pem 2048` and publish the public key as a TXT record at `default._domainkey.example.com`.
 
-**4. Organize with Tags**
-```javascript
-// Add tags to templates
-tags: ['onboarding', 'welcome-series', 'v2']
-```
+The provider value `nodemailer` is an alias of `smtp`.
 
----
+### SendGrid
 
-## 🎯 Smart Routing Rules
+1. In SendGrid go to **Settings → API Keys** and create a key with the **Mail Send** permission.
+2. In MagicMail choose **SendGrid** and paste the key. The sender address must be verified in SendGrid.
 
-Create intelligent routing rules to send emails through specific accounts based on conditions.
+### Mailgun
 
-### Example Use Cases
+1. In Mailgun copy your **Private API key** and your verified sending domain. Note the region the domain was created in (US or EU).
+2. In MagicMail choose **Mailgun**, enter the domain (for example `mg.example.com`), pick the region and paste the key.
 
-**1. Route Marketing Emails via SendGrid:**
-```
-Match Type: Email Type
-Match Value: marketing
-Target Account: SendGrid Marketing
-Priority: 10
-```
+A Mailgun domain can only be used through the API host of its region. MagicMail stores the region as `config.region` and calls:
 
-**2. Route VIP Customers via Priority SMTP:**
-```
-Match Type: Recipient
-Match Value: @vip-customers.com
-Target Account: Priority SMTP
-Fallback Account: Gmail OAuth
-Priority: 9
-```
+| `config.region` | API host                     |
+| --------------- | ---------------------------- |
+| `us` (default)  | `https://api.mailgun.net`    |
+| `eu`            | `https://api.eu.mailgun.net` |
 
-**3. Route Password Reset Emails:**
-```
-Match Type: Subject
-Match Value: Password Reset
-Target Account: Transactional SMTP
-Priority: 8
-```
+Any other value is rejected with a validation error when the account is created or updated. Accounts saved without a region keep using the US host.
 
-### Routing Priority
+### Provider comparison
 
-Rules are evaluated from **highest to lowest priority** (1-10):
-- Priority 10 = Evaluated first (most specific rules)
-- Priority 1 = Evaluated last (catch-all rules)
+| Provider      | Authentication        | Transport                   | DKIM                 |
+| ------------- | --------------------- | --------------------------- | -------------------- |
+| Gmail         | OAuth 2.0             | Gmail API                   | by Google            |
+| Microsoft 365 | OAuth 2.0 (Entra ID)  | Microsoft Graph `sendMail`  | by Microsoft         |
+| Yahoo Mail    | OAuth 2.0             | SMTP with XOAUTH2           | by Yahoo             |
+| SMTP          | Username and password | Nodemailer, any SMTP server | optional (see above) |
+| SendGrid      | API key               | HTTPS API (v3)              | by SendGrid          |
+| Mailgun       | API key + domain      | HTTPS API (US or EU region) | by Mailgun           |
 
-If no rule matches, the **Primary Account** is used.
+All providers support attachments, inline images (`cid`) and custom headers.
 
 ---
 
-## 🔐 Provider Setup Guides
+## Routing rules and quotas
 
-### Gmail OAuth Setup
+Routing rules send an email through a specific account when it matches a condition. Manage them under **MagicMail → Routing Rules**.
 
-**1. Google Cloud Console**
-1. Go to [console.cloud.google.com](https://console.cloud.google.com)
-2. Create a new project or select existing
-3. Enable Gmail API
-4. Create OAuth 2.0 Client ID
-5. Add redirect URI: `http://localhost:1337/magic-mail/oauth/gmail/callback`
-6. Copy Client ID and Client Secret
+| Match type     | Matches when                                                                                                |
+| -------------- | ----------------------------------------------------------------------------------------------------------- |
+| **Email Type** | the email type equals the value (`transactional`, `marketing`, `notification`)                              |
+| **Recipient**  | any recipient matches: `@domain.com` = domain, `user@domain.com` = exact address, anything else = substring |
+| **Subject**    | the subject contains the value (case-insensitive)                                                           |
+| **Template**   | the template name or Reference ID equals the value                                                          |
+| **Custom**     | the email's `customField` equals the value                                                                  |
 
-**2. In MagicMail**
-1. Choose "Gmail OAuth" provider
-2. Paste Client ID and Client Secret
-3. Click "Connect with Google"
-4. Authorize in popup
-5. Done! ✅
+Examples:
 
-**Required Scopes:**
-- `https://www.googleapis.com/auth/gmail.send`
-- `https://www.googleapis.com/auth/userinfo.email`
-
----
+| Rule                  | Match                              | Account            | Fallback           | Priority |
+| --------------------- | ---------------------------------- | ------------------ | ------------------ | -------- |
+| Password resets first | Subject contains `Password Reset`  | Transactional SMTP | Gmail Support      | 1000000  |
+| Marketing campaigns   | Email type `marketing`             | Marketing SendGrid |                    | 50       |
+| VIP customers         | Recipient `@vip-customers.example` | Gmail Support      | Transactional SMTP | 10       |
 
-### Microsoft 365 OAuth Setup
-
-**1. Azure Portal**
-1. Go to [portal.azure.com](https://portal.azure.com)
-2. Navigate to **Azure Active Directory → App registrations**
-3. Click **"New registration"**
-4. Name: "MagicMail"
-5. Account type: **"Accounts in this organizational directory only"**
-6. Copy **Application (client) ID** AND **Directory (tenant) ID**
-
-**2. Add Redirect URI**
-```
-http://localhost:1337/magic-mail/oauth/microsoft/callback
-```
+**Order.** Rules are checked from the highest to the lowest priority (1 to 1,000,000); rules with the same priority are checked oldest first. The first match wins. The admin list and `GET /magic-mail/routing-rules` show them in this order.
 
-**3. API Permissions**
+**Account order for one email.** The account of the first matching rule, then that rule's fallback account, then the accounts (and fallbacks) of the next matching rules, then the primary account, then the remaining active accounts by account priority (1 to 10, higher first). Accounts over their quota are skipped.
 
-Add these **Delegated permissions** under Microsoft Graph:
-- ✅ `Mail.Send` - Send emails as the signed-in user
-- ✅ `User.Read` - Read user profile
-- ✅ `offline_access` - Maintain access (refresh tokens)
-- ✅ `openid` - Sign users in
-- ✅ `email` - View users' email address
+**Failover.** Errors that guarantee the provider did not accept the message (connection or authentication failures, missing credentials, HTTP 401/403/429/500/502/503, SMTP envelope rejection) move on to the next account. Ambiguous errors such as timeouts are returned to the caller instead, so an email is never delivered twice.
 
-**4. Grant Admin Consent** (Required!)
+**Account references.** Rules reference accounts by name. Creating or editing a rule with an unknown account name returns 400. Renaming an account updates its rules; deleting an account deactivates the rules that target it and clears it where it is the fallback.
 
-**5. Create Client Secret**
-1. **Certificates & secrets** → **New client secret**
-2. Copy the **VALUE** (not the Secret ID)
-3. Store it securely!
-
-**6. In MagicMail**
-1. Choose "Microsoft OAuth" provider
-2. Paste **Tenant ID**, **Client ID**, and **Client Secret**
-3. Click "Connect with Microsoft"
-4. Authorize
-5. Done! ✅
+**Quotas.** Each account can have an hourly and a daily limit (0 = unlimited). Quota is reserved atomically before dispatch, so concurrent sends cannot exceed it. Windows follow the clock hour and the calendar day in UTC; set `quotaTimezone` to use another IANA time zone.
 
 ---
 
-### Yahoo Mail OAuth Setup
-
-**1. Yahoo Developer Console**
-1. Go to [developer.yahoo.com/apps](https://developer.yahoo.com/apps)
-2. Click **"Create an App"**
-3. Fill in app details
-
-**2. Add Redirect URI**
-```
-http://localhost:1337/magic-mail/oauth/yahoo/callback
-```
-
-**3. API Permissions**
-- ✅ `Mail` - Send and manage emails
-- ✅ `OpenID Connect` - User authentication
+## Templates and the visual editor
 
-**4. In MagicMail**
-1. Choose "Yahoo Mail OAuth" provider
-2. Paste Client ID and Client Secret
-3. Click "Connect with Yahoo"
-4. Done! ✅
+Everything in the designer is included, with no tiers:
 
----
+| Feature                           | Included |
+| --------------------------------- | -------- |
+| **Visual Designer (Unlayer)**     | ✅       |
+| **Plain HTML/Text editing**       | ✅       |
+| **Unlimited Templates**           | ✅       |
+| **Mustache Variables**            | ✅       |
+| **Import / Export**               | ✅       |
+| **Template Versioning**           | ✅       |
+| **Users & Permissions templates** | ✅       |
 
-### SMTP Setup (Universal)
+### Creating templates
 
-**Works with ANY SMTP server:**
+1. Go to **MagicMail → Email Templates** and click **Create template**.
+2. Build the email in the **Visual Designer** tab, or write HTML and text in the **Plain Text** tab.
+3. Use Mustache variables for dynamic content:
 
-```
-Host: smtp.gmail.com (or your SMTP server)
-Port: 587 (STARTTLS) or 465 (SSL/TLS)
-Username: your-email@domain.com
-Password: your-password (or App Password)
-```
+   ```html
+   <h1>Welcome {{user.firstName}}!</h1>
+   <p>Thanks for joining {{company.name}}</p>
+   ```
 
-**Popular SMTP Servers:**
-- **Gmail:** `smtp.gmail.com:587` (use App Password!)
-- **Outlook:** `smtp-mail.outlook.com:587`
-- **Office365:** `smtp.office365.com:587`
-- **Custom:** Your own mail server
+4. Save. Each template has a numeric **Reference ID** (for example `100`) that you use when sending. It cannot be changed after creation.
 
-**Gmail App Password:**
-1. Google Account → Security → 2-Step Verification
-2. App passwords → Generate
-3. Use the 16-character password in MagicMail
+The server fills `{{system.date}}`, `{{system.year}}` and `{{system.unsubscribe}}` (the email's unsubscribe URL); callers cannot override them.
 
-**Optional: DKIM Signing**
+### Sending a template
 
-For custom domains, you can add DKIM:
 ```javascript
-// In config field (advanced users):
-{
-  dkim: {
-    domainName: 'yourdomain.com',
-    keySelector: 'default',
-    privateKey: '-----BEGIN PRIVATE KEY-----\n...'
-  }
-}
+await strapi
+  .plugin('magic-mail')
+  .service('email-router')
+  .send({
+    to: 'user@example.com',
+    templateId: 100, // Reference ID
+    templateData: {
+      user: { firstName: 'Ada' },
+      company: { name: 'Example Shop' },
+    },
+  });
 ```
 
----
-
-### SendGrid Setup
-
-**1. Get API Key**
-1. Go to [app.sendgrid.com](https://app.sendgrid.com)
-2. Settings → API Keys → Create API Key
-3. Scope: **Mail Send** (Full Access)
-4. Copy the API key
+`strapi.plugin('email').service('email').send()` accepts the same `templateId` and `templateData` fields. The template list also shows a ready-made code snippet per template.
 
-**2. In MagicMail**
-1. Choose "SendGrid" provider
-2. Paste API Key
-3. Done! ✅
+### Categories
 
----
-
-### Mailgun Setup
-
-**1. Get API Key & Domain**
-1. Go to [app.mailgun.com](https://app.mailgun.com)
-2. Settings → API Security → Copy **Private API Key**
-3. Sending → Domains → Copy your verified domain
-
-**2. In MagicMail**
-1. Choose "Mailgun" provider
-2. Enter **Domain** (e.g., `mg.yourdomain.com`)
-3. Paste **Private API Key**
-4. Done! ✅
-
----
-
-## 🛡️ Security Features
-
-### Encryption
-- ✅ **AES-256-GCM** encryption for all credentials
-- ✅ **No plain text passwords** in database
-- ✅ **OAuth tokens encrypted** at rest
-- ✅ **Secure token refresh** mechanism
-
-### Transport Security
-- ✅ **TLS 1.2+ enforced** (SMTP)
-- ✅ **Certificate verification** enabled
-- ✅ **HTTPS only** for API providers
-
-### Email Authentication
-- ✅ **DKIM signing** (optional for SMTP, automatic for OAuth)
-- ✅ **SPF validation** support
-- ✅ **DMARC compliance** - All providers pass DMARC checks
-- ✅ **Proper Message-ID** generation (RFC 5322)
-
-### Content Security
-- ✅ **XSS prevention** - No `<script>` tags allowed
-- ✅ **Input validation** - Email format, subject length
-- ✅ **Spam trigger detection** - Warns about suspicious patterns
-- ✅ **MIME type validation**
-
-### Compliance Headers
-- ✅ **List-Unsubscribe** (RFC 8058) - GDPR/CAN-SPAM compliant
-- ✅ **Auto-Submitted** (RFC 3834) - Prevents auto-responder loops
-- ✅ **Precedence: bulk** for marketing emails
-- ✅ **X-Priority** and **Importance** headers
+Templates have a category: `transactional`, `marketing`, `notification` or `custom`. The first three become the email `type` when the caller passes none, so a rule _Email Type = marketing_ also catches marketing templates.
 
----
+### Versions, import and export
 
-## 📊 Features Overview
-
-### Multi-Account Management
-- Unlimited email accounts
-- Provider-specific configuration
-- Active/Inactive status
-- Primary account designation
-- Per-account priority (1-10)
-- Daily and hourly rate limits
-
-### Smart Routing Engine
-- **Email Type Routing** - transactional, marketing, notification
-- **Recipient Matching** - Route by email domain or address
-- **Subject Matching** - Route by subject keywords
-- **Template Matching** - Route by template name
-- **Custom Field Matching** - Flexible custom conditions
-- **Priority-based evaluation** - Higher priority rules match first
-- **Fallback accounts** - Automatic failover per rule
-
-### Rate Limiting & Failover
-- Per-account daily limits
-- Per-account hourly limits
-- Automatic counter reset (hourly/daily)
-- Smart failover to backup accounts
-- Rate limit hit detection
-- Account health monitoring
-
-### Analytics & Monitoring
-- Real-time statistics dashboard
-- Emails sent today (per account and total)
-- Total emails sent (lifetime)
-- Active/Inactive account count
-- Success/Failure tracking
-- Last used timestamps
-- Visual progress bars for rate limits
-
-### Testing Features
-- **Test Direct** - Test specific account directly
-- **Test Strapi Service** - Verify Email Designer compatibility
-- **Priority Testing** - Test high/normal priority headers
-- **Marketing Email Testing** - Test List-Unsubscribe headers
-- **Detailed test results** - Shows all security features applied
-
----
+- Version 1 is the created template. Every save that changes the content (name, subject, design, HTML, text or tags) adds a version with the saved content. Saves that only toggle `isActive` or the category add none. Restoring a version saves its content as a new version.
+- Export writes JSON (all templates, or the ones you select); import accepts MagicMail exports and exports of `strapi-plugin-email-designer-5`. The `isActive` state is kept.
 
-## 🔧 Configuration
-
-### Basic Setup (No .env Required!)
-
-All configuration is done via the Admin Panel. However, for production deployments, you can set:
-
-```env
-# Optional - Base URL for OAuth callbacks
-URL=https://yourdomain.com
-
-# Optional - Encryption key (auto-generated if not provided)
-ENCRYPTION_KEY=your-32-character-secret-key
+```javascript
+const designer = strapi.plugin('magic-mail').service('email-designer');
+const versions = await designer.getVersions(templateDocumentId);
+await designer.restoreVersion(templateDocumentId, versionDocumentId);
+const exported = await designer.exportTemplates(); // or exportTemplates([documentId, ...])
+const results = await designer.importTemplates(exported);
 ```
 
-### Account Configuration
-
-Each account can have:
+### Users & Permissions templates
 
-**Basic Settings:**
-- Name (unique identifier)
-- Description
-- Provider type
-- From Email
-- From Name
-- Reply-To Email
+The **Core emails** tab edits the _Reset password_ and _Email address confirmation_ templates of Users & Permissions. This needs the _Users & Permissions → Email templates_ read/update permissions in addition to MagicMail's. Only `{{ URL }}`, `{{ SERVER_URL }}`, `{{ ADMIN_URL }}`, `{{ CODE }}`, `{{ TOKEN }}`, `{{ USER }}`, `{{ USER.email }}` and `{{ USER.username }}` are accepted; they are stored as `<%= KEY %>`, the syntax Users & Permissions fills in.
 
-**Security:**
-- OAuth credentials (encrypted)
-- SMTP credentials (encrypted)
-- API keys (encrypted)
-- DKIM configuration (optional)
+### The visual editor (Unlayer) and privacy
 
-**Rate Limiting:**
-- Daily email limit (0 = unlimited)
-- Hourly email limit (0 = unlimited)
-- Priority (1-10, higher = preferred)
+The visual designer embeds the [Unlayer](https://unlayer.com) editor through `react-email-editor`. What that means for you:
 
-**Status:**
-- Active/Inactive
-- Primary account designation
-
----
+- The editor script loads from `https://editor.unlayer.com/embed.js?2` and the editor build is pinned (`1.524.0`). Unlayer serves the editor, so the browser of each editor user contacts Unlayer's servers.
+- No Unlayer `projectId` is sent unless you configure one.
+- Disabled: Unlayer image hosting, stock images, the AI assistant, the hosted image editor, "preview in browser" and third-party placeholder images. New image blocks use an inline placeholder.
+- Images you add are uploaded to the **Strapi Media Library** (`POST /upload`), so editors also need _Media Library → Create (upload)_.
+- If the editor cannot load (CSP, offline, blocked), the page explains why and the **Plain Text** tab keeps working. You never need Unlayer to send templates.
 
-## 🎨 API Reference
-
-### Send Email (Standard Method)
+Optional overrides (`config/plugins.js`):
 
 ```javascript
-await strapi.plugin('email').service('email').send({
-  to: 'recipient@example.com',
-  from: 'sender@example.com', // Optional - uses account default
-  subject: 'Email Subject',
-  text: 'Plain text content',
-  html: '<h1>HTML content</h1>',
-  
-  // Optional advanced options:
-  replyTo: 'reply@example.com',
-  type: 'transactional', // or 'marketing', 'notification'
-  priority: 'normal', // or 'high'
-  accountName: 'Specific Account', // Force specific account
-  unsubscribeUrl: 'https://site.com/unsubscribe', // For marketing emails
-  
-  attachments: [
-    {
-      filename: 'document.pdf',
-      path: './path/to/file.pdf',
-      contentType: 'application/pdf',
+module.exports = () => ({
+  'magic-mail': {
+    config: {
+      designer: {
+        projectId: null, // your own Unlayer project id (positive integer)
+        scriptUrl: null, // https URL of a vetted, self-hosted copy of embed.js
+        version: null, // exact Unlayer build, e.g. '1.524.0'
+      },
     },
-  ],
-});
-```
-
-### Send Email (Direct MagicMail API)
-
-```javascript
-await strapi.plugin('magic-mail').service('email-router').send({
-  to: 'user@example.com',
-  subject: 'Test Email',
-  html: '<p>Content</p>',
-  accountName: 'Gmail OAuth', // Optional - force specific account
-  type: 'transactional',
-  priority: 'normal',
+  },
 });
 ```
 
-### Get All Accounts
-
-```javascript
-const accounts = await strapi.plugin('magic-mail').service('account-manager').getAllAccounts();
-```
+### Content Security Policy for the visual editor
 
-### Test Account
+Strapi's `strapi::security` middleware blocks third-party scripts and frames. To use the visual designer, allow the Unlayer origin in `config/middlewares.js`. Do **not** add `'unsafe-inline'` or `'unsafe-eval'`.
 
 ```javascript
-const result = await strapi.plugin('magic-mail').service('account-manager').testAccount(
-  accountId,
-  'test@example.com',
+module.exports = [
+  'strapi::logger',
+  'strapi::errors',
   {
-    priority: 'high',
-    type: 'marketing',
-    unsubscribeUrl: 'https://example.com/unsubscribe',
-  }
-);
-```
-
----
-
-## 🧪 Testing Your Setup
-
-### Test via Admin UI
-
-1. Go to **Email Accounts**
-2. Click **Test** button on any account
-3. Enter recipient email
-4. Select test options:
-   - **Priority:** Normal / High
-   - **Email Type:** Transactional / Marketing / Notification
-   - **Unsubscribe URL:** (for marketing emails)
-5. Choose test method:
-   - **Test Direct** - Direct send via account
-   - **Test Strapi Service** - Via Strapi email service (tests Email Designer compatibility)
-
-### Test via Code
-
-```javascript
-// Test email with all security features
-await strapi.plugin('magic-mail').service('account-manager').testAccount(
-  accountId,
-  'your-email@example.com',
-  {
-    priority: 'high',
-    type: 'marketing',
-    unsubscribeUrl: 'https://yoursite.com/unsubscribe',
-  }
-);
+    name: 'strapi::security',
+    config: {
+      contentSecurityPolicy: {
+        useDefaults: true,
+        directives: {
+          'script-src': ["'self'", 'https://editor.unlayer.com'],
+          'frame-src': ["'self'", 'https://editor.unlayer.com'],
+          // Media Library images shown in the editor and the preview:
+          'img-src': ["'self'", 'data:', 'blob:', 'https://your-media-host.example'],
+        },
+      },
+    },
+  },
+  'strapi::cors',
+  'strapi::poweredBy',
+  'strapi::query',
+  'strapi::body',
+  'strapi::session',
+  'strapi::favicon',
+  'strapi::public',
+];
 ```
 
-### Verify Headers
-
-**To verify security headers are applied:**
+With `designer.scriptUrl` (self-hosted `embed.js`) put that origin into `script-src` instead; the editor iframe still loads from `editor.unlayer.com`, so keep it in `frame-src`. The Unlayer script runs in the admin origin. Only allow it if you accept that trust.
 
-**In Gmail:**
-1. Open email → Click ⋮ (three dots)
-2. "Show original"
-3. Look for:
-   ```
-   X-Mailer: MagicMail/1.0
-   X-Priority: 1 (Highest)
-   Importance: high
-   List-Unsubscribe: <https://...>
-   Message-ID: <...>
-   DKIM-Signature: ...
-   ```
+---
 
-**In Outlook/Microsoft:**
-1. Email → File → Properties
-2. View "Internet headers"
-3. Should show "High Importance" with red exclamation mark
+## Tracking, privacy and retention
 
----
+Open tracking adds a 1×1 pixel; click tracking rewrites `<a href>` links to a redirect. Both are on by default (**Settings → MagicMail → Plugin Settings**) and can be turned off per email with `enableTracking: false` or `skipLinkTracking: true`.
 
-## 🔒 Security Compliance
+**Public URL.** Tracking URLs use the _Tracking base URL_ setting, then `server.url`, then `server.absoluteUrl`, plus your REST prefix (`api.rest.prefix`, default `/api`), for example `https://cms.example.com/api/magic-mail/track/click/...`. In production a loopback host (`localhost`, `127.0.0.1`, `0.0.0.0`) is never used: without a public URL, emails are sent **untracked** and one warning is logged.
 
-### Email Authentication
+**Never tracked.** Authentication and one-time-token links (password reset, confirmation, magic links, OAuth, parameters such as `token`, `code`, `key`, `signature`, `session`, long random values), `mailto:` and `tel:` links, and links beyond `maxLinksPerEmail` (100). Emails sent through the Content API are click-tracked only for hosts in `tracking.allowedLinkHosts` (none by default).
 
-| Standard | Status | Description |
-|----------|--------|-------------|
-| **DKIM** | ✅ | DomainKeys Identified Mail - Signature validation |
-| **SPF** | ✅ | Sender Policy Framework - Sender verification |
-| **DMARC** | ✅ | Domain-based Authentication - Policy enforcement |
-| **TLS 1.2+** | ✅ | Transport Layer Security - Encrypted transmission |
-| **AES-256-GCM** | ✅ | Credential encryption at rest |
+**What is stored.** Open and click events store the IP truncated to /24 (IPv4) or /48 (IPv6) and at most 512 characters of user agent; no location. Only Koa's `request.ip` is used, so behind a reverse proxy enable [`server.proxy`](https://docs.strapi.io/cms/configurations/server), otherwise every recipient shares the proxy's address.
 
-### Regulatory Compliance
+**Retention.** Every 6 hours MagicMail deletes events older than `tracking.eventRetentionDays` (90) and tracked links older than `tracking.linkTtlDays` (180; expired links then show the fallback page). `tracking.logRetentionDays` optionally deletes old email logs with their events and links. Logs contain personal data (recipient addresses); you can also delete them with **Analytics → Clear All** or with `DELETE /magic-mail/analytics/emails?olderThan=<ISO date>`.
 
-| Regulation | Status | Implementation |
-|------------|--------|----------------|
-| **GDPR** | ✅ | List-Unsubscribe header for marketing emails |
-| **CAN-SPAM** | ✅ | One-click unsubscribe mechanism (RFC 8058) |
-| **RFC 5322** | ✅ | Proper email format and headers |
-| **RFC 3834** | ✅ | Auto-Submitted header prevents loops |
-| **RFC 2156** | ✅ | Priority and Importance headers |
+**Rate limit.** The tracking routes allow 300 requests per minute and IP. Above that, opens and clicks are no longer recorded but recipients still get the pixel and the redirect; only above 3,000 per minute is a plain-text 429 returned.
 
-### Security Validation
+**Signing.** Tracking hashes are signed with `MAGIC_MAIL_TRACKING_SECRET`, falling back to `MAGIC_MAIL_ENCRYPTION_KEY`. To rotate, keep the old values in `MAGIC_MAIL_TRACKING_SECRET_PREVIOUS` (comma-separated) while old emails matter.
 
-**Every email is validated for:**
-- ✅ Valid recipient email format
-- ✅ Non-empty subject line
-- ✅ Subject length (warns if > 200 chars)
-- ✅ Content presence (text or html required)
-- ✅ No `<script>` tags in HTML
-- ✅ No `javascript:` protocol in links
-- ✅ Spam trigger detection (warns only)
+Mention open and click tracking in your privacy notice.
 
 ---
 
-## 📈 Analytics & Monitoring
+## Content API
 
-### Dashboard Stats
+| Method | Path                                                            | Auth      | Purpose                                                                       |
+| ------ | --------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
+| `POST` | `/api/magic-mail/send`                                          | API token | Send through the router with all [send options](#send-options)                |
+| `POST` | `/api/magic-mail/send-message`                                  | API token | Simple email: `to`, `cc`, `bcc`, `subject`, `message`/`text`/`html`, template |
+| `GET`  | `/api/magic-mail/track/open/:emailId/:recipientHash`            | public    | Open-tracking pixel                                                           |
+| `GET`  | `/api/magic-mail/track/click/:emailId/:linkHash/:recipientHash` | public    | Click redirect                                                                |
 
-**Global Stats:**
-- Emails sent today (all accounts)
-- Total emails sent (lifetime)
-- Active accounts count
+### The API token rule
 
-**Per-Account Stats:**
-- Emails sent today
-- Total emails sent
-- Rate limit usage (visual progress bars)
-- Last used timestamp
-- Success/failure rate
+The send routes accept **API tokens only**. Create a _Custom_ token under **Settings → API Tokens** that allows only **Magic-mail → controller → `send`** (and `sendMessage` if you use it). Never enable these actions for the _Public_ or _Authenticated_ role: a users-permissions request is rejected with 403 even if the role has the permission.
 
-### Email Logging
+To let users-permissions roles send as well (the pre-4.0 behaviour):
 
-Every email is logged with:
-- Recipient
-- Sender
-- Subject
-- Account used
-- Status (sent/failed)
-- Timestamp
-- Email type
-- Error message (if failed)
-
-Access logs via:
 ```javascript
-const logs = await strapi.entityService.findMany('plugin::magic-mail.email-log', {
-  filters: { status: 'sent' },
-  sort: { createdAt: 'desc' },
-  limit: 100,
+// config/plugins.js
+module.exports = () => ({
+  'magic-mail': {
+    config: { contentApi: { allowUserRoles: true } },
+  },
 });
 ```
 
----
-
-## 🔄 Integration with Email Designer
-
-**MagicMail is fully compatible with [strapi-plugin-email-designer-5](https://www.npmjs.com/package/strapi-plugin-email-designer-5)!**
-
-### How It Works
-
-1. Install Email Designer:
-   ```bash
-   npm install strapi-plugin-email-designer-5
-   ```
-
-2. Create email templates in Email Designer
-
-3. Send via template:
-   ```javascript
-   // Email Designer internally uses strapi.plugin('email').service('email').send()
-   // MagicMail automatically intercepts it!
-   ```
+With user roles allowed, the email log is always attributed to the authenticated user and a body `userId` is ignored. With an API token, `userId` must be the id or documentId of an existing users-permissions user (else 400).
 
-4. Your email is automatically:
-   - ✅ Routed through MagicMail's smart routing
-   - ✅ Sent via the best account (based on rules)
-   - ✅ Rate limited and failover protected
-   - ✅ Logged and tracked
+The body is validated strictly: unknown fields, `path`/`href` attachments and invalid addresses return 400. Both send routes share a budget of 60 requests per minute per token (in process memory, so each Strapi instance counts separately).
 
-**No configuration needed - it just works!** 🎉
+### Example: send
 
----
-
-## 🚨 Troubleshooting
-
-### Email Not Received
-
-**1. Check Logs**
 ```bash
-# Look for errors in Strapi console
-[magic-mail] ❌ Email send failed: ...
+curl -X POST https://cms.example.com/api/magic-mail/send \
+  -H "Authorization: Bearer $MAGIC_MAIL_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": "customer@example.com",
+    "templateId": 100,
+    "templateData": { "user": { "firstName": "Ada" } },
+    "type": "transactional"
+  }'
+```
+
+```json
+{
+  "success": true,
+  "accountUsed": "Transactional SMTP",
+  "messageId": "<…@example.com>",
+  "emailId": "…"
+}
 ```
 
-**2. Check Account Status**
-- Is the account marked as "Active"?
-- Test the account using the Test button
-- Check rate limits haven't been exceeded
-
-**3. Check Spam Folder**
-- First emails from new accounts may land in spam
-- Check spam/junk folders
-- Mark as "Not Spam" to train filters
-
-**4. Verify Credentials**
-- SMTP: Username and password correct?
-- Gmail: Using App Password (not regular password)?
-- OAuth: Tokens may have expired - reconnect
-
-### DMARC Failures
+### Example: send-message
 
-**For Custom Domains:**
-1. Set up SPF record:
-   ```
-   v=spf1 include:_spf.google.com ~all
-   ```
+```bash
+curl -X POST https://cms.example.com/api/magic-mail/send-message \
+  -H "Authorization: Bearer $MAGIC_MAIL_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{ "to": "customer@example.com", "subject": "Your code", "message": "Your code is 123456." }'
+```
 
-2. Set up DKIM:
-   - Generate DKIM key pair
-   - Add public key to DNS
-   - Add private key to MagicMail SMTP config
+The response has the same shape as `/send`.
 
-3. Set up DMARC:
-   ```
-   v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com
-   ```
+### Errors
 
-**For OAuth Providers (Gmail, Microsoft, Yahoo):**
-- ✅ DKIM handled automatically
-- ✅ SPF handled automatically
-- ✅ DMARC should pass automatically
+Errors use Strapi's envelope:
 
-### Rate Limit Errors
+```json
+{
+  "data": null,
+  "error": { "status": 400, "name": "ValidationError", "message": "…", "details": {} }
+}
+```
 
-**If you hit rate limits:**
-- Increase daily/hourly limits in account settings
-- Add more accounts for load balancing
-- Set up routing rules to distribute load
-- Check provider-specific limits:
-  - Gmail: 500/day (free), 2000/day (workspace)
-  - SendGrid: Varies by plan
-  - Mailgun: Varies by plan
+| Status | When                                                                                                |
+| ------ | --------------------------------------------------------------------------------------------------- |
+| 400    | Invalid or unknown fields, invalid addresses, `userId` of a missing user                            |
+| 401    | Invalid or expired token                                                                            |
+| 403    | No token, a token without the action, or a users-permissions caller while `allowUserRoles` is false |
+| 429    | More than 60 send requests per minute (`TooManyRequestsError`, `Retry-After` header)                |
+| 500    | Delivery failed (no account could send, or the provider rejected the email)                         |
 
-### OAuth Connection Issues
+---
 
-**Gmail OAuth:**
-- Ensure Gmail API is enabled
-- Check redirect URI matches exactly
-- Clear browser cookies and try again
+## Admin API
 
-**Microsoft OAuth:**
-- Verify all 5 permissions are granted
-- **Grant admin consent** (required!)
-- Use correct Tenant ID
-- Check Client Secret hasn't expired
+All admin routes live under `/magic-mail` on the Strapi server (not `/api`), require an authenticated administrator (admin JWT) and the capability shown. The admin UI uses them; you can call them with an admin token for automation.
 
-**Yahoo OAuth:**
-- Verify app is approved by Yahoo
-- Check API permissions are enabled
+| Area          | Routes                                                                                                                                                                                                                                                                | Capability                                                    |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Accounts      | `GET /accounts`, `GET /accounts/:accountId`                                                                                                                                                                                                                           | `read`                                                        |
+|               | `POST /accounts`, `PUT /accounts/:accountId`, `DELETE /accounts/:accountId`                                                                                                                                                                                           | `manage`                                                      |
+|               | `POST /accounts/:accountId/test`, `POST /test-strapi-service`                                                                                                                                                                                                         | `test-send`                                                   |
+| Routing rules | `GET /routing-rules`, `GET /routing-rules/:ruleId`                                                                                                                                                                                                                    | `read`                                                        |
+|               | `POST /routing-rules`, `PUT /routing-rules/:ruleId`, `DELETE /routing-rules/:ruleId`                                                                                                                                                                                  | `manage`                                                      |
+| OAuth         | `GET /oauth/<gmail\|microsoft\|yahoo>/auth`, `POST /oauth/create-account`, `POST /oauth/reconnect/:accountId`                                                                                                                                                         | `manage`                                                      |
+|               | `GET /oauth/<provider>/callback`                                                                                                                                                                                                                                      | public, signed single-use state                               |
+| Templates     | `GET /designer/templates`, `GET /designer/templates/:id`, `GET /designer/templates/:id/versions`, `GET /designer/templates/:id/download`, `POST /designer/render/:templateReferenceId`, `POST /designer/export`, `GET /designer/stats`, `GET /designer/editor-config` | `read`                                                        |
+|               | `POST /designer/templates`, `PUT`/`DELETE /designer/templates/:id`, `POST /designer/templates/:id/duplicate`, `POST /designer/import`, version restore/delete routes                                                                                                  | `manage`                                                      |
+|               | `POST /designer/templates/:id/test-send`                                                                                                                                                                                                                              | `test-send`                                                   |
+|               | `GET`/`PUT /designer/core/:coreEmailType`                                                                                                                                                                                                                             | `read`/`manage` + users-permissions email-template permission |
+| Analytics     | `GET /analytics/stats`, `GET /analytics/emails`, `GET /analytics/emails/:emailId`, `GET /analytics/users/:userId`                                                                                                                                                     | `read`                                                        |
+|               | `DELETE /analytics/emails/:emailId`, `DELETE /analytics/emails`                                                                                                                                                                                                       | `manage`                                                      |
+|               | `GET /analytics/debug` (only with `MAGIC_MAIL_ENABLE_DEBUG_ENDPOINT=true`, never in production)                                                                                                                                                                       | `read`                                                        |
+| Settings      | `GET /settings` / `PUT /settings`                                                                                                                                                                                                                                     | `read` / `manage`                                             |
 
----
+Test sends (`/accounts/:accountId/test`, `/test-strapi-service`, `/designer/templates/:id/test-send`) are limited to 10 per minute per admin.
 
-## 🏗️ Architecture
+### Example: create a routing rule
 
-### Plugin Structure
+```http
+POST /magic-mail/routing-rules
+Authorization: Bearer <admin JWT>
+Content-Type: application/json
 
+{
+  "name": "Marketing campaigns",
+  "matchType": "emailType",
+  "matchValue": "marketing",
+  "accountName": "Marketing SendGrid",
+  "fallbackAccountName": "Transactional SMTP",
+  "priority": 50,
+  "isActive": true
+}
 ```
-magic-mail/
-├── admin/                  # React Admin UI
-│   └── src/
-│       ├── components/
-│       │   ├── AddAccountModal.jsx    # Multi-step account setup
-│       │   └── PluginIcon.jsx         # Sidebar icon
-│       └── pages/
-│           ├── App.jsx                # Main app with tabs
-│           ├── HomePage.jsx           # Email accounts page
-│           └── RoutingRules.jsx       # Routing rules page
-├── server/                # Backend
-│   └── src/
-│       ├── bootstrap.js              # Overrides Strapi email service
-│       ├── controllers/
-│       │   ├── accounts.js           # CRUD for accounts
-│       │   ├── oauth.js              # OAuth flows
-│       │   └── routing-rules.js      # CRUD for routing rules
-│       ├── services/
-│       │   ├── email-router.js       # Core routing logic
-│       │   ├── account-manager.js    # Account management
-│       │   └── oauth.js              # OAuth token exchange
-│       ├── content-types/
-│       │   ├── email-account/        # Account schema
-│       │   ├── email-log/            # Email log schema
-│       │   └── routing-rule/         # Routing rule schema
-│       └── utils/
-│           └── encryption.js         # AES-256-GCM encryption
-└── package.json
-```
-
-### Data Flow
 
-```
-Email Request
-    ↓
-Strapi Email Service (intercepted!)
-    ↓
-MagicMail Email Router
-    ↓
-Routing Rules Engine
-    ↓
-Account Selection (priority/rules)
-    ↓
-Rate Limit Check
-    ↓
-Provider-Specific Sender
-    ↓
-Email Log & Stats Update
-    ↓
-Response
+```json
+{
+  "data": {
+    "documentId": "…",
+    "name": "Marketing campaigns",
+    "matchType": "emailType",
+    "priority": 50,
+    "…": "…"
+  },
+  "message": "Routing rule created successfully"
+}
 ```
 
----
-
-## 🎯 Use Cases
-
-### Multi-Tenant SaaS
-
-```javascript
-// Each tenant gets their own email account
-// Route by custom field:
+`matchType` is one of `emailType`, `recipient`, `subject`, `template`, `custom`. An unknown `accountName` or `fallbackAccountName` returns 400.
 
-// Routing Rule:
-// Match Type: Custom Field
-// Match Value: tenant-123
-// Target Account: Tenant 123 Gmail
+### Example: list accounts
 
-await strapi.plugin('email').service('email').send({
-  to: 'customer@example.com',
-  subject: 'Order Confirmation',
-  html: '<h1>Order #456</h1>',
-  customField: 'tenant-123', // Matches routing rule
-});
+```http
+GET /magic-mail/accounts
 ```
 
-### High-Volume Email Sending
-
-```javascript
-// Distribute load across multiple accounts
-// Account 1: Priority 10, Limit 500/day
-// Account 2: Priority 9, Limit 500/day
-// Account 3: Priority 8, Limit 500/day
-// → Total: 1500 emails/day with automatic load balancing!
+```json
+{
+  "data": [
+    {
+      "documentId": "…",
+      "name": "Transactional SMTP",
+      "provider": "smtp",
+      "fromEmail": "noreply@example.com",
+      "isActive": true,
+      "isPrimary": true,
+      "priority": 9,
+      "dailyLimit": 500,
+      "hourlyLimit": 0,
+      "emailsSentToday": 128,
+      "totalEmailsSent": 18342
+    }
+  ],
+  "meta": { "count": 1 }
+}
 ```
 
-### Marketing Campaigns
+Credentials are never returned. `GET /accounts/:accountId` returns `********` for each stored secret; send that exact value back in `PUT` to keep a secret. Changing provider, `host`, `port`, `user`, `clientId`, `tenantId`, `domain` or `allowInsecure` requires the secrets again (400 otherwise, with the fields in `details.config`).
 
-```javascript
-// Route marketing emails via SendGrid
-// Routing Rule:
-// Match Type: Email Type
-// Match Value: marketing
-// Target Account: SendGrid Marketing
+### Example: delivery log
 
-await strapi.plugin('email').service('email').send({
-  to: 'subscriber@example.com',
-  subject: 'Weekly Newsletter',
-  html: template,
-  type: 'marketing',
-  unsubscribeUrl: 'https://yoursite.com/unsubscribe?id=123',
-});
-// ✅ Automatically routes via SendGrid
-// ✅ Adds List-Unsubscribe header
-// ✅ GDPR/CAN-SPAM compliant
+```http
+GET /magic-mail/analytics/emails?search=order&deliveryStatus=sent&page=1&pageSize=25
 ```
 
-### VIP Customer Emails
-
-```javascript
-// Route VIP customers via a priority account
-// Routing Rule:
-// Match Type: Recipient
-// Match Value: @vip-domain.com
-// Target Account: Priority SMTP
-// Fallback Account: Gmail OAuth
-
-await strapi.plugin('email').service('email').send({
-  to: 'ceo@vip-domain.com',
-  subject: 'Exclusive Offer',
-  html: content,
-  priority: 'high',
-});
-// ✅ Routes via Priority SMTP
-// ✅ High priority headers added
-// ✅ Automatic fallback if the priority account is unavailable
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "emailId": "…",
+      "recipient": "user01@example.com",
+      "subject": "Your order #1001 has shipped",
+      "deliveryStatus": "sent",
+      "openCount": 0,
+      "clickCount": 0
+    }
+  ],
+  "pagination": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 1 }
+}
 ```
 
----
-
-## 🔌 Email Provider Comparison
-
-| Feature | Gmail OAuth | Microsoft OAuth | Yahoo OAuth | SMTP | SendGrid | Mailgun |
-|---------|-------------|-----------------|-------------|------|----------|---------|
-| **Auth Method** | OAuth 2.0 | OAuth 2.0 | OAuth 2.0 | Password | API Key | API Key |
-| **Free Tier** | 500/day | Varies | Limited | Varies | 100/day | 5000/month |
-| **Attachments** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **HTML Emails** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **DKIM Auto** | ✅ | ✅ | ✅ | Optional | ✅ | ✅ |
-| **Custom Headers** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Priority Headers** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Security** | Excellent | Excellent | Good | Good | Excellent | Excellent |
-| **Deliverability** | Excellent | Excellent | Good | Varies | Excellent | Excellent |
-| **Best For** | Personal/Small | Enterprise | Personal | Custom | Marketing | Bulk/Dev |
+`search` looks in recipient, subject and template name; `pageSize` is capped at 100.
 
 ---
 
-## 🌍 Production Deployment
+## Permissions
 
-### Environment Variables
+MagicMail registers four admin actions under **Settings → Administration Panel → Roles → Plugins → MagicMail**:
 
-```env
-# Base URL (required for OAuth callbacks in production)
-URL=https://yourdomain.com
-
-# Database (Strapi default)
-DATABASE_CLIENT=postgres
-DATABASE_HOST=127.0.0.1
-DATABASE_PORT=5432
-DATABASE_NAME=strapi
-DATABASE_USERNAME=strapi
-DATABASE_PASSWORD=password
-
-# Required in production. Keep this stable across deploys and backups.
-# Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
-MAGIC_MAIL_ENCRYPTION_KEY=your-generated-secret-with-at-least-32-bytes
-
-# Optional dedicated OAuth-state signing secret. APP_KEYS is used otherwise.
-MAGIC_MAIL_OAUTH_STATE_SECRET=your-generated-secret-with-at-least-32-bytes
-```
+| Action                         | Grants                                                                                                          |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `plugin::magic-mail.access`    | The MagicMail menu entry and page. No API access by itself                                                      |
+| `plugin::magic-mail.read`      | Read accounts, routing rules, templates, analytics and settings; render and export templates; the settings link |
+| `plugin::magic-mail.manage`    | Create, update and delete accounts, rules, templates, logs and settings; OAuth setup                            |
+| `plugin::magic-mail.test-send` | Send test emails (account test, Strapi-service test, template test); 10 per minute per admin                    |
 
-### OAuth Callback URLs
+Typical roles:
 
-**Update redirect URIs in your OAuth apps:**
+- **Read-only:** `access` + `read`
+- **Editor:** `access` + `read` + `manage`
+- **Tester:** `access` + `read` + `test-send`
 
-**Gmail:**
-```
-https://yourdomain.com/magic-mail/oauth/gmail/callback
-```
+Editing the Users & Permissions templates also needs the users-permissions email-template permissions; uploading images in the visual editor needs _Media Library → Create (upload)_. Details: [docs/permission-migration.md](./docs/permission-migration.md).
 
-**Microsoft:**
-```
-https://yourdomain.com/magic-mail/oauth/microsoft/callback
-```
-
-**Yahoo:**
-```
-https://yourdomain.com/magic-mail/oauth/yahoo/callback
-```
+---
 
-### Recommended Provider Settings
+## Configuration reference
 
-**For Production Apps:**
+### Environment variables
 
-| Use Case | Recommended Provider | Configuration |
-|----------|---------------------|---------------|
-| **Transactional** | SendGrid or Mailgun | High daily limit, dedicated IP |
-| **Marketing** | SendGrid | List management, analytics |
-| **Notifications** | SMTP or Gmail OAuth | Medium limits, reliable |
-| **Internal** | Microsoft 365 | Company domain, OAuth |
-| **Development** | Mailgun Sandbox | Free testing |
+| Variable                              | Required                                                 | Purpose                                                                         |
+| ------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `MAGIC_MAIL_ENCRYPTION_KEY`           | yes, unless `NODE_ENV` is unset, `development` or `test` | Credential encryption key (32+ bytes). Keep it stable and backed up             |
+| `MAGIC_MAIL_ENCRYPTION_KEY_PREVIOUS`  | no                                                       | Previous key during a rotation (decrypt only; saving an account re-encrypts it) |
+| `MAGIC_MAIL_OAUTH_STATE_SECRET`       | no                                                       | OAuth state signing secret (default: derived from the encryption key)           |
+| `MAGIC_MAIL_TRACKING_SECRET`          | no                                                       | Tracking hash secret (default: derived from the encryption key)                 |
+| `MAGIC_MAIL_TRACKING_SECRET_PREVIOUS` | no                                                       | Comma-separated old tracking secrets that stay valid                            |
+| `URL`                                 | no                                                       | Legacy override of the OAuth callback base URL (default: `server.url`)          |
+| `MAGIC_MAIL_ENABLE_DEBUG_ENDPOINT`    | no                                                       | `true` enables `GET /magic-mail/analytics/debug` outside production             |
 
----
+Without `MAGIC_MAIL_ENCRYPTION_KEY`, a development key derived from `ADMIN_JWT_SECRET`/`APP_KEYS` is used only when `NODE_ENV` is unset, `development` or `test`; rotating those secrets then makes stored credentials unreadable. Any other environment (for example `staging`) refuses to start without the key.
 
-## 📚 Advanced Topics
+Also set Strapi's `server.url` to your public URL (OAuth redirects, tracking links) and `server.proxy: true` behind a reverse proxy.
 
-### Custom Routing Logic
+### Plugin config
 
-Create complex routing rules:
+All keys are optional and validated at startup (an invalid value stops Strapi with a clear message):
 
 ```javascript
-// Rule 1: VIP customers via a priority account
-{
-  name: "VIP Customer Emails",
-  matchType: "recipient",
-  matchValue: "@vip-customers.com",
-  accountName: "Priority SMTP",
-  fallbackAccountName: "Gmail OAuth",
-  priority: 10,
-  isActive: true
-}
+// config/plugins.js
+module.exports = () => ({
+  'magic-mail': {
+    enabled: true,
+    config: {
+      debug: false, // info/debug logs; warnings and errors are always logged
+      contentApi: {
+        allowUserRoles: false, // true = users-permissions roles may use the send routes
+      },
+      quotaTimezone: 'UTC', // IANA zone for hourly/daily quota windows
+      tracking: {
+        eventRetentionDays: 90, // raw open/click events; 0 = keep forever
+        linkTtlDays: 180, // tracked links redirect this long; 0 = forever
+        logRetentionDays: 0, // email logs (with events and links); 0 = keep forever
+        maxLinksPerEmail: 100, // further links stay untracked
+        allowedLinkHosts: [], // e.g. ['example.com'] (subdomains included)
+        anonymizeIp: true, // store /24 (IPv4) or /48 (IPv6) only
+      },
+      designer: {
+        projectId: null, // optional Unlayer project id
+        scriptUrl: null, // optional https URL of the Unlayer loader
+        version: null, // optional exact Unlayer build
+      },
+    },
+  },
+});
+```
 
-// Rule 2: Password resets via fast account
-{
-  name: "Password Reset Emails",
-  matchType: "subject",
-  matchValue: "Password Reset",
-  accountName: "Fast Gmail",
-  priority: 9,
-  isActive: true
-}
+`allowedLinkHosts` empty means: every host may be click-tracked for admin, service and native sends, and **no** host for Content-API sends. When the list is set, it applies to all sends.
 
-// Rule 3: Marketing via SendGrid
-{
-  name: "Marketing Campaigns",
-  matchType: "emailType",
-  matchValue: "marketing",
-  accountName: "SendGrid Marketing",
-  priority: 8,
-  isActive: true
-}
-```
+### Admin settings
 
-### DKIM Configuration (Advanced)
+**Settings → MagicMail → Plugin Settings**, stored in the database (`GET`/`PUT /magic-mail/settings`):
 
-For custom domains with SMTP:
+| Setting                       | Default | Effect                                                                      |
+| ----------------------------- | ------- | --------------------------------------------------------------------------- |
+| Link tracking / Open tracking | on      | Rewrite links / add the open pixel                                          |
+| Tracking base URL             | empty   | Public base for tracking URLs (else `server.url`)                           |
+| Default from name             | empty   | Display name when neither the account nor the caller sets one               |
+| Default from email            | empty   | Reference only; emails always go out from the selected account's address    |
+| Unsubscribe header            | on      | Send `List-Unsubscribe` for every email type and use the plugin-wide URL    |
+| Unsubscribe URL               | empty   | Plugin-wide unsubscribe URL; `{{email}}` is replaced per recipient          |
+| `trackingFallbackUrl` (API)   | empty   | Where expired or unknown tracking links redirect; empty shows a static page |
 
-**1. Generate DKIM Keys:**
-```bash
-openssl genrsa -out dkim_private.pem 1024
-openssl rsa -in dkim_private.pem -pubout -out dkim_public.pem
-```
+### Account fields
 
-**2. Add to DNS:**
-```
-default._domainkey.yourdomain.com TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA..."
-```
+Name (unique), description, provider, from email and name, reply-to, encrypted credentials (SMTP password, API key, OAuth tokens, optional DKIM key), daily and hourly limit (0 = unlimited), priority (1 to 10, higher preferred), active and primary flags.
+
+### Service API
 
-**3. Add to MagicMail SMTP Account:**
 ```javascript
-// In account config (edit account → credentials):
-{
-  host: "smtp.yourdomain.com",
-  port: 587,
-  user: "...",
-  pass: "...",
-  dkim: {
-    domainName: "yourdomain.com",
-    keySelector: "default",
-    privateKey: "-----BEGIN PRIVATE KEY-----\n..."
-  }
-}
-```
+const router = strapi.plugin('magic-mail').service('email-router');
+await router.send({ to, subject, html });
 
-### Rate Limit Strategy
+const accounts = await strapi.plugin('magic-mail').service('account-manager').getAllAccounts();
 
-**Best practices for high-volume sending:**
+// Test one account (also works for inactive accounts)
+await strapi
+  .plugin('magic-mail')
+  .service('account-manager')
+  .testAccount(accountDocumentId, 'you@example.com', { priority: 'high', type: 'marketing' });
 
-```javascript
-// Account Setup:
-// Account A: Priority 10, Daily Limit: 500
-// Account B: Priority 9, Daily Limit: 500  
-// Account C: Priority 8, Daily Limit: 500
-// → Total capacity: 1500 emails/day
-
-// MagicMail automatically:
-// 1. Uses Account A until limit hit
-// 2. Switches to Account B
-// 3. Switches to Account C
-// 4. All transparent to your code!
+const designer = strapi.plugin('magic-mail').service('email-designer');
+const rendered = await designer.renderTemplate(100, { user: { firstName: 'Ada' } });
+const stats = await designer.getStats(); // { total, active, inactive, byCategory, ... }
 ```
 
 ---
 
-## 🤝 Contributing
+## Troubleshooting
 
-We welcome contributions!
+**Email not received**
 
-**Found a bug?** [Open an issue](https://github.com/Schero94/MagicMail/issues)
+1. Look for `[magic-mail]` warnings and errors in the Strapi log (always logged; set `debug: true` for details).
+2. Check the account: active, the **Test** action succeeds, today's usage is below the limit.
+3. Check **Analytics**: the log shows status, the account used and, for failures, the error.
+4. Check the spam folder; new senders often land there.
 
-**Have a feature idea?** [Start a discussion](https://github.com/Schero94/MagicMail/discussions)
+**"Could not connect to the mail server"** on an SMTP test: check host, port and TLS (`587` STARTTLS, `465` with _Use SSL/TLS encryption_). Self-signed certificates are rejected unless `allowInsecure` is set on a non-production or loopback host.
 
-**Want to contribute code?**
-1. Fork the repo
-2. Create a feature branch
-3. Make your changes
-4. Submit a pull request
+**OAuth popup fails or reports a redirect mismatch**
 
----
+- Register exactly the redirect URI the wizard shows.
+- Production: `server.url` must be public `https`.
+- Admin on its own host: set `admin.url`.
+- Microsoft: all five delegated permissions with admin consent, correct tenant ID, client secret not expired.
+- Several Strapi instances: use sticky admin sessions.
 
-##  License
+**Edit wizard says "Stored credentials cannot be decrypted"**: the encryption key changed. Set the old key in `MAGIC_MAIL_ENCRYPTION_KEY_PREVIOUS`, or enter the secrets again.
 
-**MIT License**
+**Content API returns 403**: use an API token with the `send`/`sendMessage` action; users-permissions roles are rejected unless `contentApi.allowUserRoles` is true.
 
-Copyright © 2025 Schero D.
+**Content API returns 400**: the response `details` name the field. Common causes: unknown fields (for example `phoneNumber` or `channel` from 3.x), `path` attachments, a `from` that is not the account's address.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+**Links are not tracked**: set _Tracking base URL_ or `server.url` to a public URL; for Content-API sends add the link hosts to `tracking.allowedLinkHosts`. Authentication links are never tracked.
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+**Visual designer does not load**: add `https://editor.unlayer.com` to `script-src` and `frame-src` (see [Content Security Policy](#content-security-policy-for-the-visual-editor)). The **Plain Text** tab works without it.
 
-MagicMail is fully free and open source. Every feature is available to everyone
-with no license key, tier, activation, or usage limit.
+**DMARC failures with a custom domain**: publish SPF (for example `v=spf1 include:_spf.google.com ~all`), add DKIM (provider or SMTP DKIM config) and a DMARC record. MagicMail always sends from the account's address, which keeps alignment.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+**"Too many requests"**: the send routes allow 60 requests per minute per token, test sends 10 per minute per admin. Also check provider limits (for example Gmail 500/day for free accounts, 2,000/day for Workspace).
 
 ---
 
-## 🙏 Credits
+## Upgrading to 4.0.0
 
-**Built with:**
-- [Strapi v5](https://strapi.io) - Headless CMS
-- [Nodemailer](https://nodemailer.com) - SMTP client
-- [Heroicons](https://heroicons.com) - Beautiful icons
-- [styled-components](https://styled-components.com) - CSS-in-JS
+4.0.0 is a major release with security and correctness changes. **Back up the database first**: credentials are re-encrypted in a format 3.x cannot read, and two legacy routing-rule columns are dropped. The full list with migration notes is in [CHANGELOG.md](./CHANGELOG.md).
 
-**Inspired by:**
-- Professional email requirements
-- Multi-tenant application needs
-- Developer experience first
+Breaking changes and what to do:
 
----
-
-## 💬 Support
+1. **Node.js 22.12+** and **`@strapi/plugin-users-permissions`** are required. Peer ranges are `^5.57.0`.
+2. **Encryption key everywhere but development/test.** Set `MAGIC_MAIL_ENCRYPTION_KEY` for staging too. The constant fallback key is gone.
+3. **Email only.** The non-email messaging routes and service methods are removed and `/send` no longer accepts `phoneNumber` (both already in 3.1.0); `/send-message` no longer accepts `channel` (400 for unknown fields).
+4. **Content API needs API tokens.** Switch callers to an API token, or set `contentApi.allowUserRoles: true`. `userId` must reference an existing user.
+5. **Admin capabilities.** Grant `read`, `manage` and `test-send` in addition to `access` ([permission guide](./docs/permission-migration.md)).
+6. **Attachments:** replace `path`/`href` with `content`.
+7. **`from` and headers:** `from` must be the sending account's address; custom headers must be `X-*` or one of the allowed names.
+8. **Explicit `accountName` is never replaced**; a template's category now sets the email type when `type` is omitted.
+9. **Tracking needs a public URL.** Set _Tracking base URL_ or `server.url`; Content-API emails are click-tracked only for `tracking.allowedLinkHosts`; links expire after 180 days, events after 90 days, IPs are truncated.
+10. **Secrets:** the placeholder is `********`; changing host, user, provider or OAuth client requires the secret again.
+11. **OAuth:** in production the redirect URI comes from `server.url` (public `https`). Authorizations in progress during the upgrade must be restarted.
+12. **Users & Permissions templates** need the users-permissions email-template permissions and only accept the listed placeholders.
+13. **Visual designer:** add the CSP directives and the Media Library upload permission.
+14. **Removed:** provider `ses` (never had an adapter), two legacy messaging columns of the routing-rule table (names in the changelog), the admin keep-alive polling.
 
-**Need help?**
-- 📖 [Documentation](https://github.com/Schero94/Magic-Mail#readme)
-- 🐛 [Report Issues](https://github.com/Schero94/Magic-Mail/issues)
-- 💡 [Feature Requests](https://github.com/Schero94/Magic-Mail/discussions)
+---
 
+## Development
 
----
+```bash
+npm ci --ignore-scripts
+npm run lint
+npm run format:check
+npm test
+npm run build
+npm run verify
+npm run verify:runtime
+```
 
-## ⭐ Show Your Support
+`npm run watch` (or `npm run watch:link` with yalc) rebuilds the admin and the server bundle on change. Pull requests run the same checks on Node 22 and 24.
 
-If MagicMail helps your project, please:
-- ⭐ Star the repo on [GitHub](https://github.com/Schero94/Magic-Mail)
-- 📢 Share with your team
-- 🐦 Tweet about it
+- **Bug?** [Open an issue](https://github.com/Schero94/Magic-Mail/issues)
+- **Idea?** [Start a discussion](https://github.com/Schero94/Magic-Mail/discussions)
 
----
+### Dependency audits
 
-## Dependency audits
+Run `npm audit` from your Strapi project root to check the complete installed tree; npm applies overrides from the root project only.
 
-Run `npm audit` from the Strapi project root to check the complete installed dependency tree. npm applies dependency overrides from the root project manifest, not from this plugin's manifest.
+Known host-side advisory: `npm audit --omit=dev` in this repository reports GHSA-mrhx-c7xc-m3w5 (zod < 4.6.6) inside `@strapi/utils`, which the Strapi host provides. MagicMail validates every request with its own patched zod (`^4.6.7`) and bounds all collections, so the advisory is not reachable through MagicMail inputs. It disappears once your Strapi version ships a fixed zod.
 
 ---
 
-**Made for the Strapi Community**
+## License
+
+MIT License, Copyright © 2025 Schero D. See [LICENSE](./LICENSE).
 
-**MagicMail - Because email management should be magical, not painful.**
+Built with [Strapi](https://strapi.io), [Nodemailer](https://nodemailer.com), [Unlayer](https://unlayer.com) / [react-email-editor](https://github.com/unlayer/react-email-editor), [Heroicons](https://heroicons.com) and [styled-components](https://styled-components.com).