📧 MagicMail - Email Business Suite for Strapi v5

> Professional-grade multi-account email management with smart routing, OAuth 2.0 support, and complete security compliance


---

🌟 Why MagicMail?

Stop fighting with .env files and email configuration! MagicMail brings professional email management to Strapi v5 with:

- 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

$3

!Email Accounts Dashboard
Manage unlimited email accounts with live stats and real-time monitoring

$3

!Add Account Step 1
Choose from 6 different email providers with OAuth 2.0 support

$3

!Add Account Step 2
Configure SMTP settings or connect with OAuth

$3

!Add Account Step 3
Complete setup with rate limits and test connection

$3

!Email Templates
Create and manage email templates with the visual designer

$3

!Email Designer
Drag-and-drop email editor with real-time preview

$3

!Version History
Track changes and restore previous template versions (ADVANCED+)

$3

!Send Test
Test your templates before sending to production

$3

!Routing Rules
Define intelligent routing rules based on email type, recipient, subject

$3

!Email Analytics
Track email performance with detailed analytics and statistics

$3

!Code Snippet
Simple API integration with your Strapi application

---

WhatsApp Messaging (NEW!)

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

$3

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

$3

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!

$3

Method 1: Direct WhatsApp Send

``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.'
);
`

Method 2: Unified Messaging API

`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!'
});

// 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'
});

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!'
});
`

Method 3: REST API

`javascript
// POST /api/magic-mail/send-whatsapp
await fetch('/api/magic-mail/send-whatsapp', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
phoneNumber: '+491234567890',
message: 'Hello from MagicMail!'
})
});

// POST /api/magic-mail/send-message (unified)
await fetch('/api/magic-mail/send-message', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
channel: 'whatsapp',
phoneNumber: '+491234567890',
message: 'Order confirmed!'
})
});
`

$3

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

`javascript
// In Routing Rules, enable "WhatsApp Fallback"
// Set "WhatsApp Phone Field" to 'phoneNumber'

await strapi.plugin('magic-mail').service('email-router').send({
to: 'user@example.com',
phoneNumber: '+491234567890', // Fallback phone
subject: 'Important Update',
html: '

Update

',
type: 'transactional'
});

// If email fails -> auto-sends via WhatsApp!
`

2. Admin Notifications
Get instant WhatsApp alerts for critical events:

`javascript
// Example: Notify admin when email quota exceeded
const adminPhone = '+4917612345678';

await strapi.plugin('magic-mail').service('whatsapp').sendMessage(
adminPhone,
'[ALERT] Email quota exceeded for SendGrid account!'
);
`

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

`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}
);
`

$3

`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' }
`

$3

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

$3

`bash
npm install strapi-plugin-magic-mail


or


yarn add strapi-plugin-magic-mail
`

$3

Create or update config/plugins.ts:

`typescript
export default () => ({
'magic-mail': {
enabled: true,
},
});
`

$3

`bash
npm run build
npm run develop
`

$3

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

---

📧 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

$3

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

`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',
html: '

Welcome!

Thanks for signing up!

',
});

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

$3

For explicit control over account selection:

`javascript
// Force a specific account
await strapi.plugin('magic-mail').service('email-router').send({
to: 'customer@example.com',
subject: 'Order Confirmation',
html: '

Your Order #12345

',
accountName: 'SendGrid Marketing', // Force this account
type: 'transactional',
priority: 'high',
});
`

$3

`javascript
await strapi.plugin('email').service('email').send({
to: 'customer@example.com',
subject: 'Invoice #12345',
html: '

Invoice Attached

',
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!

$3

`javascript
// High priority email
await strapi.plugin('magic-mail').service('email-router').send({
to: 'vip@example.com',
subject: 'Urgent: Action Required',
html: '

Important Update

',
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: '

This Week's Updates

',
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!

$3

| Feature | FREE | PREMIUM | ADVANCED |
|---------|------|---------|----------|
| Visual Designer | ✅ Basic builder | ✅ + template library | ✅ Pro components |
| Templates Included | 25 | 100 | 500 |
| Drag & Drop + Mustache | ✅ | ✅ | ✅ |
| Import / Export | ✅ | ✅ | ✅ |
| Template Versioning | ❌ | ✅ | ✅ |
| Analytics | ❌ | Basic insights | Advanced dashboard |
| A/B Testing | ❌ | ❌ | ✅ |

$3

1. Navigate to Email Templates Tab

Go to MagicMail → Email Templates in the admin panel.

2. Create New Template

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

3. Add Variables with Mustache

Use Mustache syntax for dynamic content:

`html


Welcome {{user.firstName}}!

Thanks for joining {{company.name}}

`

4. Save & Use

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

$3

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',
},
});

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

`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',
},
});
`

$3

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)
`

$3

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

`javascript
// Get all versions
const versions = await strapi
.plugin('magic-mail')
.service('email-designer')
.getVersions(templateId);

// Restore old version
await strapi
.plugin('magic-mail')
.service('email-designer')
.restoreVersion(templateId, versionId);
`

$3

Export all templates:

`javascript
const templates = await strapi
.plugin('magic-mail')
.service('email-designer')
.exportTemplates();

// Save to file
fs.writeFileSync('templates.json', JSON.stringify(templates, null, 2));
`

Import templates:

`javascript
const templates = JSON.parse(fs.readFileSync('templates.json'));

const results = await strapi
.plugin('magic-mail')
.service('email-designer')
.importTemplates(templates);

console.log(Imported ${results.filter(r => r.success).length} templates);
`

$3

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

$3

`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: 3, // FREE tier limit
// remaining: 0 // Upgrade needed!
// }
`

$3

1. Use Template Categories
`javascript
// Set category when creating template
category: 'marketing' // Auto-routes to marketing account
`

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
`

3. Version Control
`javascript
// ADVANCED+: Keep version history
// Automatically enabled for ADVANCED and ENTERPRISE licenses
`

4. Organize with Tags
`javascript
// 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.

$3

1. Route Marketing Emails via SendGrid:
`
Match Type: Email Type
Match Value: marketing
Target Account: SendGrid Marketing
Priority: 10
`

2. Route VIP Customers via Premium SMTP:
`
Match Type: Recipient
Match Value: @vip-customers.com
Target Account: Premium 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
`

$3

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

$3

1. Google Cloud Console
1. Go to 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

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

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

---

$3

1. Azure Portal
1. Go to 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
`

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
1. Certificates & secrets → New client secret
2. Copy the VALUE (not the Secret ID)
3. Store it securely!

6. In MagicMail
1. Choose "Microsoft OAuth" provider
2. Paste Tenant ID, Client ID, and Client Secret
3. Click "Connect with Microsoft"
4. Authorize
5. Done! ✅

---

$3

1. Yahoo Developer Console
1. Go to developer.yahoo.com/apps
2. Click "Create an App"
3. Fill in app details

2. Add Redirect URI
`
http://localhost:1337/magic-mail/oauth/yahoo/callback
`

3. API Permissions
- ✅ Mail - Send and manage emails
- ✅ OpenID Connect - User authentication

4. In MagicMail
1. Choose "Yahoo Mail OAuth" provider
2. Paste Client ID and Client Secret
3. Click "Connect with Yahoo"
4. Done! ✅

---

$3

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:
1. Google Account → Security → 2-Step Verification
2. App passwords → Generate
3. Use the 16-character password in MagicMail

Optional: DKIM Signing

For custom domains, you can add DKIM:
`javascript
// In config field (advanced users):
{
dkim: {
domainName: 'yourdomain.com',
keySelector: 'default',
privateKey: '-----BEGIN PRIVATE KEY-----\n...'
}
}
`

---

$3

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

2. In MagicMail
1. Choose "SendGrid" provider
2. Paste API Key
3. Done! ✅

---

$3

1. Get API Key & Domain
1. Go to app.mailgun.com
2. Settings → API Security → Copy Private API Key
3. Sending → Domains → Copy your verified domain

2. In MagicMail
1. Choose "Mailgun" provider
2. Enter Domain (e.g., mg.yourdomain.com)
3. Paste Private API Key
4. Done! ✅

---

🛡️ Security Features

$3

- ✅ AES-256-GCM encryption for all credentials
- ✅ No plain text passwords in database
- ✅ OAuth tokens encrypted at rest
- ✅ Secure token refresh mechanism

$3

- ✅ TLS 1.2+ enforced (SMTP)
- ✅ Certificate verification enabled
- ✅ HTTPS only for API providers

$3

- ✅ DKIM signing (optional for SMTP, automatic for OAuth)
- ✅ SPF validation support
- ✅ DMARC compliance - All providers pass DMARC checks
- ✅ Proper Message-ID generation (RFC 5322)

$3

- ✅ XSS prevention - No