📧 MagicMail - Email Business Suite for Strapi v5

Professional-grade multi-account email management with smart routing, OAuth 2.0 support, and complete security compliance — 100% free and open source

💚 Fully free & open source (MIT). Every feature is included for everyone — no license key, no activation, no paid tiers, and no usage limits.

🌟 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

Manage unlimited email accounts with live stats and real-time monitoring

Add Email Account - Step 1

Choose from 6 different email providers with OAuth 2.0 support

Add Email Account - Step 2

Configure SMTP settings or connect with OAuth

Add Email Account - Step 3

Complete setup with rate limits and test connection

Email Templates

Create and manage email templates with the visual designer

Email Designer

Drag-and-drop email editor with real-time preview

Template Version History

Track changes and restore previous template versions

Template Send Test

Test your templates before sending to production

Routing Rules & Templates

Define intelligent routing rules based on email type, recipient, subject

Email Analytics

Track email performance with detailed analytics and statistics

Code Integration

Simple API integration with your Strapi application

WhatsApp Messaging (NEW!)

MagicMail now includes FREE WhatsApp messaging - send messages directly from your Strapi application!

Why WhatsApp?

Feature	Email	WhatsApp
Open Rate	~20%	~98%
Delivery Speed	Minutes	Instant
Spam Folder Risk	High	None
User Preference	Declining	Growing
Cost	Varies	FREE

Quick Setup (4 Steps)

Navigate to Admin Panel -> MagicMail -> WhatsApp
Connect - Scan QR code with WhatsApp mobile app
Verify - Check connection status shows "Connected"
Send - Start sending messages programmatically!

Sending WhatsApp Messages

Method 1: Direct WhatsApp Send

// Send WhatsApp message directlyawaitstrapi.plugin('magic-mail').service('whatsapp').sendMessage('+491234567890',// Phone number with country code'Hello! This is a test message from MagicMail.');

Method 2: Unified Messaging API

// Send via unified API - auto-detects channelawaitstrapi.plugin('magic-mail').service('email-router').sendMessage({channel: 'whatsapp',// or 'email' or 'auto'phoneNumber: '+491234567890',message: 'Your order #12345 has been shipped!'});// Auto-detect: sends WhatsApp if phoneNumber provided, email if to providedawaitstrapi.plugin('magic-mail').service('email-router').sendMessage({channel: 'auto',phoneNumber: '+491234567890',// Has phone -> WhatsAppmessage: 'Shipping notification'});awaitstrapi.plugin('magic-mail').service('email-router').sendMessage({channel: 'auto',to: 'user@example.com',// Has email -> Emailsubject: 'Shipping Notification',message: 'Your order has been shipped!'});

Method 3: REST API

// POST /api/magic-mail/send-whatsappawaitfetch('/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!'})});// POST /api/magic-mail/send-message (unified)awaitfetch('/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!'})});

WhatsApp Use Cases

1. Email Fallback If email delivery fails, automatically send via WhatsApp:

// In Routing Rules, enable "WhatsApp Fallback"// Set "WhatsApp Phone Field" to 'phoneNumber'awaitstrapi.plugin('magic-mail').service('email-router').send({to: 'user@example.com',phoneNumber: '+491234567890',// Fallback phonesubject: '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:

// Example: Notify admin when email quota exceededconstadminPhone='+4917612345678';awaitstrapi.plugin('magic-mail').service('whatsapp').sendMessage(adminPhone,'[ALERT] Email quota exceeded for SendGrid account!');

3. Urgent Transactional Messages Send time-sensitive messages instantly:

// OTP/Verification codesawaitstrapi.plugin('magic-mail').service('whatsapp').sendMessage(userPhone,`Your verification code: 123456\n\nValid for 5 minutes.`);// Order updatesawaitstrapi.plugin('magic-mail').service('whatsapp').sendMessage(customerPhone,`Order #${orderId} is out for delivery!\nTrack: ${trackingUrl}`);

WhatsApp Status API

// Check connection statusconststatus=awaitstrapi.plugin('magic-mail').service('whatsapp').getStatus();// { isConnected: true, phoneNumber: '+49...', name: 'Business Account' }// Check if phone number is on WhatsAppconstexists=awaitstrapi.plugin('magic-mail').service('whatsapp').checkNumber('+491234567890');// { exists: true, jid: '491234567890@s.whatsapp.net' }

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.

npm install strapi-plugin-magic-mail
# or
yarn add strapi-plugin-magic-mail

Enable Plugin

Create or update config/plugins.ts:

exportdefault()=>({'magic-mail': {enabled: true,},});

Build & Start

npm run build
npm run develop

Add Your First Email Account

Navigate to Admin Panel → MagicMail → Email Accounts
Click "Add Account"
Choose your provider (Gmail OAuth, SMTP, etc.)
Fill in credentials
Click "Test" to verify
Done! 🎉

📧 Supported Email Providers

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

💡 How to Send Emails

Method 1: Strapi Native Email Service (Recommended!)

MagicMail automatically intercepts Strapi's email service - no code changes needed!

// This works in ANY Strapi plugin or controller:awaitstrapi.plugin('email').service('email').send({to: 'user@example.com',subject: 'Welcome to Our Platform!',text: 'Plain text version',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!

Method 2: Direct MagicMail API

For explicit control over account selection:

// Force a specific accountawaitstrapi.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 accounttype: 'transactional',priority: 'high',});

Sending with Attachments

awaitstrapi.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

// High priority emailawaitstrapi.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)awaitstrapi.plugin('magic-mail').service('email-router').send({to: 'subscriber@example.com',subject: 'Weekly Newsletter',html: '<h1>This Week'sUpdates</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:

Feature	Included
Visual Designer	✅
Unlimited Templates	✅
Drag & Drop + Mustache	✅
Import / Export	✅
Template Versioning	✅
Email Analytics	✅

📧 Creating Email Templates

1. Navigate to Email Templates Tab

Go to MagicMail → Email Templates in the admin panel.

2. Create New Template

Click "Create Template" and use the visual designer to build your email.

3. Add Variables with Mustache

Use Mustache syntax for dynamic content:

<h1>Welcome {{user.firstName}}!</h1><p>Thanks for joining {{company.name}}</p>

4. Save & Use

Each template gets a unique Reference ID (e.g., 100) that you use when sending.

💌 Sending Templated Emails

Method 1: Using Template ID

// Send email using templateawaitstrapi.plugin('magic-mail').service('email-router').send({to: 'user@example.com',templateId: 100,// Your template reference IDtemplateData: {user: {firstName: 'John',lastName: 'Doe',email: 'john@example.com',},company: {name: 'ACME Corp',url: 'https://acme.com',},orderNumber: '12345',orderTotal: '$199.99',},});// ✅ MagicMail will:// - Load template #100// - Render it with your data (Mustache)// - Route via smart routing// - Send via best account

Method 2: Via Strapi Email Service

// Also works with standard Strapi email service!awaitstrapi.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:

// Create routing rule: All marketing templates → SendGrid// Then just send:awaitstrapi.plugin('magic-mail').service('email-router').send({to: 'subscriber@example.com',templateId: 200,// Marketing category templatetemplateData: {offer: '50% OFF'},});// ✅ Automatically routes via SendGrid (based on category)

🔄 Template Versioning

Every time you save a template, a new version is created automatically:

// Get all versionsconstversions=awaitstrapi.plugin('magic-mail').service('email-designer').getVersions(templateId);// Restore old versionawaitstrapi.plugin('magic-mail').service('email-designer').restoreVersion(templateId,versionId);

📦 Import/Export Templates

Export all templates:

consttemplates=awaitstrapi.plugin('magic-mail').service('email-designer').exportTemplates();// Save to filefs.writeFileSync('templates.json',JSON.stringify(templates,null,2));

Import templates:

consttemplates=JSON.parse(fs.readFileSync('templates.json'));constresults=awaitstrapi.plugin('magic-mail').service('email-designer').importTemplates(templates);console.log(`Imported ${results.filter(r=>r.success).length} templates`);

🎨 Visual Designer Features

Powered by Unlayer Email Editor:

✅ 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

📊 Template Statistics

conststats=awaitstrapi.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// }

🚀 Best Practices

1. Use Template Categories

// Set category when creating template
category: 'marketing'// Auto-routes to marketing account

2. Test Templates Before Using

// Test render before sendingconstrendered=awaitstrapi.plugin('magic-mail').service('email-designer').renderTemplate(100,{user: {firstName: 'Test'}});console.log(rendered.html);// Preview HTML

3. Version Control

// Template version history is always enabled (free for everyone).

4. Organize with Tags

// Add tags to templates
tags: ['onboarding','welcome-series','v2']

🎯 Smart Routing Rules

Create intelligent routing rules to send emails through specific accounts based on conditions.

Example Use Cases

1. Route Marketing Emails via SendGrid:

Match Type: Email Type
Match Value: marketing
Target Account: SendGrid Marketing
Priority: 10

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

3. Route Password Reset Emails:

Match Type: Subject
Match Value: Password Reset
Target Account: Transactional SMTP
Priority: 8

Routing Priority

Rules are evaluated from highest to lowest priority (1-10):

Priority 10 = Evaluated first (most specific rules)
Priority 1 = Evaluated last (catch-all rules)

If no rule matches, the Primary Account is used.

🔐 Provider Setup Guides

Gmail OAuth Setup

1. Google Cloud Console

Go to console.cloud.google.com
Create a new project or select existing
Enable Gmail API
Create OAuth 2.0 Client ID
Add redirect URI: http://localhost:1337/magic-mail/oauth/gmail/callback
Copy Client ID and Client Secret

2. In MagicMail

Choose "Gmail OAuth" provider
Paste Client ID and Client Secret
Click "Connect with Google"
Authorize in popup
Done! ✅

Required Scopes:

https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/userinfo.email

Microsoft 365 OAuth Setup

1. Azure Portal

Go to portal.azure.com
Navigate to Azure Active Directory → App registrations
Click "New registration"
Name: "MagicMail"
Account type: "Accounts in this organizational directory only"
Copy Application (client) ID AND Directory (tenant) ID

2. Add Redirect URI

http://localhost:1337/magic-mail/oauth/microsoft/callback

3. API Permissions

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

4. Grant Admin Consent (Required!)

5. Create Client Secret

Certificates & secrets → New client secret
Copy the VALUE (not the Secret ID)
Store it securely!

6. In MagicMail

Choose "Microsoft OAuth" provider
Paste Tenant ID, Client ID, and Client Secret
Click "Connect with Microsoft"
Authorize
Done! ✅

Yahoo Mail OAuth Setup

1. Yahoo Developer Console

Go to developer.yahoo.com/apps
Click "Create an App"
Fill in app details

2. Add Redirect URI

http://localhost:1337/magic-mail/oauth/yahoo/callback

3. API Permissions

✅ Mail - Send and manage emails
✅ OpenID Connect - User authentication

4. In MagicMail

Choose "Yahoo Mail OAuth" provider
Paste Client ID and Client Secret
Click "Connect with Yahoo"
Done! ✅

SMTP Setup (Universal)

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)

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

Gmail App Password:

Google Account → Security → 2-Step Verification
App passwords → Generate
Use the 16-character password in MagicMail

Optional: DKIM Signing

For custom domains, you can add DKIM:

// In config field (advanced users):{dkim: {domainName: 'yourdomain.com',keySelector: 'default',privateKey: '-----BEGIN PRIVATE KEY-----\n...'}}

SendGrid Setup

1. Get API Key

Go to app.sendgrid.com
Settings → API Keys → Create API Key
Scope: Mail Send (Full Access)
Copy the API key

2. In MagicMail

Choose "SendGrid" provider
Paste API Key
Done! ✅

Mailgun Setup

1. Get API Key & Domain

Go to app.mailgun.com
Settings → API Security → Copy Private API Key
Sending → Domains → Copy your verified domain

2. In MagicMail

Choose "Mailgun" provider
Enter Domain (e.g., mg.yourdomain.com)
Paste Private API Key
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:

# Optional - Base URL for OAuth callbacksURL=https://yourdomain.com# Optional - Encryption key (auto-generated if not provided)ENCRYPTION_KEY=your-32-character-secret-key

Account Configuration

Each account can have:

Basic Settings:

Name (unique identifier)
Description
Provider type
From Email
From Name
Reply-To Email

Security:

OAuth credentials (encrypted)
SMTP credentials (encrypted)
API keys (encrypted)
DKIM configuration (optional)

Rate Limiting:

Daily email limit (0 = unlimited)
Hourly email limit (0 = unlimited)
Priority (1-10, higher = preferred)

Status:

Active/Inactive
Primary account designation

🎨 API Reference

Send Email (Standard Method)

awaitstrapi.plugin('email').service('email').send({to: 'recipient@example.com',from: 'sender@example.com',// Optional - uses account defaultsubject: '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 accountunsubscribeUrl: 'https://site.com/unsubscribe',// For marketing emailsattachments: [{filename: 'document.pdf',path: './path/to/file.pdf',contentType: 'application/pdf',},],});

Send Email (Direct MagicMail API)

awaitstrapi.plugin('magic-mail').service('email-router').send({to: 'user@example.com',subject: 'Test Email',html: '<p>Content</p>',accountName: 'Gmail OAuth',// Optional - force specific accounttype: 'transactional',priority: 'normal',});

Get All Accounts

constaccounts=awaitstrapi.plugin('magic-mail').service('account-manager').getAllAccounts();

Test Account

constresult=awaitstrapi.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

Go to Email Accounts
Click Test button on any account
Enter recipient email
Select test options:
- Priority: Normal / High
- Email Type: Transactional / Marketing / Notification
- Unsubscribe URL: (for marketing emails)
Choose test method:
- Test Direct - Direct send via account
- Test Strapi Service - Via Strapi email service (tests Email Designer compatibility)

Test via Code

// Test email with all security featuresawaitstrapi.plugin('magic-mail').service('account-manager').testAccount(accountId,'your-email@example.com',{priority: 'high',type: 'marketing',unsubscribeUrl: 'https://yoursite.com/unsubscribe',});

Verify Headers

To verify security headers are applied:

In Gmail:

Open email → Click ⋮ (three dots)
"Show original"

Look for:

X-Mailer: MagicMail/1.0
X-Priority: 1 (Highest)
Importance: high
List-Unsubscribe: <https://...>
Message-ID: <...>
DKIM-Signature: ...

In Outlook/Microsoft:

Email → File → Properties
View "Internet headers"
Should show "High Importance" with red exclamation mark

🔒 Security Compliance

Email Authentication

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

Regulatory Compliance

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

Security Validation

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)

📈 Analytics & Monitoring

Dashboard Stats

Global Stats:

Emails sent today (all accounts)
Total emails sent (lifetime)
Active accounts count

Per-Account Stats:

Emails sent today
Total emails sent
Rate limit usage (visual progress bars)
Last used timestamp
Success/failure rate

Email Logging

Every email is logged with:

Recipient
Sender
Subject
Account used
Status (sent/failed)
Timestamp
Email type
Error message (if failed)

Access logs via:

constlogs=awaitstrapi.entityService.findMany('plugin::magic-mail.email-log',{filters: {status: 'sent'},sort: {createdAt: 'desc'},limit: 100,});

🔄 Integration with Email Designer

MagicMail is fully compatible with strapi-plugin-email-designer-5!

How It Works

Install Email Designer:

npm install strapi-plugin-email-designer-5

Create email templates in Email Designer

Send via template:

// Email Designer internally uses strapi.plugin('email').service('email').send()// MagicMail automatically intercepts it!

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! 🎉

🚨 Troubleshooting

Email Not Received

1. Check Logs

# Look for errors in Strapi console
[magic-mail] ❌ Email send failed: ...

2. Check Account Status

Is the account marked as "Active"?
Test the account using the Test button
Check rate limits haven't been exceeded

3. Check Spam Folder

First emails from new accounts may land in spam
Check spam/junk folders
Mark as "Not Spam" to train filters

4. Verify Credentials

SMTP: Username and password correct?
Gmail: Using App Password (not regular password)?
OAuth: Tokens may have expired - reconnect

DMARC Failures

For Custom Domains:

Set up SPF record:
```
v=spf1 include:_spf.google.com ~all
```
Set up DKIM:
- Generate DKIM key pair
- Add public key to DNS
- Add private key to MagicMail SMTP config

Set up DMARC:

v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com

For OAuth Providers (Gmail, Microsoft, Yahoo):

✅ DKIM handled automatically
✅ SPF handled automatically
✅ DMARC should pass automatically

Rate Limit Errors

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

OAuth Connection Issues

Gmail OAuth:

Ensure Gmail API is enabled
Check redirect URI matches exactly
Clear browser cookies and try again

Microsoft OAuth:

Verify all 5 permissions are granted
Grant admin consent (required!)
Use correct Tenant ID
Check Client Secret hasn't expired

Yahoo OAuth:

Verify app is approved by Yahoo
Check API permissions are enabled

🏗️ Architecture

Plugin Structure

magic-mail/
├── admin/ # React Admin UI
│ └── src/
│ ├── components/
│ │ ├── AddAccountModal.jsx # Multi-step account setup
│ │ └── PluginIcon.jsx # Sidebar icon
│ └── pages/
│ ├── App.jsx # Main app with tabs
│ ├── HomePage.jsx # Email accounts page
│ └── RoutingRules.jsx # Routing rules page
├── server/ # Backend
│ └── src/
│ ├── bootstrap.js # Overrides Strapi email service
│ ├── controllers/
│ │ ├── accounts.js # CRUD for accounts
│ │ ├── oauth.js # OAuth flows
│ │ └── routing-rules.js # CRUD for routing rules
│ ├── services/
│ │ ├── email-router.js # Core routing logic
│ │ ├── account-manager.js # Account management
│ │ └── oauth.js # OAuth token exchange
│ ├── content-types/
│ │ ├── email-account/ # Account schema
│ │ ├── email-log/ # Email log schema
│ │ └── routing-rule/ # Routing rule schema
│ └── utils/
│ └── encryption.js # AES-256-GCM encryption
└── package.json

Data Flow

Email Request
↓
Strapi Email Service (intercepted!)
↓
MagicMail Email Router
↓
Routing Rules Engine
↓
Account Selection (priority/rules)
↓
Rate Limit Check
↓
Provider-Specific Sender
↓
Email Log & Stats Update
↓
Response

🎯 Use Cases

Multi-Tenant SaaS

// 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 Gmailawaitstrapi.plugin('email').service('email').send({to: 'customer@example.com',subject: 'Order Confirmation',html: '<h1>Order #456</h1>',customField: 'tenant-123',// Matches routing rule});

High-Volume Email Sending

// 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!

Marketing Campaigns

// Route marketing emails via SendGrid// Routing Rule:// Match Type: Email Type// Match Value: marketing// Target Account: SendGrid Marketingawaitstrapi.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

VIP Customer Emails

// Route VIP customers via a priority account// Routing Rule:// Match Type: Recipient// Match Value: @vip-domain.com// Target Account: Priority SMTP// Fallback Account: Gmail OAuthawaitstrapi.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

🔌 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

🌍 Production Deployment

Environment Variables

# Base URL (required for OAuth callbacks in production)URL=https://yourdomain.com# Database (Strapi default)DATABASE_CLIENT=postgresDATABASE_HOST=127.0.0.1DATABASE_PORT=5432DATABASE_NAME=strapiDATABASE_USERNAME=strapiDATABASE_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

OAuth Callback URLs

Update redirect URIs in your OAuth apps:

Gmail:

https://yourdomain.com/magic-mail/oauth/gmail/callback

Microsoft:

https://yourdomain.com/magic-mail/oauth/microsoft/callback

Yahoo:

https://yourdomain.com/magic-mail/oauth/yahoo/callback

Recommended Provider Settings

For Production Apps:

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

📚 Advanced Topics

Custom Routing Logic

Create complex routing rules:

// 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}

DKIM Configuration (Advanced)

For custom domains with SMTP:

1. Generate DKIM Keys:

openssl genrsa -out dkim_private.pem 1024
openssl rsa -in dkim_private.pem -pubout -out dkim_public.pem

2. Add to DNS:

default._domainkey.yourdomain.com TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA..."

3. Add to MagicMail SMTP Account:

// 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..."}}

Rate Limit Strategy

Best practices for high-volume sending:

// 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!

🤝 Contributing

We welcome contributions!

Found a bug?Open an issue

Have a feature idea?Start a discussion

Want to contribute code?

Fork the repo
Create a feature branch
Make your changes
Submit a pull request

License

MIT License

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:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

MagicMail is fully free and open source. Every feature is available to everyone with no license key, tier, activation, or usage limit.

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.

🙏 Credits

Built with:

Strapi v5 - Headless CMS
Nodemailer - SMTP client
Heroicons - Beautiful icons
styled-components - CSS-in-JS

Inspired by:

Professional email requirements
Multi-tenant application needs
Developer experience first

💬 Support

Need help?

⭐ Show Your Support

If MagicMail helps your project, please:

⭐ Star the repo on GitHub
📢 Share with your team
🐦 Tweet about it

🔒 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'spackage.json (not this plugin's — npm overrides only take effect on the root project):

{
"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"
}
}

After editing package.json, run:

rm -rf node_modules package-lock.json
npm install
npm audit

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.

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.

Made for the Strapi Community

MagicMail - Because email management should be magical, not painful.

Name		Name	Last commit message	Last commit date
Latest commit History 198 Commits
.dev		.dev
.github		.github
admin		admin
docs/plans		docs/plans
pics		pics
scripts		scripts
server		server
tests		tests
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.externals.json		.externals.json
.gitignore		.gitignore
.npmignore		.npmignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
strapi-admin.js		strapi-admin.js
strapi-server.js		strapi-server.js

Folders and files

Latest commit

History

Repository files navigation

📧 MagicMail - Email Business Suite for Strapi v5

🌟 Why MagicMail?

📸 Screenshots

Email Accounts Dashboard

Add Email Account - Step 1

Add Email Account - Step 2

Add Email Account - Step 3

Email Templates

Email Designer

Template Version History

Template Send Test

Routing Rules & Templates

Email Analytics

Code Integration

WhatsApp Messaging (NEW!)

Why WhatsApp?

Quick Setup (4 Steps)

Sending WhatsApp Messages

WhatsApp Use Cases

WhatsApp Status API

Integration with Magic-Link Plugin

Quick Start

Installation

Enable Plugin

Build & Start

Add Your First Email Account

📧 Supported Email Providers

💡 How to Send Emails

Method 1: Strapi Native Email Service (Recommended!)

Method 2: Direct MagicMail API

Sending with Attachments

Advanced: Priority & Marketing Emails

🎨 Email Designer Suite (NEW!)

✨ Features

📧 Creating Email Templates

💌 Sending Templated Emails

🎯 Template Categories

🔄 Template Versioning

📦 Import/Export Templates

🎨 Visual Designer Features

📊 Template Statistics

🚀 Best Practices

🎯 Smart Routing Rules

Example Use Cases

Routing Priority

🔐 Provider Setup Guides

Gmail OAuth Setup

Microsoft 365 OAuth Setup

Yahoo Mail OAuth Setup

SMTP Setup (Universal)

SendGrid Setup

Mailgun Setup

🛡️ Security Features

Encryption

Transport Security

Email Authentication

Content Security

Compliance Headers

📊 Features Overview

Multi-Account Management

Smart Routing Engine

Rate Limiting & Failover

Analytics & Monitoring

Testing Features

🔧 Configuration

Basic Setup (No .env Required!)

Account Configuration

🎨 API Reference

Send Email (Standard Method)

Send Email (Direct MagicMail API)

Get All Accounts

Test Account

🧪 Testing Your Setup

Test via Admin UI

Test via Code

Verify Headers