Thanks for signing up!
',\n});\n\n// โ MagicMail automatically:\n// - Selects best account (via routing rules or priority)\n// - Checks rate limits\n// - Handles failover if needed\n// - Logs the email\n// - Updates statistics\n```\n\n**Benefits:**\n- โ **Zero code changes** - Existing plugins work automatically\n- โ **Email Designer compatible** - Works with strapi-plugin-email-designer-5\n- โ **Fallback safe** - Falls back to original email service if MagicMail fails\n- โ **Drop-in replacement** - Just enable and go!\n\n### Method 2: Direct MagicMail API\n\nFor explicit control over account selection:\n\n```javascript\n// Force a specific account\nawait strapi.plugin('magic-mail').service('email-router').send({\n to: 'customer@example.com',\n subject: 'Order Confirmation',\n html: 'Thanks for joining {{company.name}}
\n```\n\n**4. Save & Use**\n\nEach template gets a unique **Reference ID** (e.g., `100`) that you use when sending.\n\n### ๐ Sending Templated Emails\n\n**Method 1: Using Template ID**\n\n```javascript\n// Send email using template\nawait strapi.plugin('magic-mail').service('email-router').send({\n to: 'user@example.com',\n templateId: 100, // Your template reference ID\n templateData: {\n user: {\n firstName: 'John',\n lastName: 'Doe',\n email: 'john@example.com',\n },\n company: {\n name: 'ACME Corp',\n url: 'https://acme.com',\n },\n orderNumber: '12345',\n orderTotal: '$199.99',\n },\n});\n\n// โ MagicMail will:\n// - Load template #100\n// - Render it with your data (Mustache)\n// - Route via smart routing\n// - Send via best account\n```\n\n**Method 2: Via Strapi Email Service**\n\n```javascript\n// Also works with standard Strapi email service!\nawait strapi.plugin('email').service('email').send({\n to: 'user@example.com',\n templateId: 100,\n templateData: {\n user: { firstName: 'Jane' },\n resetUrl: 'https://yoursite.com/reset?token=xyz',\n },\n});\n```\n\n### ๐ฏ Template Categories\n\nTemplates can be categorized for automatic routing:\n\n- **transactional** - Order confirmations, receipts\n- **marketing** - Newsletters, promotions\n- **notification** - System alerts, updates\n- **custom** - Anything else\n\n**Automatic Routing by Category:**\n\n```javascript\n// Create routing rule: All marketing templates โ SendGrid\n// Then just send:\nawait strapi.plugin('magic-mail').service('email-router').send({\n to: 'subscriber@example.com',\n templateId: 200, // Marketing category template\n templateData: { offer: '50% OFF' },\n});\n// โ Automatically routes via SendGrid (based on category)\n```\n\n### ๐ Template Versioning\n\nEvery time you save a template, a new version is created automatically:\n\n```javascript\n// Get all versions\nconst versions = await strapi\n .plugin('magic-mail')\n .service('email-designer')\n .getVersions(templateId);\n\n// Restore old version\nawait strapi\n .plugin('magic-mail')\n .service('email-designer')\n .restoreVersion(templateId, versionId);\n```\n\n### ๐ฆ Import/Export Templates\n\n**Export all templates:**\n\n```javascript\nconst templates = await strapi\n .plugin('magic-mail')\n .service('email-designer')\n .exportTemplates();\n\n// Save to file\nfs.writeFileSync('templates.json', JSON.stringify(templates, null, 2));\n```\n\n**Import templates:**\n\n```javascript\nconst templates = JSON.parse(fs.readFileSync('templates.json'));\n\nconst results = await strapi\n .plugin('magic-mail')\n .service('email-designer')\n .importTemplates(templates);\n\nconsole.log(`Imported ${results.filter(r => r.success).length} templates`);\n```\n\n### ๐จ Visual Designer Features\n\n**Powered by Unlayer Email Editor:**\n\n- โ Drag & Drop Interface\n- โ Pre-built Content Blocks\n- โ Image Upload & Management\n- โ Custom Fonts & Colors\n- โ Responsive Design\n- โ Mobile Preview\n- โ HTML/Text Editor\n- โ Merge Tags Support\n- โ Save/Load Designs\n\n### ๐ Template Statistics\n\n```javascript\nconst stats = await strapi\n .plugin('magic-mail')\n .service('email-designer')\n .getStats();\n\nconsole.log(stats);\n// {\n// total: 15,\n// active: 12,\n// inactive: 3,\n// byCategory: [\n// { category: 'transactional', count: 8 },\n// { category: 'marketing', count: 4 },\n// { category: 'notification', count: 3 }\n// ],\n// maxTemplates: -1, // unlimited (all features are free)\n// remaining: -1 // unlimited\n// }\n```\n\n### ๐ Best Practices\n\n**1. Use Template Categories**\n```javascript\n// Set category when creating template\ncategory: 'marketing' // Auto-routes to marketing account\n```\n\n**2. Test Templates Before Using**\n```javascript\n// Test render before sending\nconst rendered = await strapi\n .plugin('magic-mail')\n .service('email-designer')\n .renderTemplate(100, { user: { firstName: 'Test' } });\n\nconsole.log(rendered.html); // Preview HTML\n```\n\n**3. Version Control**\n```javascript\n// Template version history is always enabled (free for everyone).\n```\n\n**4. Organize with Tags**\n```javascript\n// Add tags to templates\ntags: ['onboarding', 'welcome-series', 'v2']\n```\n\n---\n\n## ๐ฏ Smart Routing Rules\n\nCreate intelligent routing rules to send emails through specific accounts based on conditions.\n\n### Example Use Cases\n\n**1. Route Marketing Emails via SendGrid:**\n```\nMatch Type: Email Type\nMatch Value: marketing\nTarget Account: SendGrid Marketing\nPriority: 10\n```\n\n**2. Route VIP Customers via Priority SMTP:**\n```\nMatch Type: Recipient\nMatch Value: @vip-customers.com\nTarget Account: Priority SMTP\nFallback Account: Gmail OAuth\nPriority: 9\n```\n\n**3. Route Password Reset Emails:**\n```\nMatch Type: Subject\nMatch Value: Password Reset\nTarget Account: Transactional SMTP\nPriority: 8\n```\n\n### Routing Priority\n\nRules are evaluated from **highest to lowest priority** (1-10):\n- Priority 10 = Evaluated first (most specific rules)\n- Priority 1 = Evaluated last (catch-all rules)\n\nIf no rule matches, the **Primary Account** is used.\n\n---\n\n## ๐ Provider Setup Guides\n\n### Gmail OAuth Setup\n\n**1. Google Cloud Console**\n1. Go to [console.cloud.google.com](https://console.cloud.google.com)\n2. Create a new project or select existing\n3. Enable Gmail API\n4. Create OAuth 2.0 Client ID\n5. Add redirect URI: `http://localhost:1337/magic-mail/oauth/gmail/callback`\n6. Copy Client ID and Client Secret\n\n**2. In MagicMail**\n1. Choose \"Gmail OAuth\" provider\n2. Paste Client ID and Client Secret\n3. Click \"Connect with Google\"\n4. Authorize in popup\n5. Done! โ \n\n**Required Scopes:**\n- `https://www.googleapis.com/auth/gmail.send`\n- `https://www.googleapis.com/auth/userinfo.email`\n\n---\n\n### Microsoft 365 OAuth Setup\n\n**1. Azure Portal**\n1. Go to [portal.azure.com](https://portal.azure.com)\n2. Navigate to **Azure Active Directory โ App registrations**\n3. Click **\"New registration\"**\n4. Name: \"MagicMail\"\n5. Account type: **\"Accounts in this organizational directory only\"**\n6. Copy **Application (client) ID** AND **Directory (tenant) ID**\n\n**2. Add Redirect URI**\n```\nhttp://localhost:1337/magic-mail/oauth/microsoft/callback\n```\n\n**3. API Permissions**\n\nAdd these **Delegated permissions** under Microsoft Graph:\n- โ `Mail.Send` - Send emails as the signed-in user\n- โ `User.Read` - Read user profile\n- โ `offline_access` - Maintain access (refresh tokens)\n- โ `openid` - Sign users in\n- โ `email` - View users' email address\n\n**4. Grant Admin Consent** (Required!)\n\n**5. Create Client Secret**\n1. **Certificates & secrets** โ **New client secret**\n2. Copy the **VALUE** (not the Secret ID)\n3. Store it securely!\n\n**6. In MagicMail**\n1. Choose \"Microsoft OAuth\" provider\n2. Paste **Tenant ID**, **Client ID**, and **Client Secret**\n3. Click \"Connect with Microsoft\"\n4. Authorize\n5. Done! โ \n\n---\n\n### Yahoo Mail OAuth Setup\n\n**1. Yahoo Developer Console**\n1. Go to [developer.yahoo.com/apps](https://developer.yahoo.com/apps)\n2. Click **\"Create an App\"**\n3. Fill in app details\n\n**2. Add Redirect URI**\n```\nhttp://localhost:1337/magic-mail/oauth/yahoo/callback\n```\n\n**3. API Permissions**\n- โ `Mail` - Send and manage emails\n- โ `OpenID Connect` - User authentication\n\n**4. In MagicMail**\n1. Choose \"Yahoo Mail OAuth\" provider\n2. Paste Client ID and Client Secret\n3. Click \"Connect with Yahoo\"\n4. Done! โ \n\n---\n\n### SMTP Setup (Universal)\n\n**Works with ANY SMTP server:**\n\n```\nHost: smtp.gmail.com (or your SMTP server)\nPort: 587 (STARTTLS) or 465 (SSL/TLS)\nUsername: your-email@domain.com\nPassword: your-password (or App Password)\n```\n\n**Popular SMTP Servers:**\n- **Gmail:** `smtp.gmail.com:587` (use App Password!)\n- **Outlook:** `smtp-mail.outlook.com:587`\n- **Office365:** `smtp.office365.com:587`\n- **Custom:** Your own mail server\n\n**Gmail App Password:**\n1. Google Account โ Security โ 2-Step Verification\n2. App passwords โ Generate\n3. Use the 16-character password in MagicMail\n\n**Optional: DKIM Signing**\n\nFor custom domains, you can add DKIM:\n```javascript\n// In config field (advanced users):\n{\n dkim: {\n domainName: 'yourdomain.com',\n keySelector: 'default',\n privateKey: '-----BEGIN PRIVATE KEY-----\\n...'\n }\n}\n```\n\n---\n\n### SendGrid Setup\n\n**1. Get API Key**\n1. Go to [app.sendgrid.com](https://app.sendgrid.com)\n2. Settings โ API Keys โ Create API Key\n3. Scope: **Mail Send** (Full Access)\n4. Copy the API key\n\n**2. In MagicMail**\n1. Choose \"SendGrid\" provider\n2. Paste API Key\n3. Done! โ \n\n---\n\n### Mailgun Setup\n\n**1. Get API Key & Domain**\n1. Go to [app.mailgun.com](https://app.mailgun.com)\n2. Settings โ API Security โ Copy **Private API Key**\n3. Sending โ Domains โ Copy your verified domain\n\n**2. In MagicMail**\n1. Choose \"Mailgun\" provider\n2. Enter **Domain** (e.g., `mg.yourdomain.com`)\n3. Paste **Private API Key**\n4. Done! โ \n\n---\n\n## ๐ก๏ธ Security Features\n\n### Encryption\n- โ **AES-256-GCM** encryption for all credentials\n- โ **No plain text passwords** in database\n- โ **OAuth tokens encrypted** at rest\n- โ **Secure token refresh** mechanism\n\n### Transport Security\n- โ **TLS 1.2+ enforced** (SMTP)\n- โ **Certificate verification** enabled\n- โ **HTTPS only** for API providers\n\n### Email Authentication\n- โ **DKIM signing** (optional for SMTP, automatic for OAuth)\n- โ **SPF validation** support\n- โ **DMARC compliance** - All providers pass DMARC checks\n- โ **Proper Message-ID** generation (RFC 5322)\n\n### Content Security\n- โ **XSS prevention** - No `