strapi-plugin-magic-mail 3.0.4 → 4.0.0

package/README.md

@@ -1,1641 +1,930 @@
-# 📧 MagicMail - Email Business Suite for Strapi v5
+# MagicMail: email accounts, routing and templates for Strapi 5
 
-> **Professional-grade multi-account email management with smart routing, OAuth 2.0 support, and complete security compliance — 100% free and open source**
+Project site: https://schero94.github.io/Magic-Mail/
 
 [![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.30.1-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)
 
-> 💚 **Fully free & open source (MIT).** Every feature is included for everyone — no license key, no activation, no paid tiers, and no usage limits.
+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.
 
----
-
-## 🌟 Why MagicMail?
-
-**Stop fighting with .env files and email configuration!** MagicMail brings professional email management to Strapi v5 with:
-
-- **100% Free & Open Source** - Every feature included, no license key, tiers, or limits (MIT)
-- **6 Email Providers** - Gmail, Microsoft 365, Yahoo, SMTP, SendGrid, Mailgun
-- **WhatsApp Messaging** - Send messages via WhatsApp (FREE!) 
-- **OAuth 2.0 Authentication** - No passwords needed for Gmail, Microsoft, Yahoo
-- **Smart Routing Rules** - Route emails by type, recipient, subject, or custom conditions
-- **WhatsApp Fallback** - Auto-send via WhatsApp if email fails
-- **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
-
----
-
-## 📸 Screenshots
-
-### Email Accounts Dashboard
-![Email Accounts Dashboard](pics/EmailAccountDashboard.png)
-*Manage unlimited email accounts with live stats and real-time monitoring*
-
-### Add Email Account - Step 1
-![Add Account Step 1](pics/Emailaddccount1.png)
-*Choose from 6 different email providers with OAuth 2.0 support*
-
-### Add Email Account - Step 2
-![Add Account Step 2](pics/emailaddaccount2.png)
-*Configure SMTP settings or connect with OAuth*
-
-### Add Email Account - Step 3
-![Add Account Step 3](pics/emailaddaccount3.png)
-*Complete setup with rate limits and test connection*
-
-### Email Templates
-![Email Templates](pics/Templates.png)
-*Create and manage email templates with the visual designer*
+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.
 
-### Email Designer
-![Email Designer](pics/emailDesigner.png)
-*Drag-and-drop email editor with real-time preview*
+MagicMail sends **email only**. It is MIT-licensed, has no license key, tiers or usage limits.
 
-### Template Version History
-![Version History](pics/emailVersionHistory.png)
-*Track changes and restore previous template versions*
+**At a glance**
 
-### Template Send Test
-![Send Test](pics/emailTemplateSendTest.png)
-*Test your templates before sending to production*
+- 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
 
-### Routing Rules & Templates
-![Routing Rules](pics/RoutingEmailTemplates.png)
-*Define intelligent routing rules based on email type, recipient, subject*
+## Contents
 
-### Email Analytics
-![Email Analytics](pics/emailAnalytics.png)
-*Track email performance with detailed analytics and statistics*
-
-### Code Integration
-![Code Snippet](pics/codesnippet.png)
-*Simple API integration with your Strapi application*
+- [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)
 
 ---
 
-## WhatsApp Messaging (NEW!)
+## Screenshots
 
-MagicMail now includes **FREE WhatsApp messaging** - send messages directly from your Strapi application!
+The screenshots show synthetic demo data (`example.test` addresses) on Strapi 5.61.
 
-### Why WhatsApp?
+### Email accounts
 
-| Feature | Email | WhatsApp |
-|---------|-------|----------|
-| **Open Rate** | ~20% | ~98% |
-| **Delivery Speed** | Minutes | Instant |
-| **Spam Folder Risk** | High | None |
-| **User Preference** | Declining | Growing |
-| **Cost** | Varies | FREE |
+![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._
 
-### Quick Setup (4 Steps)
+### Account wizard
 
-1. **Navigate** to Admin Panel -> MagicMail -> WhatsApp
-2. **Connect** - Scan QR code with WhatsApp mobile app
-3. **Verify** - Check connection status shows "Connected"
-4. **Send** - Start sending messages programmatically!
+![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._
 
-### Sending WhatsApp Messages
+### Routing rules
 
-**Method 1: Direct WhatsApp Send**
+![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._
 
-```javascript
-// Send WhatsApp message directly
-await strapi.plugin('magic-mail').service('whatsapp').sendMessage(
-  '+491234567890',  // Phone number with country code
-  'Hello! This is a test message from MagicMail.'
-);
-```
+### Templates
 
-**Method 2: Unified Messaging API**
+![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._
 
-```javascript
-// Send via unified API - auto-detects channel
-await strapi.plugin('magic-mail').service('email-router').sendMessage({
-  channel: 'whatsapp',  // or 'email' or 'auto'
-  phoneNumber: '+491234567890',
-  message: 'Your order #12345 has been shipped!'
-});
+### Template editor
 
-// Auto-detect: sends WhatsApp if phoneNumber provided, email if to provided
-await strapi.plugin('magic-mail').service('email-router').sendMessage({
-  channel: 'auto',
-  phoneNumber: '+491234567890',  // Has phone -> WhatsApp
-  message: 'Shipping notification'
-});
+![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._
 
-await strapi.plugin('magic-mail').service('email-router').sendMessage({
-  channel: 'auto',
-  to: 'user@example.com',  // Has email -> Email
-  subject: 'Shipping Notification',
-  message: 'Your order has been shipped!'
-});
-```
+### Analytics
 
-**Method 3: REST API**
+![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._
 
-```javascript
-// POST /api/magic-mail/send-whatsapp
-await fetch('/api/magic-mail/send-whatsapp', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    'Authorization': 'Bearer YOUR_STRAPI_API_TOKEN'
-  },
-  body: JSON.stringify({
-    phoneNumber: '+491234567890',
-    message: 'Hello from MagicMail!'
-  })
-});
+### Plugin settings
 
-// POST /api/magic-mail/send-message (unified)
-await fetch('/api/magic-mail/send-message', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    'Authorization': 'Bearer YOUR_STRAPI_API_TOKEN'
-  },
-  body: JSON.stringify({
-    channel: 'whatsapp',
-    phoneNumber: '+491234567890',
-    message: 'Order confirmed!'
-  })
-});
-```
+![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._
 
-### WhatsApp Use Cases
+### Dark mode and mobile
 
-**1. Email Fallback**
-If email delivery fails, automatically send via WhatsApp:
+![Analytics in dark mode](https://raw.githubusercontent.com/Schero94/Magic-Mail/main/pics/emailAnalyticsDark.png)
 
-```javascript
-// In Routing Rules, enable "WhatsApp Fallback"
-// Set "WhatsApp Phone Field" to 'phoneNumber'
+| 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) |
 
-await strapi.plugin('magic-mail').service('email-router').send({
-  to: 'user@example.com',
-  phoneNumber: '+491234567890',  // Fallback phone
-  subject: 'Important Update',
-  html: '<h1>Update</h1>',
-  type: 'transactional'
-});
-
-// If email fails -> auto-sends via WhatsApp!
-```
+---
 
-**2. Admin Notifications**
-Get instant WhatsApp alerts for critical events:
+## Quick start
 
-```javascript
-// Example: Notify admin when email quota exceeded
-const adminPhone = '+4917612345678';
+### Requirements
 
-await strapi.plugin('magic-mail').service('whatsapp').sendMessage(
-  adminPhone,
-  '[ALERT] Email quota exceeded for SendGrid account!'
-);
-```
+- 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))
 
-**3. Urgent Transactional Messages**
-Send time-sensitive messages instantly:
+### 1. Install
 
-```javascript
-// OTP/Verification codes
-await strapi.plugin('magic-mail').service('whatsapp').sendMessage(
-  userPhone,
-  `Your verification code: 123456\n\nValid for 5 minutes.`
-);
-
-// Order updates
-await strapi.plugin('magic-mail').service('whatsapp').sendMessage(
-  customerPhone,
-  `Order #${orderId} is out for delivery!\nTrack: ${trackingUrl}`
-);
+```bash
+npm install strapi-plugin-magic-mail
 ```
 
-### WhatsApp Status API
+### 2. Enable
 
 ```javascript
-// Check connection status
-const status = await strapi.plugin('magic-mail').service('whatsapp').getStatus();
-// { isConnected: true, phoneNumber: '+49...', name: 'Business Account' }
-
-// Check if phone number is on WhatsApp
-const exists = await strapi.plugin('magic-mail').service('whatsapp').checkNumber('+491234567890');
-// { exists: true, jid: '491234567890@s.whatsapp.net' }
+// config/plugins.js (or config/plugins.ts with export default)
+module.exports = () => ({
+  'magic-mail': {
+    enabled: true,
+  },
+});
 ```
 
-### Integration with Magic-Link Plugin
-
-When both **MagicMail** and **Magic-Link** are installed:
-
-- Magic-Link automatically uses MagicMail's WhatsApp service
-- Only ONE WhatsApp connection needed (managed here in MagicMail)
-- Send magic links via WhatsApp from Magic-Link settings
-- Unified WhatsApp management for all plugins
-
----
-
-## Quick Start
-
-### Installation
-
-Requires Node.js 20.19 or newer and Strapi 5.50 or newer.
+### 3. Set the encryption key
 
 ```bash
-npm install strapi-plugin-magic-mail
-# or
-yarn add strapi-plugin-magic-mail
+# Generate once and keep it with your other secrets
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
 ```
 
-### Enable Plugin
-
-Create or update `config/plugins.ts`:
-
-```typescript
-export default () => ({
-  'magic-mail': {
-    enabled: true,
-  },
-});
+```env
+MAGIC_MAIL_ENCRYPTION_KEY=<the generated value>
 ```
 
-### Build & Start
+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
-
-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! 🎉
+### 5. Add an account and send a test
 
----
+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
-
-```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',
-    },
-  ],
-});
-```
-
-**Supported attachment formats:**
-- ✅ PDF, Word, Excel, PowerPoint
-- ✅ Images (PNG, JPG, GIF, WebP)
-- ✅ Text files (TXT, CSV, JSON)
-- ✅ Archives (ZIP, RAR)
-- ✅ Any file type!
-
-### Advanced: Priority & Marketing Emails
-
-```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
-});
-
-// 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!
-});
-```
-
----
-
-## 🎨 Email Designer Suite (NEW!)
-
-**Design beautiful emails visually with the integrated email designer!**
-
-### ✨ Features
-
-Every Email Designer feature is included for free:
+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.
 
-| Feature | Included |
-|---------|----------|
-| **Visual Designer** | ✅ |
-| **Unlimited Templates** | ✅ |
-| **Drag & Drop + Mustache** | ✅ |
-| **Import / Export** | ✅ |
-| **Template Versioning** | ✅ |
-| **Email Analytics** | ✅ |
+### Option 3: HTTP
 
-### 📧 Creating Email Templates
+See [Content API](#content-api) for `POST /api/magic-mail/send` and `/send-message`.
 
-**1. Navigate to Email Templates Tab**
+### Send options
 
-Go to **MagicMail → Email Templates** in the admin panel.
+The same fields work for the router, the Strapi email service and `POST /api/magic-mail/send`.
 
-**2. Create New Template**
+| 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                                                                                                                                                       |
 
-Click **"Create Template"** and use the visual designer to build your email.
+### Attachments
 
-**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
+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.
 
-Every time you save a template, a new version is created automatically:
+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.
 
-```javascript
-// Get all versions
-const versions = await strapi
-  .plugin('magic-mail')
-  .service('email-designer')
-  .getVersions(templateId);
+**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.
 
-// Restore old version
-await strapi
-  .plugin('magic-mail')
-  .service('email-designer')
-  .restoreVersion(templateId, versionId);
-```
-
-### 📦 Import/Export Templates
+### Gmail (OAuth 2.0)
 
-**Export all templates:**
-
-```javascript
-const templates = await strapi
-  .plugin('magic-mail')
-  .service('email-designer')
-  .exportTemplates();
+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.
 
-// Save to file
-fs.writeFileSync('templates.json', JSON.stringify(templates, null, 2));
-```
+Scopes: `https://www.googleapis.com/auth/gmail.send`, `https://www.googleapis.com/auth/userinfo.email`, `openid`. Mail is sent through the Gmail API.
 
-**Import templates:**
+### Microsoft 365 (OAuth 2.0)
 
-```javascript
-const templates = JSON.parse(fs.readFileSync('templates.json'));
+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**.
 
-const results = await strapi
-  .plugin('magic-mail')
-  .service('email-designer')
-  .importTemplates(templates);
+The tenant ID must be a GUID, a domain, `common`, `organizations` or `consumers`. Mail is sent through Microsoft Graph `sendMail`.
 
-console.log(`Imported ${results.filter(r => r.success).length} templates`);
-```
+### Yahoo Mail (OAuth 2.0)
 
-### 🎨 Visual Designer Features
+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**.
 
-**Powered by Unlayer Email Editor:**
+Mail is sent over SMTP with XOAUTH2.
 
-- ✅ 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
+### SMTP
 
-### 📊 Template Statistics
+| 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                       |
 
-```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
-// }
-```
+Common hosts: Gmail `smtp.gmail.com:587` (app password), Outlook.com `smtp-mail.outlook.com:587`, Microsoft 365 `smtp.office365.com:587`.
 
-### 🚀 Best Practices
+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.
 
-**1. Use Template Categories**
-```javascript
-// Set category when creating template
-category: 'marketing' // Auto-routes to marketing account
-```
+Optional DKIM signing (account config):
 
-**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' } });
-
-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
-
-### Gmail OAuth Setup
+## Routing rules and quotas
 
-**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
+Routing rules send an email through a specific account when it matches a condition. Manage them under **MagicMail → Routing Rules**.
 
-**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! ✅
+| 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                                                                  |
 
-**Required Scopes:**
-- `https://www.googleapis.com/auth/gmail.send`
-- `https://www.googleapis.com/auth/userinfo.email`
+Examples:
 
----
-
-### 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
-```
+| 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       |
 
-**3. API Permissions**
+**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.
 
-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
+**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.
 
-**4. Grant Admin Consent** (Required!)
+**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.
 
-**5. Create Client Secret**
-1. **Certificates & secrets** → **New client secret**
-2. Copy the **VALUE** (not the Secret ID)
-3. Store it securely!
+**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.
 
-**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
-```
+## Templates and the visual editor
 
-**3. API Permissions**
-- ✅ `Mail` - Send and manage emails
-- ✅ `OpenID Connect` - User authentication
+Everything in the designer is included, with no tiers:
 
-**4. In MagicMail**
-1. Choose "Yahoo Mail OAuth" provider
-2. Paste Client ID and Client Secret
-3. Click "Connect with Yahoo"
-4. Done! ✅
+| Feature                           | Included |
+| --------------------------------- | -------- |
+| **Visual Designer (Unlayer)**     | ✅       |
+| **Plain HTML/Text editing**       | ✅       |
+| **Unlimited Templates**           | ✅       |
+| **Mustache Variables**            | ✅       |
+| **Import / Export**               | ✅       |
+| **Template Versioning**           | ✅       |
+| **Users & Permissions templates** | ✅       |
 
----
+### Creating templates
 
-### SMTP Setup (Universal)
+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:
 
-**Works with ANY SMTP server:**
-
-```
-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' },
+    },
+  });
 ```
 
----
+`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.
 
-### SendGrid Setup
+### Categories
 
-**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
+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.
 
-**2. In MagicMail**
-1. Choose "SendGrid" provider
-2. Paste API Key
-3. Done! ✅
+### Versions, import and export
 
----
-
-### 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
+- 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.
 
-**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
-
----
-
-## 📊 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
-
----
-
-## 🔧 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:
-
-**Basic Settings:**
-- Name (unique identifier)
-- Description
-- Provider type
-- From Email
-- From Name
-- Reply-To Email
+### Users & Permissions templates
 
-**Security:**
-- OAuth credentials (encrypted)
-- SMTP credentials (encrypted)
-- API keys (encrypted)
-- DKIM configuration (optional)
+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.
 
-**Rate Limiting:**
-- Daily email limit (0 = unlimited)
-- Hourly email limit (0 = unlimited)
-- Priority (1-10, higher = preferred)
+### The visual editor (Unlayer) and privacy
 
-**Status:**
-- Active/Inactive
-- Primary account designation
+The visual designer embeds the [Unlayer](https://unlayer.com) editor through `react-email-editor`. What that means for you:
 
----
-
-## 🎨 API Reference
+- 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.
 
-### 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();
-```
-
-### Test Account
-
-```javascript
-const result = await strapi.plugin('magic-mail').service('account-manager').testAccount(
-  accountId,
-  'test@example.com',
-  {
-    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)
+### Content Security Policy for the visual editor
 
-### Test via Code
+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
-// Test email with all security features
-await strapi.plugin('magic-mail').service('account-manager').testAccount(
-  accountId,
-  'your-email@example.com',
+module.exports = [
+  'strapi::logger',
+  'strapi::errors',
   {
-    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
+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.
 
-**To verify security headers are applied:**
-
-**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
-
-### Dashboard Stats
+## Content API
 
-**Global Stats:**
-- Emails sent today (all accounts)
-- Total emails sent (lifetime)
-- Active accounts count
+| 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                                                                |
 
-**Per-Account Stats:**
-- Emails sent today
-- Total emails sent
-- Rate limit usage (visual progress bars)
-- Last used timestamp
-- Success/failure rate
+### The API token rule
 
-### Email Logging
+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.
 
-Every email is logged with:
-- Recipient
-- Sender
-- Subject
-- Account used
-- Status (sent/failed)
-- Timestamp
-- Email type
-- Error message (if failed)
+To let users-permissions roles send as well (the pre-4.0 behaviour):
 
-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!
-   ```
-
-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
-
-**No configuration needed - it just works!** 🎉
+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).
 
----
-
-## 🚨 Troubleshooting
+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).
 
-### Email Not Received
+### Example: send
 
-**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
+### Example: send-message
 
-### DMARC Failures
-
-**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
 
+```json
+{
+  "data": {
+    "documentId": "…",
+    "name": "Marketing campaigns",
+    "matchType": "emailType",
+    "priority": 50,
+    "…": "…"
+  },
+  "message": "Routing rule created successfully"
+}
 ```
-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
-```
-
----
 
-## 🎯 Use Cases
+`matchType` is one of `emailType`, `recipient`, `subject`, `template`, `custom`. An unknown `accountName` or `fallbackAccountName` returns 400.
 
-### Multi-Tenant SaaS
+### Example: list accounts
 
-```javascript
-// Each tenant gets their own email account
-// Route by custom field:
-
-// Routing Rule:
-// Match Type: Custom Field
-// Match Value: tenant-123
-// Target Account: Tenant 123 Gmail
-
-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
-
-### Environment Variables
+## Permissions
 
-```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
-```
+MagicMail registers four admin actions under **Settings → Administration Panel → Roles → Plugins → MagicMail**:
 
-### OAuth Callback URLs
+| 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                    |
 
-**Update redirect URIs in your OAuth apps:**
+Typical roles:
 
-**Gmail:**
-```
-https://yourdomain.com/magic-mail/oauth/gmail/callback
-```
+- **Read-only:** `access` + `read`
+- **Editor:** `access` + `read` + `manage`
+- **Tester:** `access` + `read` + `test-send`
 
-**Microsoft:**
-```
-https://yourdomain.com/magic-mail/oauth/microsoft/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).
 
-**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
-}
-
-// Rule 2: Password resets via fast account
-{
-  name: "Password Reset Emails",
-  matchType: "subject",
-  matchValue: "Password Reset",
-  accountName: "Fast Gmail",
-  priority: 9,
-  isActive: true
-}
-
-// Rule 3: Marketing via SendGrid
-{
-  name: "Marketing Campaigns",
-  matchType: "emailType",
-  matchValue: "marketing",
-  accountName: "SendGrid Marketing",
-  priority: 8,
-  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
+      },
+    },
+  },
+});
 ```
 
-### DKIM Configuration (Advanced)
+`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.
 
-For custom domains with SMTP:
+### Admin settings
 
-**1. Generate DKIM Keys:**
-```bash
-openssl genrsa -out dkim_private.pem 1024
-openssl rsa -in dkim_private.pem -pubout -out dkim_public.pem
-```
+**Settings → MagicMail → Plugin Settings**, stored in the database (`GET`/`PUT /magic-mail/settings`):
 
-**2. Add to DNS:**
-```
-default._domainkey.yourdomain.com TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA..."
-```
+| 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 |
 
-**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..."
-  }
-}
-```
+### Account fields
 
-### Rate Limit Strategy
+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.
 
-**Best practices for high-volume sending:**
+### Service API
 
 ```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 router = strapi.plugin('magic-mail').service('email-router');
+await router.send({ to, subject, html });
 
----
-
-## 🤝 Contributing
-
-We welcome contributions!
-
-**Found a bug?** [Open an issue](https://github.com/Schero94/MagicMail/issues)
+const accounts = await strapi.plugin('magic-mail').service('account-manager').getAllAccounts();
 
-**Have a feature idea?** [Start a discussion](https://github.com/Schero94/MagicMail/discussions)
+// 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' });
 
-**Want to contribute code?**
-1. Fork the repo
-2. Create a feature branch
-3. Make your changes
-4. Submit a pull request
+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, ... }
+```
 
 ---
 
-##  License
+## Troubleshooting
 
-**MIT License**
+**Email not received**
 
-Copyright © 2025 Schero D.
+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.
 
-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:
+**"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.
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+**OAuth popup fails or reports a redirect mismatch**
 
-MagicMail is fully free and open source. Every feature is available to everyone
-with no license key, tier, activation, or usage limit.
+- 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.
 
-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.
+**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.
 
----
+**Content API returns 403**: use an API token with the `send`/`sendMessage` action; users-permissions roles are rejected unless `contentApi.allowUserRoles` is true.
 
-## 🙏 Credits
+**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.
 
-**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
+**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.
 
-**Inspired by:**
-- Professional email requirements
-- Multi-tenant application needs
-- Developer experience first
+**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.
 
----
+**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.
 
-## 💬 Support
+**"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).
 
-**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)
+---
 
+## Upgrading to 4.0.0
 
----
+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).
 
-## ⭐ Show Your Support
+Breaking changes and what to do:
 
-If MagicMail helps your project, please:
-- ⭐ Star the repo on [GitHub](https://github.com/Schero94/Magic-Mail)
-- 📢 Share with your team
-- 🐦 Tweet about it
+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.
 
 ---
 
-## 🔒 Security Advisories & Dependency Overrides
-
-MagicMail's direct dependencies are audited on every release, but two
-transitive paths are governed by upstream packages we do not control.
-If your own `npm audit` flags either of them, add the matching entry
-to your **Strapi project's** `package.json` (not this plugin's — npm
-`overrides` only take effect on the root project):
+## Development
 
-```jsonc
-{
-  "overrides": {
-    // GHSA-xq3m-2v4x-88gg — protobufjs <7.5.5 arbitrary code execution.
-    // Reaches us via baileys → libsignal → protobufjs. We already ship
-    // this override for local plugin development; apply it in your
-    // Strapi project so the fix propagates to the installed tree.
-    "protobufjs": "^7.5.5"
-  }
-}
+```bash
+npm ci --ignore-scripts
+npm run lint
+npm run format:check
+npm test
+npm run build
+npm run verify
+npm run verify:runtime
 ```
 
-After editing `package.json`, run:
+`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.
 
-```bash
-rm -rf node_modules package-lock.json
-npm install
-npm audit
-```
+- **Bug?** [Open an issue](https://github.com/Schero94/Magic-Mail/issues)
+- **Idea?** [Start a discussion](https://github.com/Schero94/Magic-Mail/discussions)
 
-The critical `protobufjs` advisory disappears once the override is in
-place. Remaining `@strapi/design-system → lodash` advisories are
-Strapi-core issues and will clear up automatically when you upgrade
-`@strapi/strapi` to the latest patch release.
+### Dependency audits
 
-If you don't use the WhatsApp delivery feature at all, you can also
-install without the Baileys optional paths via
-`npm install strapi-plugin-magic-mail --ignore-scripts` — the plugin
-already guards every Baileys import with a try/catch and will log
-"WhatsApp features disabled" rather than crash.
+Run `npm audit` from your Strapi project root to check the complete installed tree; npm applies overrides from the root project only.
+
+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).